Creating a Drupal core security release

This guide explains how to create a security release of Drupal core. For instructions on creating a normal patch or minor release, see Creating a new Drupal core release.

Before you begin

Everything about a security release is private until the release itself is published, including whether or not there will even be a release. Only the security release window itself (typically the third Wednesday of the month) is announced in advance. Do not share any information about an upcoming security release with anyone outside the Drupal security team. See the security team disclosure policy for more information.

Security releases require coordination with the security team and (when fixes are being released for multiple branches) coordination with other branch maintainers.

Security release window preparation

1. If the security release is a coordinated release to update a third-party Composer dependency, different steps are required. See Creating a security release for a third-party dependency update.

2. Friday before release: Go through list of issues at https://security.drupal.org/project/issues/drupal and figure out which (if any) are ready for release. Issues marked "Ready for SA to be published" already have another committer's signoff; issues marked RTBC are awaiting committer signoff. See the Committer checklist for reviewing a private core security issue and make sure all issues comply with the requirements there.

3. Monday before release: Figure out if any of the ready issues affect other stable branches of Drupal, and coordinate with the maintainers for that branch if so. You can ask the Security Team for help with this in the #security channel on Drupal Slack or on the security mailing list. The Security Team lead will need a list of issues likely to go in to the next release, in order to know what CVE IDs (a unique ID for a vulnerability that security professionals reference) they need to assign.

4. Monday before release: Create a combined patch with all issues in the release and attach it to a separate private issue. All patches that are scheduled to go out must be applied together and tested by the private testbot to ensure there are no regressions or conflicts. Be sure any commits that will need revert for a clean forward merge are documented in the issue summary.

   • Use the Improved security testing project for this (Drupal 8 and above), or kick_drupalCI (Drupal 7).

   • Get the Jenkins token required by that script from a security team member who already has access, and get the URL of the patch to be tested using the "One-time downloads" tab on the security.drupal.org issue.

   • The test results will be emailed to you (although there is currently a bug with the email message formatting).

     To check for failures in Drupal 7 test results, run commands like
     grep fail build.log | grep -v \ 0\ fail
grep exception build.log | grep -v \ 0\ exception
     on the file.

     For Drupal 8 test results, use
     grep \ fail build.log
grep \ exception build.log

     You may also request access to view the results on https://dispatcher.drupalci.org/ if you will test security issues regularly.

5. Each issue should have its own security advisory draft. If it does not have a draft, it is not ready for release.

6. Each issue should also be assigned contributor credits at the bottom of the security issue (similar to the credit widget on public issues).

A code freeze across all branches begins at 1200 UTC Tuesday prior to a core release window. This is also the time at which all private issues must be ready for release (barring a zero-day). Issues that aren't ready will need to wait for the next window.

Day before the release: Committing the changes to the private repository

1. Check for any updates on issues planned for the release. If they were (or should be) bumped back from "Ready for release", be sure to remove them from the patch. If additional work has been done, go back over the points above for the issue.
2. Check for any additional issues that were marked RTBC or Ready for release since Friday and follow the same steps as above. Add them to your combined patch
3. Re-run the tests against HEAD for the active and development branches (8.7.x and 8.6.x in the example above). If the issues in the release have changed since Friday, also re-run the tests against the relevant tags (8.6.3 and 8.5.8 in the example).
4. If any of the fixes apply and pass tests on the latest tag but not HEAD for the current branch, revert the commits in HEAD that cause the discrepancy locally.
5. Use the security release tagging script to tag the releases locally. (If you need to tag the release manually for some reason, read the archived tagging instructions.) Do not push your changes to the public core repository.
6. Push the commits (including any local reverts) and new tags to the private repository for the security release. Ask the security team lead if you need a link to the instructions for this.
7. Cherry-pick the main commit forward to the development branch (or commit the patch with the same commit message) and push this to the private repository as well. Do not push your changes to the public core repository.

Release day (typically the third Wednesday of the month)

