Add more info on deploying configuration changes

docs/webmaster-modules.md

@@ -30,6 +30,11 @@ Adding new configuration for modules not in DPL CMS is more safe, but
 you should look out for dependencies. If a configuration depends on a
 particular node type or field being available for instance.
 
+In general, you should get more familiar with the configuration YAML
+you're putting into your module, than you're used to from general
+Drupal configuration management, and know exactly why you need each
+one.
+
 ### Overview
 
 Configuration handling in webmaster modules consists of three parts:
@@ -95,14 +100,56 @@ to be instantiated. Again, you can just copy the code from
 Keeping the module configuration up to date might pose some
 challenges.
 
-Just changing the configuration is often simple, just do the
-modifications, export and copy the changed files.
+#### Module configuration changes
+
+Changing the configuration is often simple, just do the modifications,
+export and copy the changed files. You'll need to add an update hook
+that triggers a configuration import in order for the changes to take
+effect when the module is updated.
+
+#### DPL CMS configuration changes
 
 Merging in changes from DPL CMS could be problematic, as applying the
 configuration changes from the module that's based on the previous
-version of DPL CMS might throw a `ConfigImporterException` and leave
-you without any of the module changes. In this case you can either
-rebuild the configuration in the administration interface and export
-it fresh, or by careful inspection of diffs apply the needed changes
-by hand to the YAML files. Deployment of such a change is left as an
-exercise for the reader...
+version of DPL CMS might throw a `ConfigImporterException` and make
+the deployment fail.
+
+The hard failure modes of this sounds bad, but the deployment policy
+of first rolling out new DPL CMS releases to the libraries
+`moduletest` environments should catch these issues before they hit
+production.
+
+When this happens, you can either rebuild the configuration in the
+administration interface and export it fresh, or by careful inspection
+of diffs apply the needed changes by hand to the YAML files.
+
+Even if importing the configuration doesn't show any errors, the fact
+that the module in effect replaces part of the DPL CMS configuration
+might cause upstream changes to get lost, so you should occasionally
+check for this. This can be done by doing a configuration export and
+inspecting the diff of the configuration changes for changes that's
+unrelated to the modules changes.
+
+Deploying the fixed version requires some extra care. Obviously, you
+cannot update the module after updating DPL CMS, as the upgrade will
+fail when trying to apply the old changes from the module to the new
+DPL CMS configuration. So you'll have to update the module first, but
+you should not trigger an configuration import when doing so, as that
+would likely fail just as bad when trying to overlay the modules new
+configuration on the old DPL CMS configuration (so no `hook_update_N`
+for this version of the module).
+
+Test it out first on `moduletest`.
+
+1. Ask the hosting team to get `moduletest` reverted to the previous
+DPL CMS version and database and files synced with production.
+2. Update the module.
+3. Ask the hosting team to upgrade the `moduletest` environment.
+
+If it works, you can update the module in production and ask for
+upgrading production. Make the library aware that, in the timespan
+between updating the module and updating DPL CMS, they cannot do
+anything that triggers a configuration import. In practice this should
+translate to "don't upload any webmaster modules", as that should be
+about the only thing apart from a DPL CMS update that triggers an
+import.