I'm over at #1497310: Convert statistics settings to configuration system and writing out a YAML file by hand. A lot of these keys are truly non-sensical-looking without any context, so it occurs to me we might want to develop a documentation standard for default configuration files, so that you have a canonical reference to go back to and see what's involved there.

Here's a sample YAML file:

name: large
effects:
    image_scale_480_480_1:
        name: image_scale
        data:
            width: '480'
            height: '480'
            upscale: '1'
        weight: '0'
        ieid: image_scale_480_480_1

Here's a proposal of what a documented one might look like:

# Machine name of image style.
name: large

# List of image effects to apply during transformation.
effects:
    image_scale_480_480_1:
        name: image_scale
        data:
            width: '480'
            height: '480'
            upscale: '1'
        weight: '0'
        ieid: image_scale_480_480_1

Nothing too crazy. Top-level elements only. Just a line or so to explain to others what they're about. What say you?

Comments

gdd’s picture

gdd
he/him
Primary language English
Location Portland, OR
CreditAttribution: gdd commented

I don't have any issue with this, as long as we realize that once these actually get installed the comments will disappear. Once the YAML is parsed, the comments will be stripped and thus can not be written back out to the file system. I wouldn't even mind internal comments. For instance, in the example above, describing how the machine name is generated (although that is going away but whatever.)

webchick’s picture

webchick
she/they
Primary language English
Location Vancouver 🇨🇦
CreditAttribution: webchick commented

Yep, totally realize that the defaults only get documented. I think this is fine, and see it as equivalent to the tpl.php files in system module shipping with like 500K of documentation of what all the variables do at the top. In your custom theme's tpl.php file you'll probably never add all of those docs, but they're really nice to have over there as a reference.

I.. have no idea how the machine name is generated, but yes! Agreed that'd be a handy thing to have. :)

alexpott’s picture

alexpott
he/they
Primary language English
Location 🇪🇺🌍
CreditAttribution: alexpott commented

This probably means that core or contrib will have to provide a nice way to diff these files as a command line diff will no longer work.

Being able to diff config files will be a useful way of seeing what's changed from a default implementation. This will be very useful when one arrives on a project some time after it's started :)

sun’s picture

sun
Primary language German
Location Karlsruhe
CreditAttribution: sun commented

@alexpott: Nope, the default configuration files are loaded, decoded/parsed, and re-encoded and saved, i.e., completely rewritten, before they are saved to any storage engine. Diffing against the very original default module configuration is not foreseen at this point, but could be added later on. In general, the mechanism for doing that is #1447686: Allow importing and synchronizing configuration when files are updated

alexpott’s picture

alexpott
he/they
Primary language English
Location 🇪🇺🌍
CreditAttribution: alexpott commented

@sun: that's why I wrote:

This probably means that core or contrib will have to provide a nice way to diff these files

I was not raising the ability to diff and as reason not to comment. I'm fully aware that config parses and rewrites default configuration files.

To review that suggested comment format. @webchick makes sense to me. This will definitely prove very useful to people who want to understand how a module is configured. One area of concern is that we might see a lot of duplicated information from the configuration form. For example, the Yaml file for system.rss-publishing could look like this (not sure if this is a good or bad thing):

# Description of your site, included in each feed.
feed_description: ''

# Default number of items to include in each feed.
feed_default_items: '10'

# Global setting for the default display of content items in each feed.
feed_item_length: fulltext
jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

This looks like an excellent idea in general!

Regarding #5, I think we probably don't need to provide one documentation line per setting -- settings could be grouped (e.g., "Default settings for all feeds on the site"), and if the setting names are obvious, maybe they don't need documentation (especially if the documentation exactly duplicates the setting names -- for instance feed_default_items seems pretty obvious what it is)?

sun’s picture

sun
Primary language German
Location Karlsruhe
CreditAttribution: sun commented

In general, in all the config conversion issues we heavily improved the old variable names to be much more self-descriptive. So I'm not really sure how much documentation is actually needed for the keys in config files.

IMHO, if we start to do this, then we need to set very good examples of what makes sense to document and what doesn't. For example, adding comments along the lines of this:

# This is the label, shown in the user interface.
label = Article

...would be 100% silly/nonsensical.

I guess it would be OK to document keys and perhaps also sub-key structures that are not self-descriptive.

OTOH, I fear we'd duplicate the documentation that already lives in PHP code (or in the user interface) for many things.

And in general, there's the open question of whether anyone will actually look into the default config files in the first place... As soon as you can see your active configuration in files (with #1702080: Introduce canonical FileStorage + (regular) cache), I know for sure that I'm looking into those files, but not really into the default config files that are scattered over the entire system in various $module/config subdirectories.

webchick’s picture

webchick
she/they
Primary language English
Location Vancouver 🇨🇦
CreditAttribution: webchick commented

Well, as a module evaluator, I would definitely look at the default YML files in order to get a sense of what configuration settings are there and what they do. It'd be akin to me scanning hook_menu() and looking at the admin form callbacks, which I currently do today.

I don't know if I agree that "obvious" documentation should be missing documentation, though. We always document all database columns in hook_schema(), for example, even if it's a column called "title" in a table called "node." We can't know that "label" is universally understood to be "This is the label, shown in the user interface." by people new to Drupal. So I would err towards documenting everything all the time if we chose to go down this path.

YesCT’s picture

YesCT CreditAttribution: YesCT commented

related: #1948284: [policy no patch] config save format and default yml file format and coding standards

YesCT’s picture

YesCT CreditAttribution: YesCT commented

An example of a yml config default file using inline # comments. #1942144: Make Language module active config save format match the default yml file.
I'm not sure if that is good or bad.

alexpott’s picture

alexpott
he/they
Primary language English
Location 🇪🇺🌍
CreditAttribution: alexpott commented
Issue summary: View changes
Status: Active » Closed (won't fix)

I'm closing this issue because config schema describe all configuration and it is entirely possible to have comments in default YAML files as pointed out by @YesCT