Back to top anchor
Documentation

Updating a Sector site

We are updating our documentation library to be ready for the Sector 10! Find out more in our Sector 10 roadmap or head straight to our collection of Sector 10 - Changes and Updates.

User role
Site Administrators (UID1)
Collection
Task
Planning and maintaining your site Backend
Topic
Webserver and Infrastructure

Updating a Sector site is easy. Sector releases funnel through a strict and thorough test process to ensure the best possible compatibility against Drupal core and contributed modules.

As with any Drupal distribution, you can use the Sector Starter Kit as a stepping stone and never look back - we call this decoupling. If you are along for the ride, you can remain on an upgrade path. 

The Sector release schedule

We maintain two Sector branches at any given time based on our Sector release schedule. Each branch is compatible with a Drupal core version, e.g. 8.8.x, 8.9.x, 9.0.x. All releases are published on Drupal.org and release notes are published here on Sector.nz

Security updates 

At Sparks Interactive, most Sector sites remain on an upgrade path. In the case of a Drupal security advisory, Sparks assesses the advisory, updates and tests Sector, publishes the Sector update, then updates the Sparks Sector sites via a Composer update. For time-critical updates, you can also hot patch sites (add patches to your code base directly) and bring them back into the Sector fold with the next Sector update.  

Continuous improvements

We also publish continuous improvements for both the Sector Starter Kit and Sector add-ons. All releases are published on Drupal.org and release notes are published here on Sector.nz

Updating Sector sites on an upgrade path

Updating within a minor release 

Updates within a minor release are updates within a branch - for example, 4.x to 4.x+1.

What's the latest Sector release?

See our news section for the latest Sector release notes.

Generally speaking, when working from the base Sector Starter Kit, the upgrade process is reasonably simple. Your mileage may vary if you have included additional modules outside of the Starter Kit, and you will need to test them separately.

Occasionally, the update process may be different for an individual Sector release - like Sector 5.0.0-rc1, where one module update meant a change in update process. If anything different is required for an update, we will outline this in the release notes.


Steps to update a Sector site

  1. Carry out a dry run for visibility
  2. Run the update command
  3. Review any patches that fail to apply
  4. Update the database
  5. Verify that the update has been done

Note: Use Composer to perform updates

We recommend using Composer on the command line to perform updates, instead of using the built-in Drupal UI.

Step 1 - Carry out a dry run for visibility

Begin by carrying out a dry run for visibility on what changes are going to occur.

You can restrict your update to the newest Sector Starter Kit - this will update Drupal Core and all included contributed modules to the latest versions that have been tested with Sector and are included as part of the latest Sector version. It will also fetch the latest Sector Starter Kit code.

composer update drupal/sector --with-all-dependencies --dry-run

If you have added additional contributed modules or Sector add-ons to your site build, running the command below will update the Starter Kit as well as all contributed modules and  Sector add-ons.

composer update --with-all-dependencies --dry-run

If the output doesn’t contain anything alarming, you can go ahead and run the command for real.

Step 2 - Run the update command

Repeat the previous command(s), but drop ‘--dry-run’.

$ composer update --with-all-dependencies

Step 3 - Review any patches that fail to apply

In some cases, there may be patches that fail to apply - in the time between Sector releases, some contributed modules might have committed those patches into their main project branch.

If this is the case, a close investigation of the failing patches should provide some detail on whether or not they can be removed from the composer.json file. Once done, the update command can be re-run.

What to do if module dependencies are failing?

If module dependencies are failing, you can force an explicit version on the module in question (within composer.json), or use the more advanced Composer aliasing to ‘fake’ the version number.

Once any bugs or errors have been resolved and the Composer updates complete successfully, you can move on to update the database.

Step 4 - Update the database

Note: Take a backup first!

It's good practice to take a precautionary backup of the database before an update.

Using Drush, update the database by running:

drush updb

You could also use the update tools provided by Drupal to do this.

<your-domain>/update.php

Confirm you’re ok to proceed - all going well, you should now be on an updated Sector / Drupal core and relevant contributed modules.

Step 5 - Verify that the update has been done

If you want to check that the updates have been completed successfully, you can see these details on the 'Status reports' page in the backend of your site.

<your-domain>/admin/reports/status

Changing from legacy namespace

If you're using the older sparksinteractive/sector-distribution namespace, it's a simple procedure to migrate to the new namespace

$ composer remove sparksinteractive/sector-distribution

Add $ exclude: [ "drupal/sector" ] to the https://packages.drupal.org/8 repository definition.

$ composer require drupal/sector --with-all-dependencies

Updating to a new major release

Updates to a new major release are updates between branches for example 4.x to 5.x. 

Before any major update, it is important to review the release notes for the new branch and to understand what has changed, what code was deprecated or been removed. Updating when there are major improvements like the new Sector Radix Starter theme or the new media library will need some planning. 

Once your review is completed, and you want to give the update a go on a development site, you can follow the steps above, with one change: you will need to update your composer.json file. Find the drupal/sector line in the required section, and change that to the new branch! 


Having problems updating Sector?

If you encounter issues with the steps above, we'd be glad to help. You can leave feedback on this page using the 'Is there something wrong with this page?' form below, or chat to us on Twitter or Slack

Last updated

Sector 10 is coming!

Find out more in our Sector 10 roadmap.

Need Help?

Sector is brought to you by Sparks Interactive - supporting Sector from Wellington and Auckland

Open Source award winner!

Sparks Interactive are delighted to accept the Open Source Use in Business award for Sector and the Sector.nz open source platform.

Subscribe for Sector updates