Allowed changes during Drupal core release cycles | Core change policies | About guide on Drupal.org

Allowed changes during Drupal core release cycles | Core change policies | About guide on Drupal.org
Skip to search
Can we use first and third party cookies and web beacons to
understand our audience, and to tailor promotions you see
Advertising sustains the DA. Ads are hidden for members.
Join today
On this page
How to evaluate issues
Patch releases
Minor releases
Functionality and frontend
APIs
Third-party code
Coding standards
Deprecations
High-risk and disruptive changes
Maintenance minor releases
Major releases
Alphas for minor versions
Alphas for major versions
Betas for minor and major versions
Release candidates for minor and major versions
Additional information
Experimental modules
Extensions approved for removal
Is the change disruptive?
Definitions of terms
Core change policies
Allowed changes during Drupal core release cycles
Backport policy
Change records
Continuous upgrades between major versions
Core gates
Criteria for evaluating proposed changes
Drupal core backend backwards compatibility and internal API policy
Drupal core frontend backwards compatibility (BC) policy
Experimental modules and themes
Frontend Developer tools for Drupal core
How to deal with a random test failure
How to deprecate
How to deprecate and remove an extension
Set platform requirements
Supported browser approval
Allowed changes during Drupal core release cycles
Last
updated
on
15 March 2026
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,
main
Issues may be assigned to a specific branch in the following situations.
A bug that
only
affects a specific branch.
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)
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 (
dependency update policy
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
Deprecations
disruptive
deprecations scheduled for removal in a major release that is more than one year away
non-disruptive deprecations scheduled for removal in the next major release
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 user or handbook 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. Release managers make the final decision about when a change can be allowed based on its disruption.
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.
Related Content
Core dependency release cycles
Dependency changes allowed in Drupal releases.
Drupal core backend backwards compatibility and internal API policy
What parts of the Drupal codebase are considered stable and reliable APIs, and which are not
Help improve this page
Page status:
No known problems
You can:
Log in, click
Edit
, and edit this page
Log in, click
Discuss
, update the Page status value, and suggest an improvement
Log in and
create a Documentation issue
with your suggestion
Drupal’s online documentation is © 2000-2026 by the individual contributors and can be used in accordance with the
Creative Commons License, Attribution-ShareAlike 2.0
. PHP code is distributed under the
GNU General Public License
Infrastructure management for Drupal.org provided by
Need a Drupal 7 extended support partner? Consider Tag1.
News items
News
Planet Drupal
Social media
Sign up for Drupal news
Security advisories
Jobs
Our community
Community
Services
Training
Hosting
Contributor guide
Groups & meetups
DrupalCon
Code of conduct
Documentation
Documentation
Drupal Guide
Drupal User Guide
Developer docs
API.Drupal.org
Drupal code base
Download & Extend
Drupal core
Modules
Themes
Distributions
Governance of community
About
Web accessibility
Drupal Association
About Drupal.org
Drupal is a
registered trademark
of
Dries Buytaert