Document consequences of contrib changing config schema without core's API supporting config version tracking

But what about contrib? Can a contrib module make changes during its alpha or beta releases, like Drupal core has done many times during its alphas and betas? Can a contrib module make changes between its 8.x-1.x and 8.x-2.x versions? If it does make such changes, what does it need to do and/or what do other modules that provide default config for it, implement potential overrides for it (such as via Domain module), etc. need to do?

As per our discussions given that #1977498: Add version tracking for configuration schema and data is not resolved, core and contrib alike should only make additive changes to schema, it should not make backwards incompatible changes in any way whatsoever. Eg. if a views plugin need to make backwards incompatible changes to their settings, they need to modify their plugin_id and add schema under the new plugin_id from then on. If a module needs to change its modulename.settings file in a backwards incompatible compatible way, it will need to change the config name to something else, eg. modulename.configuration or something else. Adding keys and stopping the use of some keys is fine, so if a views plugin needs to use now new keys for its settings and abandon old ones, that is fine too.

This is my understanding basically.

I think we should add documentation once #2521776: Update documentation for hook_update_N() for Drupal 8 lands.

It would be good to wait for that one please. :)

@effulgentsia: we both decided to make config schema static, so we can parse it without the presence of the runtime which generated it and to not version schema or config. That means that if we have a copy of schema X and a copy of config Y that should be valid according to schema X, they need to match regardless of what "version" of config Y is that schema for. We only have the keys no versions to contextualize them.

Does it come down to:

Can a contrib module make changes during its alpha or beta releases, like Drupal core has done many times during its alphas and betas?

Yes with the caveat that sites/modules with a dependency on that module may break if the change is not backwards compatible with existing config.

Can a contrib module make changes between its 8.x-1.x and 8.x-2.x versions?

Only backwards compatible changes.

Now that #2521776: Update documentation for hook_update_N() for Drupal 8 has landed I also think this issue should perhaps give examples of how to do hook_update_N() config changes.

That sounds like a good idea.

So we have several places that some of the documentation for this issue can go:

a) There's a new "Update API" topic on api.drupal.org:
https://api.drupal.org/api/drupal/core!lib!Drupal!Core!Extension!module....

b) It's kind of an abbreviated version of the d.o documentation:
https://www.drupal.org/developing/api/8/update
which has several child pages and gives several examples.

c) Then there's the documentation for hook_update_N() itself:
https://api.drupal.org/api/drupal/core!lib!Drupal!Core!Extension!module....
(and some other update-related hooks and classes that are listed on the Update API api.d.o topic page). This page has a function body with a couple of simple examples.

So can we get an actionable list of what we actually need to document that's missing, and where the docs for each should go (some of which in more than one place I'd imagine -- everything should get onto the d.o docs, and most should go somewhere in the API docs as well I would think)? So far I think it is a bit nebulous.

And regarding the discussion from the past few comments... It seems like both Core and Contrib can make config changes that are not backwards compatible *if they supply an update function* that converts the config, right? There would still possibly be problems if another module was depending on the config structure, but that is always the case for any kind of API or data model change. I don't see how config is much different from that... It seems like if a module makes an API or data model change of any sort, and something's depending on it being the way it was, that's going to break. So if they go from the 8.x-1.x to 8.x-2.x version they can make those changes (with update functions) to allow dependent modules time to catch up to be compatible with the new way of doing things.

Right?

Anyway, so far I'm not seeing anything new in this issue that needs documenting that is not in the existing docs, but let's discuss!

It seems like both Core and Contrib can make config changes that are not backwards compatible *if they supply an update function* that converts the config, right?

Not quite, exported config will also break. For default config in a module or install profile, we can say that's 'code' and the same as another API change.

However we also export config for deployment, and there are situations that could break too - i.e. export config from staging, update contrib module on both staging and production, try to import config to production - it'd break because the config was exported before the update ran.

The other thing that can break is that config overrides also get stored, and we have no way to update the overrides to point to the new schema. So for example, renaming a config key that was being tweaked per-domain the overrides would just get lost, same with translations.

OK, then what do we want to say, that you can never make these changes, or that if you do, you'd better put something in your release notes?

It seems like both Core and Contrib can make config changes that are not backwards compatible *if they supply an update function* that converts the config, right?

One more point that @catch did not mention, we did not version neither schema nor config, and we designed them so schema is used to parse config independent of the runtime site (eg. on localize.drupal.org). Due to the combination of these, if there is not a 1-1 relationship between config and schema (ie. there are incompatible schemas for the same config), we could not tell which one to use (due to lack of versioning). This was deemed acceptable because people are supposed to only make backwards incompatible changes and they can just make up new config keys and plugin IDs if they need/want for backwards incompatible changes.

OK, then what do we want to say, that you can never make these changes, or that if you do, you'd better put something in your release notes?

The release notes will not help with static code analysis incompatibility.

No, plus no one ever reads release notes.

So, I have no idea what we would to say here. I mean, contrib maintainers hopefully know in general that changing their API or data model can be problematic if any other module depends on their module, which they have little control over. I don't know that we need to make a bigger deal out of documenting this for Config than for any other API or data model changes -- the issues are pretty much the same.

Updating tag.