- Issue created by @krystalcode
- 🇳🇿New Zealand quietone
Fixes are made on on 11.x (our main development branch) first, and are then back ported as needed according to our policies.
In PHP, and most other languages, it's common to add inline comments that add context or explanations related to the lines of code that follow. This is very important so that other developers have that information when reading other developers' code, or even the authors themselves if they revisit the code later. Not having adequate information can lead to regressions when code is changed.
// This code does this because of that.
$my_var = my_function($my_arg);
YAML syntax supports comments as well
# We temporarily disable X feature until Y problem is solved.
x_feature: false
However, configuration exports do not maintain the comments in the resulting files.
Developers pretty commonly export configuration and just commit to vcs without wanting to bother reverting the comment removals - understandably, who wants to have to do that every time? Most commonly, they don't even bother to read the removed comments and evaluate whether there's a reason for keeping them - because hey, who puts comments in configuration files. The result is that important information is lost.
The potential impact of this though should not be underestimated. Configuration is code as well and it controls code. Changing a simple value e.g. from true to false can have far reaching changes, even uninstall an entire module and potentially cause data loss, for example, or show/hide a checkout pane in a commerce website etc, enable/disable integrations with external systems etc. In the example above, a new developer comes in a year later and enables feature X because the reason for disabling it is not known, causing a regression.
I find pretty frequently the need to document why certain configuration properties are given the values they are. The only place where this can be documented that is relevant is inline, in the YAML configuration file. Same way that you can create docs and readme files for a project, but none of these can replace inline PHP comments. Because when another developer comes to work on that piece of code, they may not even be aware that there is that other place somewhere else that contains relevant information to go look for it there.
In short, if comments are not available where they are most relevant i.e. inline in the YAML configuration file, it is as if they don't exist and sooner or later bad things happen.
I'd like to investigate the possibilities for maintaining comments on the generated configuration files.
- Add a comment on any configuration file.
- Run drush cex
- Notice that the comment is gone.
As a probably low-hanging fruit that should be doable but might have a big impact, do not regenerate files that have not changed. Currently, drush cex seems to actually recreate the files on the disk for all configuration objects. Is there a reason for this? This is important in this context because if I have comments in 10 files, every time I export configuration all of them are lost and I have to revert them all in Git to keep it clean - even if the configuration changes that I exported are not on any of those files. But if the export does not touch them unless they have been changed, then 95% of the cases there's nothing extra to do in my workflow.
That might be good enough if full solutions are too complicated.
A full solution would be to understand where the changes have happened, including adding or removing lines, without losing comments. There should be tools for this, either git style tools or even in PHP e.g. code beautifiers make changes including breaking a line into multiple lines without removing inline comments.
- Investigate possibilities
- Implement solution
Active
11.0 🔥
Last updated
Fixes are made on on 11.x (our main development branch) first, and are then back ported as needed according to our policies.