Creating a new Drupal core release

This guide explains how to create a regular release of Drupal core. For instructions on creating a security release, see Creating a Drupal core security release.

Release prep and announcements

Releases are made according the release schedule.

For minor releases, the release milestone schedule is announced several weeks before alpha1 on the Drupal core blog.

Remind committers of the commit freeze at least 6 hours before the release it to be made.

Minor release

We use a Drupal.org issue and a spreadsheet to coordinate creating a minor release.

After a minor release is made create a release preparation issue on Drupal.org for the next minor. For example, see [meta] Release preparation steps for 10.2.0. Also, create a child issue for the release notes. That issue will also have child issues for the pre-release milestones.

Next, make a new spreadsheet using the release preparation template. There are instructions in the README sheet. When that is made add a link to in on the d.o issue made in the previous step.

Finally, in the release manager channel update the bookmarks for the spreadsheet and minor release issue. There may be other bookmarks that need updating.

Release day

Prerequisites

Before you roll a release, check that all environments at GitLab CI are passing.

Prepare release notes

Release notes for patch releases and security releases are done locally. All others are done in a google doc linked is the relevant release notes issue. In all cases they should be thoroughly reviewed and ready for publication before starting to make the release.

Security releases

it is recommended to get the release notes written in advance and saved somewhere locally, so you can just copy-paste when it's time to create the actual release later on.

Patch releases

Copy from a previous example and modify the text appropriately. There is little to change here except when making the first minor release of a new major.

Non-patch and non-security releases

The release notes are in a google doc linked to from the relevant 'x.y.z release notes issue'. They are drafted using google docs and not on the release node so that the community can participate and because every save of the release node page starts a new packaging job.

Write the release announcement (unpublished)

We no longer create release announcements for every patch release. For significant milestones, see the instructions for creating a release announcement.

Announce a commit freeze

Announce a commit freeze in #core-leads-general.

Check for alpha stability experimental extensions

As of Drupal 8.5.x, alpha-level experimental extensions are removed from milestone releases of Drupal.

They are removed before the alpha release is tagged but remain in the development branch.

Commit the code

For a regular release, you can do this at your own pace.

These following steps are automated by the release tagging script.

Make sure you have the latest, bleeding-edge code at the tip of the branch, with no local hacks:

git checkout 11.1.x
git reset --hard
git pull --rebase

The steps below assume Drupal 11.1.2 is being released and that Drupal 11.1.1 was the previous release. Change the commands accordingly for the actual version you are releasing.

This will be released from the tip of the branch. So all you have to do is:

1. Run:

   php -r "include 'vendor/autoload.php'; \Drupal\Composer\Composer::setDrupalVersion('.', '9.1.0);"
   

2. Update the metapackages:
   

   rm -rf vendor
   composer install
   COMPOSER_ROOT_VERSION=9.0.7 composer update drupal/core*
   

