Setup Config Ignore and Config Split

The best practice for managing Site Studio configuration is to use Config Ignore and Config Split to remove Site Studio configuration from Drupal core configuration export and import process. See below for a brief explanation about the these terms.

Terminology

Site Studio Module Configuration

Site Studio follows standard Drupal community contributed module conventions and stores various module settings in Drupal config entities. This covers configuration required for basic functionality of the Site Studio module such as account, system, google maps API, element and package export settings. This type of configuration is stored using cohesion.* naming  pattern. Examples of such configuration include:

• cohesion.settings
• cohesion.sync.setting

Site Studio Configuration

Configuration entities related to the theme layer of the project - styles, templates, components, etc. This type of configuration is stored using cohesion_* naming pattern. Examples of such configuration include:

• cohesion_custom_styles.*
• cohesion_elements.*
• cohesion_website_settings.*

Config Filter
Contrib module that provides base functionality for hooking into Drupal configuration import and export processes

Config Ignore
Contrib module built using Config Filter. Its main purpose is to ignore specific configuration during the configuration import process.

Config Split
Contrib module built using Config Filter. Its main purpose is to set up a specific configuration to be split up from the rest of the configuration export. Split configuration can be handled in multiple ways:

• Placed in a separate configuration collection, but still exported with the configuration export process
• Placed in its own directory, but still exported with the configuration export
• Placed in database - export process will leave configuration in the database and will not create any files in the filesystem that are deemed to be part of the “split off configuration”

Technical Approach

This guide is based on Drupal Configuration management best practices and recommends the use of the contributed module Config Split (config_split) and Site Studio Packages. The guide covers managing Site Studio Configuration for configuration entities related to the theme layer of the project (cohesion_*). If your project uses alternative or incompatible strategies to manage configuration then you must apply this principle to your application.

This guide does not cover Site Studio Module Configuration (cohesion.*) - handling generic module configuration will depend on project requirements and should be handled in the same way as the rest of your Drupal configuration.

We also recommend that the Site Studio API and Organisation keys are excluded from your codebase, see information on Storing sensitive information outside of your codebase (https://docs.acquia.com/resource/secrets/).

Setup guide

Here are the steps to configure the Config Ignore and Config Split modules to remove Site Studio configuration from the Drupal configuration export and import process:

1. Download and enable Config Filter (config_filter), Config Split (config_split) and Config Ignore (config_ignore) contrib modules. 
   
   
    
2. Enable Site Studio Sync (cohesion_sync).
3. Configure Config Ignore to ignore Site Studio configuration during Drupal configuration imports by adding the following Configuration name pattern (/admin/config/development/configuration/ignore): 
   cohesion_*
   
   
    
4. Add new configuration split to Config Split module (/admin/config/development/configuration/config-split). Name of the config split can be anything, but we recommend something self-explanatory like “Site Studio” (site_studio)
   
   
    
5. Configure your newly added  configuration split to separate Site Studio configuration from the rest of Drupal configuration during exports by adding the following settings:
   1. “Storage” should be selected to “database”. This will ensure configuration exports are not recreating Site Studio configuration in the filesystem, which should lead to much more manageable version control workflows and work reviews.
   2. “Status” should be set to “Active”.
   3. In the “Complete Split” section leave all of the checkboxes empty, but add the following line into “Additional Configuration”:
      cohesion_*
   4. Leave the “Partial Split” section with default settings - no options should be selected and the “Additional Configuration” text box should be empty
   5. Leave the “Advanced” section with default settings - “Stackable” option should be left unchecked
      
      
6. Save your configuration split settings.

Ignoring all cohesion configuration might not be the right solution for all websites. If a website has Drupal configuration that depends on Site Studio configuration such as a user role having a dependency on a Site Studio component/helper categories, ignoring all cohesion configuration would not include the categories as dependencies of the user role.

Moving cohesion_* wildcard from Complete Split to Partial Split in config_split 2.x. This is enough for removing all cohesion_* entities from export, but retain dependencies in other entities.

Validating your configuration changes

Validate that the changes take effect during Drupal core configuration export and import and test as part of your configuration management developer workflow:

• No cohesion_* entities are imported or exported to your configuration directories as part of any configuration tasks.
• cohesion.settings will be exported to your configuration directory.
• cohesion.sync.settings will be exported to your configuration directory if you intend to use and have configured full export settings.
• Site Studio API and Organisation keys are not exported, overwritten or imported.

If these occur please revisit the setup steps or check if there are any conflicts with your existing configuration management strategy.