Finding winning Drupal 8 workflows at DrupalCon 2016

Drupal 8 is a great system. I had my doubts in the past but after seeing the impressive number of changes, improvements and new features merged in the last months, I’m not skeptical anymore. Drupal 8 is a great system.

But along with the improvements come new challenges, mainly for the developer.

The documentation is sometimes not up-to-date or missing entirely for the newest tools and, as a good developer, you need to check the code and experiment to master your new toys.

But how do you know if you are going in the right direction, that your code follows the best practices, that your Drupal 8 workflow is actually correct?

Being at DrupalCon Dublin is the perfect way to answer all these questions.

You can discuss with the community, attend the sessions, and less formal BOFs, and give your contribution at the sprints. And when you see a room with neither chairs nor standing space free, that is a clue people are DESPERATE to know more about the subject.

Let’s look at a good example of one these hot topics.

Configuration Management: theory and practice

This was a day 2 session run by pescetti, ademarco and bircher.

Configuration Management (or CMI, where the “I” stands for Initiative) is one of those new tools I was mentioning above.

CMI takes care of your Drupal 8 configuration. During site-building and development you create nodes, fields, views, menus, user roles and permissions – and much more – and CMI allows you to export this configuration into yaml files ready to be committed to your repository, deployed and imported into other instances on another environment, e.g. a Stage or Live website.

If you’ve used ctools, features, features extra or similar modules before, you’ll be pleased to hear that now Drupal 8 does it out of the box through CMI.

At Manifesto we struggled a lot with CMI and this new pattern, trying to find a good and (mainly) working workflow.

You can imagine how glad I was to hear the solution we found internally is actually the approach other developers are using around the globe.

I do suggest you watch the video to learn more, but first I would like to briefly explain the process we adopted.

1. Define your config `sync` directory

The sync directory is the destination folder where drupal will export/import your configuration. By default it lives within the files website directory, automatically created by drupal, but it’s good practice to keep it outside your website docroot.

You can define it in your settings.php file, i.e.

$config_directories['sync'] = DRUPAL_ROOT . '/../config/sync';

2. First configuration import with Config Installer

You can not install a site and import an existing configuration. Each installation creates a unique Site ID which is also stored on the config yaml files. CMI won’t let you import any configuration with a Site ID different from that of the destination site.

A way of bypassing this problem is to use the Configuration Installer profile, which works as a normal profile but will import Site ID and the whole config for the `sync` folder setup on point 1.

On our workflow we also specify the original installation profile we would like to start from, to make sure we start with minimal, adding this line on settings.php:

$settings['install_profile'] = 'minimal';

Now you are ready to install your site and importing the existing configuration. We use drush, but you can also use the web interface.

drush site-install config_installer

3. Export your changes

It’s now time to build your site and, when done, export your configuration.

Again you can do it from the administrative Configuration section of your website, but at Manifesto we love drush, so:

drush config-export

You probably want to exclude some of the modules, like devel, features, smtp, from the export. This is possible out-of-the box with drush –skip-modules + few lines on your .gitingore to avoid this bug or you can try the module config_split suggested by bircher in the DrupalCon session.

4. Review and Commit your changes before anything else.

Configuration is the core of your website, and exporting the wrong settings can potentially cause a lot of problems, including breaking your website.

You should always review the export and ask yourself:

• Are the modified files the only changes I made or was expecting?
• Are there any unwanted modules in the configuration?
• Am I deleting or adding something I shouldn’t?

As soon as you are happy with your changes, you can proceed with committing them in order to not lose anything.

5. Pull updates.

If there are multiple developers working on the project, this is the time to pull your changes. While changes to the code probably wouldn’t crash your website, not taking care of the configuration almost certainly will!

Pulling now will flag any possible conflict. You also get the opportunity to fix them, whether the problem is coming from the remote updates or your local ones.

6. Import changes.

It’s now time to import the changes you’ve just merged into your repo. And I’m using the word changes and not simply config because the changes might be more than just a configuration update.

Think about a new module listed on your composer file, or an update hook.

You need to run all of them at this step:

composer install && drush config-import && drush updatedb && drush cr

At Manifesto we use a git hook after a merge event in order to run all these commands automatically, so there’s no risk of the developer forgetting.

7. Time to push

You’ve merged your changes with those coming from the remote repository, you’ve imported the result, you’ve  checked that the import runs successfully and that the website is up and happily running.

It’s time to push your hard work.

0. Start working on a new feature

This is always your last – or, from now on, first – step.

It’s time to start working on a new feature and, if you use git-flow, in a new feature branch. But checking out a new branch from a relatively old state – for example from a develop or master branch which doesn’t have yet the changes you just pushed – could potentially cause trouble, as the `sync` folder configuration is different from the one on your local dev environment.

Exporting will add settings from the previous work, and we don’t want that (we’ve already pushed it after all!)

Importing will also cause a lot of trouble, e.g. leaving unused settings and tables in the site which will cause errors later on. Also, in some cases, it would refuse to import due to deleting fields with data in them.

That’s why at Manifesto we reset the status, installing a new site as described in step 2.

It’s a winning workflow, probably still not perfect but as confirmed by pescetti, ademarco and bircher in their ‘Configuration Management: theory and practice’ session, it’s a common pattern people use and which has the potential to become best practice soon.