3. The diff should look something like this at this point:

   diff --git a/composer.lock b/composer.lock
   index 5b6c87598b..f0b78a2fcb 100644
   --- a/composer.lock
   +++ b/composer.lock
   @@ -481,7 +481,7 @@
            },
            {
                "name": "drupal/core",
   -            "version": "9.0.x-dev",
   +            "version": "9.0.7",
                "dist": {
                    "type": "path",
                    "url": "core",
   @@ -728,7 +728,7 @@
            },
            {
                "name": "drupal/core-project-message",
   -            "version": "9.0.x-dev",
   +            "version": "9.0.7",
                "dist": {
                    "type": "path",
                    "url": "composer/Plugin/ProjectMessage",
   @@ -761,7 +761,7 @@
            },
            {
                "name": "drupal/core-vendor-hardening",
   -            "version": "9.0.x-dev",
   +            "version": "9.0.7",
                "dist": {
                    "type": "path",
                    "url": "composer/Plugin/VendorHardening",
   @@ -7100,14 +7100,10 @@
        ],
        "aliases": [],
        "minimum-stability": "dev",
   -    "stability-flags": {
   -        "drupal/core": 20,
   -        "drupal/core-project-message": 20,
   -        "drupal/core-vendor-hardening": 20
   -    },
   +    "stability-flags": [],
        "prefer-stable": true,
        "prefer-lowest": false,
        "platform": [],
        "platform-dev": [],
   -    "plugin-api-version": "1.1.0"
   +    "plugin-api-version": "2.0.0"
    }
   diff --git a/composer/Metapackage/CoreRecommended/composer.json b/composer/Metapackage/CoreRecommended/composer.json
   index b1c94c88af..bfad52acf4 100644
   --- a/composer/Metapackage/CoreRecommended/composer.json
   +++ b/composer/Metapackage/CoreRecommended/composer.json
   @@ -7,7 +7,7 @@
            "webflo/drupal-core-strict": "*"
        },
        "require": {
   -        "drupal/core": "9.0.x-dev",
   +        "drupal/core": "9.0.7",
            "asm89/stack-cors": "1.3.0",
            "composer/semver": "1.5.1",
            "doctrine/annotations": "1.10.3",
   diff --git a/composer/Metapackage/PinnedDevDependencies/composer.json b/composer/Metapackage/PinnedDevDependencies/composer.json
   index 0c80dcac81..c3308a5ba0 100644
   --- a/composer/Metapackage/PinnedDevDependencies/composer.json
   +++ b/composer/Metapackage/PinnedDevDependencies/composer.json
   @@ -7,7 +7,7 @@
            "webflo/drupal-core-require-dev": "*"
        },
        "require": {
   -        "drupal/core": "9.0.x-dev",
   +        "drupal/core": "9.0.7",
            "behat/mink": "v1.8.1",
            "behat/mink-browserkit-driver": "v1.3.4",
            "behat/mink-goutte-driver": "v1.2.1",
   diff --git a/core/lib/Drupal.php b/core/lib/Drupal.php
   index 4cecbb1506..79851ece14 100644
   --- a/core/lib/Drupal.php
   +++ b/core/lib/Drupal.php
   @@ -80,7 +80,7 @@ class Drupal {
      /**
       * The current system version.
       */
   -  const VERSION = '9.0.7-dev';
   +  const VERSION = '9.0.7';
    
      /**
       * Core API compatibility.
   

4. Commit the changes:

   git commit -am "Drupal 11.1.3"
   

   You can look for the commit at the top of commit list to make sure it looks OK. Make sure to select the correct version number.

5. Tag the release:

   git tag -a 11.1.3 -m "11.1.3 release"
   

   You can look for your new tag at the top of tag list.

6. Update the VERSION constant to111.1-dev.
7. Reset the metapackages back to dev.

   git revert HEAD --no-commit
   

   This will result in a diff that's the inverse of step 3 above.

8. Commit and push your changes:

   git commit -am "Back to dev"
   git push origin 11.1.2 11.1.x
   

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. Tag it for bug fixes and/or new features as appropriate.
5. Add a URL alias. Note the updated pattern (for 8.1.1 for example) which should be added automatically if the "Generate automatic URL alias" checkbox is checked:
   project/drupal/releases/8.1.1
6. Be sure to add a short description, since this will be used on the Drupal project page. Examples:
   • Drupal minor or patch release in active maintenance:
     

     Actively maintained with new features and backwards-compatible improvements every six months. Use this version for the best compatibility with future releases.
     

   • Drupal release candidate:
     Release candidates are not supported for production sites, but they are intended for widespread testing in preparation for the upcoming stable release.
      
   • Drupal beta:
     Betas are good testing targets for developers and site builders who are comfortable reporting (and where possible, fixing) their own bugs.
      
   • Maintenance minors:
     

     Supports Drupal 10 sites until they can be upgraded to Drupal 11.
     

   • Release on the security-only branch:
     

     Receives security coverage until December 2025 when Drupal 11.3.0 is released.
     

Check the supported versions 

This step is only needed for a stable release.

1. From the Drupal project page click the "Administer releases" link (or go to https://www.drupal.org/node/3060/edit/releases directly).
2. Set the new release to 'Supported'. Previous releases may need to be unchecked.

Confirm packaging succeeded

Confirm the tag exists in the GitHub sub tree split.

https://github.com/drupal/core-recommended/tags

Confirm the tag exists on Packagist.

https://packagist.org/packages/drupal/core-recommended

Make announcements when packaging is complete

1. Announce in #core-leads-general that the packaging is finished.
2. Announce the status of the current branches. In particular, comment on the branches no longer available for backport. Example:
   The last two normal bugfix releases for 11.1 and 10.4 have been tagged, so don't backport anything else to 11.1 or 10.4 (except in consultation with the release managers for critical security or upgrade path blocking issues)
3. For major and minor releases remind committers to watch for regressions. Example:
   Please keep an eye out for incoming reports of possible regressions or disruptions at: https://www.drupal.org/project/issues/search/drupal?project_issue_followers=&status%5B0%5D=Open&version%5B0%5D=any_11.&version%5B1%5D=any_10.&issue_tags_op=%3D&text=&assigned=&submitted=&&&&issue_tags=&order=created&sort=desc

Update the scheduled pipelines

Add a scheduled pipeline for the new release. There is information for this in the scheduled pipelines handbook page.

Update system requirement pages

Update the PHP requirement page and any other system requirements page as needed.

Post-release steps

Since this is a regular release it should automatically publish itself within 30 minutes or so. Watch for the green message at the top that the release is packaging. Once that is completed and you've verified that the release is available from Packagist:

1. Publish the release announcement if any.
2. Optionally, get a local site set up with the previous release installed, and make sure the Update Manager is correctly reporting the new version.
3. If this was a minor release, disable the EOL releases by editing the core project node, clicking on the Releases tab, and unchecking the latest release version for the old branch or branches.
4. And finally, have a sandwich. Mmmm... sandwiches.

The days after the release

Follow the list of all Drupal core issues to look for any regressions. If there are any, add them to the "Known issues" section of the release notes. Here are example release notes with a "Known issues" section.

It's a good idea to subscribe to any issues that deal with regressions (in core and/or contrib) and periodically go back and update the release notes once the problems have been dealt with (e.g., to point out which version the issue was fixed in).