Early Bird Registration for DrupalCon Portland 2024 is open! Register by 23:59 PST on 31 March 2024, to get $100 off your ticket.
Problem/Motivation
While getting drupal 8 ready, we need to have default config settings yml files, and we are making the saved active config files match in format so that a diff between them means that a change in configuration has actually happened. We dont want a diff to show a diff if the format is just different but the data is the same.
There is no coding standards for config yml yet.
Proposed resolution
Eventually make a standards doc page to put http://drupal.org/coding-standards
Remaining tasks
- Gather the conventions that are currently being used and document them.
- Discuss what the standard will be and link to related issues.
User interface changes
No UI changes.
API changes
No api changes.
Related Issues
- #1930226: Update integer/boolean values with quotes in configuration files.
- #1938580: [META] Make active config save format match the default yml file (order and quotes)
- #1602106: Document default configuration files
- #1653026: [META] Use properly typed values in module configuration
- http://drupal.org/node/1905070#codestyle (schema standards)
Comments
Comment #1
jhodgdonIt seems like if the goal is that a written-out config file and the one saved in core are the same, the solution would be to make sure before we commit any YML files to core, we have the core-writer-of-yml function write them out? :)
Does the core writer preserve comments that were in the original YML though (I think at least that YML can have comments)?
And is this issue about making a standard for the core-writer-of-yml functionality, or just about making a standard for writing YML documents?
Comment #2
YesCT CreditAttribution: YesCT commentedI'd suggest this issue is about making a standard for the core-writer-of-yml functionality.
And that we start by just writing in words what that is doing right now.
For example:
single quoting strings with whitespace
ordering items by.. (how does it order)?
indenting by 2 spaces and not tabs
how does it represent empty lists (sequences)
etc.
linking to the (api) page that is the writer code so it is easy to find.
does it: do keyed lists like
book: '0'
or just not list it
does it do
book: 'book'
or just
- book
I think comments are stripped out from the default config when the active config is written. And then diffs are done on if config has changed between the old active config and the new active config (or maybe staged config) and none of those have comments. (I'm not sure if #1602106-4: Document default configuration files is still accurate.)
This issue, the standard, would be helpful for people who are writing the config writer to make sure it is writing in the format we want it to. I think there might not be just one config writer, but different ones for different areas. For example,
#1933548: Book allowed_types settings repetitive and in under certain conditions can change unexpectedly
changed
book: book
to
- book
but then I ran into
article: article
in #1948884-14: Create configuration schemas for block and custom_block modules 7.
Maybe that is a problem with how the data is stored and not the config writer... but I only notice it when looking at the yml.
We might also want some kind of check list.. like:
if you change the way data is stored:
check the config written to the yml files if it matches (this) standard
write also the default config, add back comments and replace the default config yml file
check the schema to make sure changes to the way data is stored are also reflected in the schema.
Comment #3
jhodgdonThis doesn't sound like a coding standard to me, exactly. Our coding standards are about syntax, whitespace, and other mechanical issues in how to write readable, maintainable code....
And I'm a bit confused. Why would people be writing new writer-of-config classes anyway?
Comment #4
Gábor HojtsyYeah, well, the standard is "whatever is output by the core yml writer when you create the yml with core". But if we don't have the rules of that written down, then the code review for shipped configuration would be to go and generate it yourself and see if it matches whatever in the patch. May be more tedious then looking through a checklist of things and visually acknowledging it would match? Are you advocating not documenting the format standards but instead of rely on dynamic verification only?
Comment #5
jhodgdonBut... As discussed above, we probably want the files shipped with core to be hand-written and contain comments. So they're never going to match the machine-generated output, which strips the comments.
This other issue is specifically about standards for documenting the hand-written YML files:
#1602106: Document default configuration files
And when I asked above, I was told that this issue is about standards for the machine-written YML files only...
So... Let's figure out what the issue is about, and if it's not applicable to hand-written YML files then I think the docs should go on the interface that all YML writers implement (assuming there is one) (since it's part of the interface contract in that case, right?).
Comment #6
Gábor HojtsyI'm surprised we want to document shipped config because we also want diffs for config changes to be meaningful. If the order of items, type of items and inclusion/lack of comments is not the same, then the diffs of changed/staged config will be pretty overwhelming and not very indicative of actual changes.
Comment #7
jhodgdonThe question of putting docs into shipped config should be discussed on that other issue.
Comment #8
Gábor HojtsyAll right, so the question in this issue is whether to impose/document any standards on hand-written .yml (excluding thinking of comments) to make it easier to review although it woud be re-saved into active config (in a possibly different format) is worthwhile. Or people should write their hand written shipped config in whatever style and we don't care about that.
Comment #9
Gábor HojtsyDiscussion from IRC:
(ended there).
Comment #22
smustgrave CreditAttribution: smustgrave at Mobomo commentedNot sure I follow this policy, all config is different so what's the goal?