Join Drupal Slack so you can coordinate with the Security Team. The Security Team lead will generally create a new private channel for each core security release.

Check with the security team before pushing or publishing anything to make sure everything is ready to go. (Once the code is committed, the goal is to get the actual releases out as fast as possible.).

Write up the release notes locally

It is recommended to get the release notes written in advance and saved somewhere locally, so you can just copy-paste quickly when it's time to create the actual release later on (this is especially important for security releases).

Copy from a previous example and modify the text appropriately. Here's a simple example and a more complicated example. Note that the security advisory will have a URL following a particular pattern (https://www.drupal.org/SA-CORE-2015-003) so you can link to it now even if it isn't created yet.

If there are any disruptive changes, including even internal API changes, upgrade paths, node access rebuilds, etc., be sure these are mentioned in the release notes. See https://www.drupal.org/project/drupal/releases/8.6.2 for an example.

For releases after September 2018, security coverage is extended to the previous minor version, so security releases will be created for two minor branches at the same time. The release notes should explain the coverage and recommend sites update to the earliest secure release. For example, Drupal 8.6.2 and 8.5.8 were released together with the same fixes. The 8.6.2 release notes read:

Sites on 8.5.x or earlier should update immediately to <a href="https://www.drupal.org/project/drupal/releases/8.5>Drupal 8.5.8</a> instead, and plan to update to the latest 8.6.x release before May 2019.

The 8.5.8 release notes read:

Sites on 8.5.x will receive security coverage until May 2019. Versions of Drupal 8 prior to 8.5.x are end-of-life and do not receive security coverage. Update immediately to this release, and plan to update to 8.6.x or later before May 2019.

Write the security advisory (unpublished)

Do this in conjunction with the security team.

Hopefully most of it was already written earlier and it just needs to be copied to drupal.org (see the security release procedures for details). Make sure to give it a URL alias along the lines of "SA-CORE-2018-006" so that it's easy to cross-link this from the other pages you are creating.

Example advisory: https://www.drupal.org/SA-CORE-2018-006

Create the release node and publish the announcements

1. From the Drupal project page click the "Add new release" link (or go to https://www.drupal.org/node/add/project-release/3060 directly).
2. Choose your tag from the list and click "Next".
3. The next screen will ask you for some release notes. Paste in the ones you created earlier.
4. Make sure to tag it as a "Security update".
5. Add a URL alias along the lines of "project/drupal/releases/8.6.4" so that links to this work from the other pages you created. (This should be added automatically if the "Generate automatic URL alias" checkbox is checked.)
6. For the "Short Description" field use something similar to what was used for the previous release (see the regular release instructions for additional details).

Security releases need to be published manually. Make sure the tarballs and zip files are actually present and downloadable, get a final OK from the security team, and then publish the release node, the release announcement, and the security advisory in quick succession.

Post-release steps

Follow the post-release steps for a regular release. Additionally:

1. If any of the private issues in the release have the "Needs followup" tag, move them to "Needs public followup". Otherwise, they can be marked "Closed (fixed)".
2. Make sure the SA email gets approved. This happens at http://lists.drupal.org/mailman/admindb/security-news but you'll need to get the password first (or ask someone on the security team to do it).
3. Edit all issues with release-related tags so that the tag points to the correct version of Drupal. For example, if Drupal 7.38 was the previous core release and you just released Drupal 7.39 as a security release, then all the previous bug fixes tagged for Drupal 7.39 won't actually be released until Drupal 7.40 instead. So in that case you would look for issues tagged like the following:

   7.39 release notes
   7.39 release announcement
   7.39 release blocker
   String change in 7.39

   and re-tag them for Drupal 7.40 as appropriate.

4. Similarly, go to http://drupal.org/list-changes/drupal and look for any recently-committed change notifications that were tagged for the current release (e.g., Drupal 7.39) and re-tag them for the next release (e.g., Drupal 7.40) as appropriate.

The days after the release

Follow the same steps as for a regular release.