Allowed changes during Drupal core release cycles

Last updated on
18 March 2024

This policy explains what changes can be made to different core versions during the Drupal core release cycle.

For details on the Drupal core release schedule, including explanation of patch and minor releases, see the release cycle overview.

How to evaluate issues

This section describes how to decide which version to assign to an issue.

The target for issues is the main development trunk, 11.x. This is effectively a main branch and is in the process of being renamed to 'main'. More information on this subject is at the New Drupal core branching scheme introduced.

Issues may be assigned to a specific branch in the following situations.

  1. A bug that only affects a specific branch.
  2. It is being backported.

Patch releases

The primary goal of patch releases is to provide bug fixes for production sites.

The most important consideration is disruption to these sites.

Disruptive changes are usually postponed to the next minor or major version. But, such changes may be allowed after the core committers consider the change.

The following types of changes are allowed for patch releases. For example, following the release of 9.1.0, these changes can be committed to 9.1.x for inclusion in 9.1.1.

  • criticals
  • non-disruptive bug fixes
  • non-disruptive contributed project blockers
  • API documentation improvements
  • patch-level library updates (typically limited to security updates or important bugfixes)
  • non-disruptive coding standards cleanups (but not the phpcs.xml.dist rule itself. Additional rules should only enabled in minor releases.
  • issues for backport to D7 that meet the above criteria

Internal code cleanup that improves maintainability and is not disruptive may sometimes be backported to a patch release, but this is always at committer discretion. API and feature additions are not allowed, for compliance with semantic versioning.

Minor releases

Drupal core has a six-month minor release cycle. Minor releases provide new improvements and functionality. They do not break backward compatibility (BC) for public APIs.

The following types of changes are allowed for minor releases in addition to those allowed for patch releases. For example, following the release of 9.1.0, these changes will not be committed to 9.1.x, but instead can be committed to 9.2.x for inclusion in 9.2.0.

Functionality and frontend

  • new features
  • changes to behavior that existing sites might rely on
  • string, user interface, or render array changes
  • CSS, markup, or template changes (except for stable base themes)

APIs

  • changes to @internal APIs
  • new APIs or API improvements with backward compatibility (BC)
  • internal refactoring or improvements to maintainability with BC
  • new deprecations

Third-party code

  • patch- and minor-level library updates
  • new library dependencies
  • deprecations of a previous dependency once its code is no longer used

Coding standards

  • new coding standards
  • enabling additional rules that are already a part of the core ruleset, but currently ignored
  • risky or disruptive cleanups to comply with coding standards

High-risk and disruptive changes

  • changes requiring an upgrade path
  • changes that risk regressions
  • other disruptive bug fixes or high-risk changes

Maintenance Minor releases

The following types of changes are allowed for maintenance minor releases.

  • Certain critical or major bug fixes
  • Critical API compatibility backports
  • PHP and JavaScript dependency updates
  • PHP version compatibility fixes 

Major releases

Starting with the Drupal 8 to 9 major version upgrade, Drupal major releases have adopted a continuous upgrade path. Under the core deprecation policy, APIs will be deprecated continuously over the course of Drupal development.

No BC breaks should be introduced in the next major version other than the removal of deprecated code. This makes transition to the next major version easier and less  costly for users and developers.

For example, when an API is to be for removed in in the next major version, the replacement must be available in the previous major branch, and the old API must have already have been deprecated.

During the minor release cycle immediately prior to a major release, new disruptive deprecations may be deferred for removal until two major releases ahead (e.g. deprecated in 10.3.0 and will be removed in 12.0.0). This is to allow a window for contributed modules to update to the next major release and declare compatibility, with the reasonable expectation that once they've done so, further API removals to the forthcoming major branch won't be introduced.

Alphas for minor versions

The goal of the alpha phase is to provide a testing target for theme or module developers and site owners of the upcoming minor release. Alpha releases include most of the new features, API additions, and disruptive changes that will be in the upcoming minor version.

Core developers should plan to complete changes that are only allowed in minor releases prior to the alpha release. After the alpha release, such changes are usually committed to the next development branch.

There are no specific restrictions on what changes are allowed in alpha releases beyond the allowed changes for minors. But additions and disruptive changes are backported to the alpha only at committer discretion, with criticals, strategic initiatives, and product management priorities as the first focus.

Alphas for major versions

Alpha releases for major versions include some of the most important breaking changes. Such changes include updated platform requirements and major dependency updates. However, significant breaking changes can still occur between an alpha version and the final release. Such change may be major dependency updates and the removal of deprecated code.

There are no specific restrictions on what changes are allowed in alpha releases beyond the allowed changes for minors, But if the change is also allowed in a minor version, it must be backported to the corresponding branch of the previous major version. For example, a new API added to Drupal 9.0.x was also required to be backported to 8.9.x. Furthermore, if the change is not allowed in a minor version (for example, removing an API), then there must be an accompanying deprecation for the removal in the corresponding version of the previous major. (See the explanation of the continuous upgrade path above.)

Betas for minor and major versions

The goal of the beta phase is to prepare a polished, stable release, and to provide a testing target for theme or module developers and site owners.

We restrict changes during the beta phase in order to reduce disruptions and manage technical debt. New features and APIs must be targeted for the next development minor instead, and public APIs must remain stable.

The release of the first beta is a firm deadline for all feature and API additions. Even if an issue is pending in the RTBC queue when the commit freeze for the beta begins, it will be committed to the next minor release only.

The following types of changes are allowed during the beta phase:

  • criticals
  • bug fixes and contributed project blockers, if they are non-disruptive, or if the impact outweighs the disruption
  • API documentation improvements
  • patch- and minor-level library updates
  • string changes
  • user interface changes to fix usability or accessibility issues, if the impact outweighs the disruption
  • minor API additions or internal API changes to fix bugs, if the impact outweighs the disruption
  • changes requiring an upgrade path, if the impact outweighs the disruption
  • Certain other issues with high impact and low disruption at committer discretion only.

Release candidates for minor and major versions

The primary goal of the RC phase is to ensure stability for release.

Before each minor or major release there will be a release candidate phase. The guidelines for which patches can be committed to release candidates are the same as for patch releases.

Additional information

Experimental modules

Experimental modules have their own versions, separate from core's. Their version may change between patch and beta releases based on the changes allowed for that version.

New experimental modules may only be added in minor releases. See the experimental modules policy for more information.

Extensions approved for removal

This include extensions with a lifecycle of deprecated.

The following types of changes are allowed:

  • issues to maintain a stable upgrade path.
  • issues to maintain data integrity.
  • issues to maintain compatibility with the next major version.
  • security.
  • issues for the deprecation and removal.

Is the change disruptive?

A change is disruptive if it:

  • Has a high risk of introducing regressions
  • Introduces a BC break that will affect many contributed modules, or require some contributed modules to make non-trivial changes
  • Introduces behavior or functionality changes that may impact sites
  • Will require internal refactoring or rewriting of core subsystems, as these changes tend to introduce technical debt and regressions
  • Will require widespread documentation or code style updates which are likely to conflict with other patches in the queue
  • Will require changes across many subsystems and patches in order to make core consistent.
  • Will require changes to site owner process, core development processes, or core release processes
  • Will require documentation updates.
  • Will affect data on existing Drupal sites.
  • Will require a data upgrade path.

The above are all considered disruptive when they are changes from the previous minor release, or from a previous beta or release candidate pre-release milestone.

Definitions of terms

Backward-compatibility (BC) break (#)
A backward-compatibility break is a type of API change that requires changes in code implementing a public API. This can be anything from changing the parameters of a procedural function to renaming an interface or removing a hook. See [policy, then meta] Document @internal APIs both explicitly in phpdoc and implicitly in d.o documentation for ongoing discussion of what is a public API vs. internal API.
Backward-compatibility (BC) layer (#)
Many API changes can provide a backward compatibility layer that allows code using the old API to continue to work. For example, if a method has a badly misleading name, a BC layer can be preserved by leaving the badly-named method as a wrapper for the new one and marking it deprecated. When a BC layer is not feasible, or providing a BC layer would introduce significant technical debt, the change should be postponed.
Drupal core branch maintainers (committers)
The Drupal core branch maintainers are the core committers with the authority to commit functional code changes to the active branches of core. (Subsystem maintainers and topic coordinators in MAINTAINERS.txt are not branch maintainers.)
Issue category
See the category settings for issues for guidelines on what is a bug, task, or feature.
Issue priority
See the priority settings of issues for explanation of what is critical, major, normal, or minor. Committers have final discretion over each issue's priority, but use your best judgment to set it accurately now.

Help improve this page

Page status: No known problems

You can: