Choosing the upgrade approach

Overview

When preparing an upgrade, it is worth spending a while to plan the upgrade approach. While the content of your previous Drupal site can most probably be migrated without issues, the configuration of your new Drupal site will most probably need some manual tasks. For example, Views module doesn’t have an automatic upgrade path in core which means you will need to manually create the views on your new Drupal site. The most suitable approach needs to be considered for each site.

Simple approach with manual post upgrade steps

In this approach the upgrade is executed once and the manual post upgrade steps (e.g. creating the views) are performed on the new Drupal  site before publishing it. 

It is recommended to practice the upgrade first and take careful notes on the manual post upgrade steps. Once you are happy with your test environment, repeat the exact same steps and build your new Drupal production environment to a clean Drupal installation.

This approach can be applied by 

• Upgrading using web browser
• Upgrading using Drush

Incremental upgrade after manual post upgrade steps

Depending on the amount and complexity of the manual post upgrade steps, it might not be feasible to keep the old site offline when the manual post upgrade steps are being executed on the new Drupal site. If the old site is online when the manual post upgrade steps are being done on the new Drupal site, it is possible that the users are creating or updating content on the old site.

Drupal supports incremental upgrades. This means that the migrations are executed again in order to migrate new and updated content. It is not recommended to change the configuration of the old source site between the initial upgrade and incremental migration.

This approach can be applied by 

• Upgrading using web browser
• Upgrading using Drush

Migrating content only to STAGING and PROD environments

One of the most powerful new concepts in Drupal is an advanced configuration management system that can be used to deploy the whole Drupal configuration from one environment to another. Perhaps the most typical environment landscape is to have a development environment (DEV), a test environment (STAGING) and a production environment (PROD) which is the live site for end users. In Drupal 8 or higher, all configurations can be exported as YAML files and imported to another environment.

If you are planning to have separate DEV, STAGING and PROD environments, one possible approach is illustrated in the picture below. It is important to understand that the Drupal entities can be categorized as follows:

• Content entities (users, nodes, taxonomy terms, ...) 
• Configuration entities (content types, fields, views, all configuration settings)

The upgrade process in the picture above:

1. The new Drupal DEV environment is upgraded from the source site.
2. The source site is kept online (content can be created or updated). At the same time, the configuration is finalized on the new Drupal DEV environment.
3. The configurations can be deployed from DEV to STAGING using the new Drupal configuration management system. Version control system (e.g. Git) is typically used.
4. When the configuration of the STAGING environment is complete, content can be migrated from the source site to STAGING for final acceptance testing. Once the acceptance tests are OK, the new Drupal PROD site is deployed and content is migrated from the old site to new Drupal PROD site.

This approach requires upgrading using Drush. There are a couple of possible variants to this approach.

• Refer to upgrading using Drush page on how to generate the migrations.
• The upgrade to the new Drupal DEV (step 1 in the picture above) can be done by executing all migrations with drush migrate-import --all or by executing the desired migrations one by one using drush migrate-import <migration name>
• Upgrading content only (step 4 in the picture above) can be done by executing all content migrations with drush migrate:import --tag=Content or by executing the desired migrations one by one using drush migrate-import <migration name>. It is also possible to list the desired migrations in a manifest file.