Config split doc improvement

https://www.drupal.org/node/2898015

# CONFIG SPLIT USE CASES

# CASE: Enable modules in production and not in staging and visa versa. Have some system settings different in production then in staging.

Assumptions:

  1. Your config directory is set to $config_directories['sync'] = '../config/sync'
  2. You have two environments: staging and production.
  3. You have a different settings.php file in production than in staging.
  4. The Drupal core module Configuration Manager is enabled.
  5. You want to have the module Google Analytics enabled in production and not in staging and the module Devel enabled in staging and not in production.
  6. You want to set Error logging to all in staging and to none in production.
  7. You do not yet have installed those modules. If you have you should be able to recognize where to do some things different.
  8. You use drush, composer and git. Perhaps not really required but this use case uses them which explains the approach.
  9. It might be possible to do it more efficient, but when following these steps it works...

Steps

  1. Copy your production site to staging, except for the settings.php file of course.
  2. In staging environment add to settings.php:

    $config['config_split.config_split.production']['status'] = FALSE;
    $config['config_split.config_split.staging']['status'] = TRUE;

  3. In production environment add to settings.php:$config['config_split.config_split.production']['status'] = TRUE;
    $config['config_split.config_split.staging']['status'] = FALSE;
  4. In staging environment:
    1. install the Configuration Split module and enable it.
    2. install but not enable the modules Google Analytics and Devel.
    3. do drush cex
    4. Deploy to production to get those modules in the code base there to.
  5. In production environment:
    1. do drush cim This will install and enable the module Config Split in production environment.
    2. enable the module Google Analytics
    3. set the settings for Error logging (admin/config/development/logging).
    4. create a config split setting with machine name production, with a complete split for the module Google Analytics and a configuration items split for system.logging. De-activate this config split and save the settings.
    5. Create the directory ../config/production. Where .. represents your Drupal project root directory.
    6. Clear all cache to make the changes in the settings.php effective. You can check this at admin/config/development/configuration/config-split. The production split is active (overwritten).
    7. do drush cex
      You should get something like:

[notice] Differences of the active config to the export directory:
+------------+--------------------------------------+-----------+
| Collection | Config                               | Operation |
+------------+--------------------------------------+-----------+
|            | config_split.config_split.production | Create    |
|            | google_analytics.settings            | Create    |
|            | core.extension                       | Update    |
|            | user.role.authenticated              | Update    |
+------------+--------------------------------------+-----------+

The .yml files in your export directory (../config/sync) will be deleted and replaced with the active config. (yes/no) [yes]:

That is exactly what we want so accept this.
All config files are in ../config/sync except for the module config file and system.performance.yml and system.logging.yml are only in ../config/production.
The file ../config/sync/core.extension.yml does not mention the module.
The new file ../config/sync/config_split.config_split.production.yml does mention the module.
  f. Now commit the changes in production to your Git repo and Pull them to your staging environment.
06. In staging:
  a. do drush cim
     You should then get something like:
          Importing.
          +------------+--------------------------------------+-----------+
          | Collection | Config                               | Operation |
          +------------+--------------------------------------+-----------+
          |            | config_split.config_split.production | Create    |
          |            | user.role.authenticated              | Update    |
          |            | system.logging                       | Delete    |
          +------------+--------------------------------------+-----------+

      Accept this. Clear the cache and check your staging website.
      Google Analytics should not be enabled. And because the system.logging config is missing this is not set at all. This is not a problem for this situation, but might be an issue for other modules. So be carefull when you create splits like this.
  b. Now set the Error logging to All messages and enable the contrib module Devel.
  c. Create a new Config split with machine name staging and folder ../config/staging. And de-activate it.
  d. Create a complete split for Devel and a configuration split for system.logging.
  e. Create the directory ../config/staging.
  f. Clear all cache to be sure and check if the Staging split is active (overwriten).
  g. Do drush cex
     You should get something like this:
              [notice] Differences of the active config to the export directory:
          +------------+-----------------------------------+-----------+
          | Collection | Config                            | Operation |
          +------------+-----------------------------------+-----------+
          |            | devel.settings                    | Create    |
          |            | devel.toolbar.settings            | Create    |
          |            | system.logging                    | Create    |
          |            | system.menu.devel                 | Create    |
          |            | config_split.config_split.staging | Create    |
          |            | core.extension                    | Update    |
          +------------+-----------------------------------+-----------+

      That is correct so accept it.

      All config files are still in ../config/sync except for the devel and Google Analytics modules config files and system.logging.yml.
      The file ../config/sync/core.extension.yml does not mention the devel module either.
      The new file ../config/sync/config_split.config_split.staging.yml does mention the module.

  h. Now you can deploy your staging site again to production.
  i. In production you do drush cim
     You should then get this:

            Importing.
            +------------+-----------------------------------+-----------+
            | Collection | Config                            | Operation |
            +------------+-----------------------------------+-----------+
            |            | config_split.config_split.staging | Create    |
            +------------+-----------------------------------+-----------+

        This is the config for the staging split. You can accept this because it will not affect your production config.

THE RESULT:
You will have staging environment that allows you to have modules enabled in production and not in staging, and visa versa. You can also change some system settings different for both environments. You can deploy config changes from staging to production without overwriting specific production configuration settings.