Configuration Synchronizer

Configuration Synchronizer provides methods for safely importing site configuration from updated modules, themes, or distributions.

By taking a snapshot of configuration as installed and comparing the snapshot to the new module or theme as well as the current active configuration, Configuration Synchronizer safely merges in updates without overwriting customizations.

Configuration Synchronizer is built on the Config Filter framework used by Configuration Split and several other modules.

Instructions are for the 8.x-2.x branch, the active development branch.

Requirements

• Config Distro
• Config Filter
• Configuration Merge
• Configuration Normalizer
• Configuration Provider, 8.x-2.x branch
• Configuration Snapshot
• Configuration Update Manager

Installing Configuration Synchronizer

Ideally, install Configuration Synchronizer and its dependencies as early as possible on a site, so that it can take snapshots of configuration as other modules are installed.

When you first install the module, it takes snapshots of all installed extensions. The install may take a relatively long time to complete.

Updating Configuration Synchronizer

Configuration Synchronizer is under rapid development. When updating to a new release, always update at the same time to new releases if available for all Configuration Synchronizer dependencies, as they may include changes required by the new Configuration Synchronizer release.

If updating from a 8.x-2.x release prior to 8.x-2.0-beta2 (which introduced a new dependency on the Configuration Normalizer module), please update to 8.x-2.0-beta4 or later, as that release introduced a fix that makes updating easier.

Using Configuration Synchronizer

Each time you upgrade to a new version of a distribution, module, or theme, after you run any updates, navigate to Administration > Configuration > Development > Synchronize > Distribution Update (admin/config/development/configuration/distro).

This page displays any available configuration updates. If there are no updates available, you will see the text "There are no configuration changes to import."

If there are available updates, you will see a list of available updates arranged by module or theme. Advanced users have the option of selecting specific modules or themes to import updates from. To import the, click the "Import" button.

The Config Distro module provides a Drush 9 command to import configuration: drush config-distro-update.

Upgrading from 8.x-1.x

The 8x-2.x branch includes major refactoring. Be sure to test on a development version of your site before attempting to upgrade from 8.x-1.x. Steps will include:

• Install and enable the latest releases of all dependencies (see above). This step must be completed before you update the version of Configuration Sychronizer. (See #2863986: Allow updating modules with new service dependencies for a related bug in Drupal core and an effort to fix it.)
• Update to the 8.x-2.x branch of Configuration Synchronizer.
• Run updates. This will migrate Configuration Synchronizer snapshot data from the table used in the 8.x-1.x branch to a format used in the 8.x-2.x branch, so prior snapshots should continue to work in the new branch.
• Clear caches.

Background and use case

The focus in Drupal 8 on staging configuration, rather than sharing it among multiple sites, creates significant issues for distributions; see the blog post Drupal 8 configuration management: what about small sites and distributions?

Building on the configuration snapshot system that takes a snapshot of configuration when it's installed or synchronized via the staging system, Configuration Synchronizer snapshots configuration as installed or updated from extensions, then compares those snapshots to the active configuration to determine whether customizations were made. This approach allows merging changes into the site without losing customizations.

Detailed example

Say you have a content type, event, that you installed from a module called mydistro_event. The content type you imported looked like this:

name: Event
type: event
description: 'An <em>event</em> contains a date.'
help: ''

You decide you want to customize both the name and the description of the event content type. After your edits, the configuration item looks like this:

name: Event
type: event
description: 'An <em>event</em> is something that occurs on a specific date.'
help: ''

Meantime, the maintainers of the mydistro_event feature have also made edits. They changed both the description and the help text. The new version looks like this:

name: Event
type: event
description: 'An <em>event</em> has a date.'
help: 'Please enter a date for your event.'

You run Configuration Synchronizer to get the updates. For this item, there are two changes available: description and help. One of these you've customized, while the other is still at is default value. Configuration Synchronizer will import the updated help text, but will retain your customized description. The result will be a combination of (a) the original version, (b) the changes from the new version, and (c) your customizations:

name: Event
type: event
description: 'An <em>event</em> is something that occurs on a specific date.'
help: 'Please enter a date for your event.'

Related modules

• Configuration Development provides automated import and export of configuration between the active configuration storage and exported modules.
• Configuration Split allows to define sets of configuration that will get exported to separate directories when exporting, and get merged together when importing.
• Configuration Tools is a package of modules that help to manage Drupal 8 configuration files.
• Configuration Update Manager provides a report that allows you to see the differences between the configuration items provided by the current versions of your installed modules, themes, and install profile, and the configuration on your site. From this report, you can also import new configuration provided by updates, and revert your site configuration to the provided values.