Configuration exports will be sorted more consistently.
For site owners
This may result in more config diffs immediately after updating to this version of core. You should always export, review and commit configuration changes after running updates to ensure that changes aren't reverted by the next configuration import. After updating core, the consistent sorting should result in less config diffs in the future.
For developers of a site with multiple open merge requests
It is always recommended to upgrade Drupal versions in their own branches independent from other changes in order to better see what changes. For the upgrade to Drupal 9.3 this is especially recommended.
To manage a merge/pull request (MR for short) that was started before the Drupal 9.3 upgrade was merged to the main branch the following steps are recommended:
- Ensure branch is merged to the point just prior to 9.3.x merge
This will make sure the branch contains all non 9.3 changes up to 9.3 - Do clean install site on your site.
This will ensure that you do not have any accidental changes - Switch to 9.3 branch (not main)
This will ideally contain only changes to composer.json .lock and changes to scaffolding and config files, if your MR has other changes to composer.json you may want to replicate the Drupal 9.3 upgrade changes in composer.json or cherry-pick the Drupal 9.3 upgrade instead of switching branches - Run composer install
This will download Drupal 9.3 and dependencies - Switch back to your branch
Your site now aligns with the code again except for Drupal 9.3 - Run database updates
This will sort the configuration - Export config
This exports the sorted config plus all the config of the MR in a sorted way - Commit the config
You do not want to lose changes to it :D - Merge main branch (which has 9.3.x)
- As always after merging upstream branches: run update hooks, and import the config to align your site with the code (Or run
drush deploy)
It is not necessary to do theses steps in this order, but doing so reduces the amount of config changes that need to be reviewed at different steps. This reduces the chance that something gets lost due to the noise of sorting the config. In case a wrongly sorted config yaml gets merged, the next time Drupal imports or saves the config it will be sorted again and just needs to be exported again.
For profile and contributed module maintainers
You should re-export default configuration in your modules, so that the ordering is consistent with exports of those same configuration for sites.
This change does not affect the live site configuration in any meaningful way. In a mapping (an array with named keys) the order of the keys is usually not relevant for code accessing the data the config holds. However, when importing the config and when the config is exported to files, the config is encoded in YAML. So for a diff the order matters, otherwise a change can show up when there is no change, or changes are much harder to spot because they are hidden among unnecessary noise in the diff.
The config mappings are now sorted according to the order defined in their schema.
Reviewing changes
dyff is very helpful in reviewing these config changes. If everything worked well, the output should be empty, if there's a meaningful change it'll show up.
Another option is to use git diff --color-moved=plain to make the highlighting different for changes due to re-ordering.
Comments
GRRR
This change, which, to a lowly front-end developer, seemed to be somewhat arbitrary in nature, continues to cause me all sorts of frustration. I keep running into modules who's config will not import cleanly now, because active expects something different than staged.
I assume this must have something to do with the way the module was written in the first place.. however, BEFORE this change, I didn't experience any problems like this with config import.
The roll out alone, in midstream of maintaining large enterprise sites, was a ton of unplanned work and frustration. 2 sub versions later of 9.3.x, and, for example, the Focal \Point module config isn't importing cleanly.
meld
As stated above, dyff is very useful for sorting through the large number of line-differences:
https://github.com/homeport/dyff
I also found meld very helpful for this task:
https://meldmerge.org/
Config split
If you have multiple environments via config split then remember that running database updates is only guaranteed to fully-process the current environment's config. In this scenario you should repeat the whole process in the context of each environment, such that you are importing the environment's config under 9.2 before running database updates (each time against a refreshed 9.2 database), and then exporting and committing the config changes for 9.3 for that environment.