Last updated 3 November 2017. Created on 2 February 2016.
Edited by xjm, David_Rothstein. Log in to edit this page.

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. Friday before release: Announce the release window by creating an event on http://groups.drupal.org/core (example). Make sure the "Comment settings" and "Signup settings" are both set to "disabled". Create the announcement the same way even if there is no security release planned.
  2. Go through list of issues at https://security.drupal.org/project/issues/drupal and figure out which (if any) are ready for release. Also figure out if any of those affect other stable branches of Drupal, and coordinate with that branch maintainer if so. You can ask the security team for help with this in #drupal-security 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.
  3. All patches that are scheduled to go out must be applied and tested by a private testbot to ensure no regressions:
    • Use the kick_drupalCI project for this.
    • 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. 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
      (?? - this needs confirmation for Drupal 8)
  4. An SA (security announcement) needs to be written with full details of all the vulnerabilities fixed. See http://drupal.org/security for a list of examples, and the full list of security release procedures for more details. You can start a draft of this on the security.drupal.org website, and transfer it to drupal.org on the day of release.

Release day (typically the third Wednesday of the month)

Join #drupal-security so you can coordinate with the security team.

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.

Write up the release announcement (unpublished)

Follow the instructions for creating a core release announcement.

Note the specific templates for security release announcements:

  • Security release, joint Drupal 7 and Drupal 8 (example)

Here are some older outdated examples that might still be useful for reference:

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-2015-003" so that it's easy to cross-link this from the other pages you are creating.

Example advisory: https://www.drupal.org/SA-CORE-2015-003

Commit the code

If this is a security release, check with the security team before committing 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.)

This will be branched off the most recent stable release (so it only contains the security fixes on top of the last release, not anything else). Therefore the steps are a bit more complicated (note that these are partially based on the instructions at https://www.drupal.org/node/1154670, but with some modifications for Drupal core):

  1. Create the local branch to work from:
    git checkout -b 7.38-security 7.38
    
  2. Apply the security patches. Note that because of access protection on http://security.drupal.org you'll need to download these to your desktop from your web browser or something; stock wget doesn't work.
    git apply ~/Desktop/something.patch
    git apply ~/Desktop/something-else.patch
    
  3. Edit the VERSION constant and CHANGELOG.txt.

    See the "regular release" instructions above for where to find the version constant.

    The new CHANGELOG.txt entry should look something like this:

    Drupal 7.39, 2015-08-19
    -----------------------
    - Fixed security issues (multiple vulnerabilities). See SA-CORE-2015-003.
    

    For a Drupal 7 release, see this example diff for CHANGELOG.txt and this one for the VERSION constant.

  4. Commit the above and tag the security release:
    git commit -am "Drupal 7.39 (SA-CORE-2015-003) by username1, username2, username3"
    git tag -a 7.39 -m "7.39 release"
    
  5. Now merge the security fixes back to the latest, bleeding-edge 7.x code:
    git checkout 7.x
    git merge --no-ff 7.39
    

    You will usually have to resolve some simple conflicts here in CHANGELOG.txt and includes/bootstrap.inc.

    Here is an example diff.

    Once the conflicts are resolved and the merge is ready, git commit (but don't push yet).

  6. Remove the temporary branch (so it doesn't get pushed up to Drupal.org).
    git branch -d 7.38-security
    
  7. Push your branch and the tag:
    git push && sleep 10 & git push origin 7.39
    

    Note: the sleep is necessary because of a known issue that can cause race conditions in the commit processing. Be sure to include it in your command. Otherwise, infrastructure will need to fix it manually and it can also cause issues for the Packagist mirror of Drupal.

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.1.1" 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. Make sure the S.A. 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).
  2. Ensure that all active branches of Drupal core either have the commit applied or have a critical public issue filed to apply it. For example:
    • If there is an open development branch for the next major release of Drupal core (e.g. Drupal 9):
      Create a public issue for each of the security issues that was fixed, for the purpose of forward-porting the fix. It's best practice to give this issue the "Security Advisory follow-up" and "security" tags, as well as a tag for the S.A. ID (e.g., SA-CORE-2015-003) that this is associated with (example). Link to this public issue on the corresponding security.drupal.org issue before marking the security.drupal.org issue as fixed.
    • If there is an open development branch for the next minor releases of Drupal core (e.g., if the security release was on the 8.1.x branch, other branches like 8.2.x will be open and under development also):
      • If the patch merges cleanly and review indicates it requires no separate changes, merge it to that branch right away.
      • If it has merge conflicts but requires no other changes, revert the commits that caused the conflict and reopen their corresponding drupal.org issues, then merge the security fix right away (since the security fix is higher priority).
      • Regardless of merge conflicts or lack thereof, it's still possible that the required fix for this branch is different from the one on the previous branch. (As a very simple example, suppose the security fix involved changing a particular code pattern that was previously used in Drupal core; if the code pattern was used 3 places on the 8.1.x branch and 4 places on the 8.2.x branch, a different code change is needed for 8.2.x.) If there is any doubt, open a critical public issue and ensure that issue will get resolved before the first stable release on that branch (e.g., by giving it the "[next version] release blocker" tag).

        This step should rarely be needed, since many security fixes will be the same between different branches (and for ones that aren't, the differences may have already been considered and reviewed while preparing patches in the private issue queue).

    • Make sure the fix on the tip of the current branch (e.g. 8.1.x for a security release made from that branch, 7.x for a Drupal 7 security release) is correct also.
      While making the security release, you created it off an older version of the code (specifically, off of the last tagged release) and then semi-blindly merged it into the tip of the branch. In theory it is possible that the tip of the branch requires a different fix, just like described in the bullet point above. If so, follow the same steps mentioned there, but for this branch instead. This is even less common than the above in practice, since the last stable release and the tip of the development branch don't usually differ as much as separate branches do.
  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.

Looking for support? Visit the Drupal.org forums, or join #drupal-support in IRC.