Last updated March 20, 2017.

This policy explains what changes can be made to Drupal 8 following the release of 8.0.0.

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

Table of contents

How to evaluate issues (#)

This section describes how to evaluate core issues for 8.1.x (as an example).

If the issue:

  1. Is critical: evaluate its impact vs. disruption to decide whether it stays filed against 8.1.x or gets moved to 8.2.x.
  2. Only affects an experimental module: Evaluate its allowed changes based on the experimental module's version.
  3. Requires a BC break for a public API: implement it in 8.2.x with a BC layer. See major release allowed changes below.
  4. Provides new functionality or a new API: move it to 8.2.x.
  5. Changes the data model (upgrade path), translatable strings, markup, CSS, user interfaces, render array structures, @internal APIs, third-party libraries, functionality, etc.: move it to 8.2.x.
  6. Improves APIs or internal code flow with BC (including cleaning up existing use of deprecated code): move it to 8.2.x.
  7. Fixes a bug, blocks a contributed project, or should be backported to Drupal 7: Evaluate its impact vs. disruption to determine whether it should be filed against 8.1.x or 8.2.x.

Patch releases (#)

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

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.

Since the primary goal of patch releases is to provide bug fixes for production sites, the most important consideration is always disruption to these sites. Any change that risks disruption must be considered carefully and usually postponed to the next minor or major version, depending on the nature of the change.

Minor releases (#)

Drupal 8 introduces a six-month minor release cycle. Minor releases provide new improvements and functionality without breaking 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 8.1.0, these changes will not be committed to 8.1.x, but instead can be committed to 8.2.x for inclusion in 8.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

Coding standards

  • new coding standards rules

Disruptive changes

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

As with patch releases, we will initially be conservative about what changes are accepted, committing a limited new feature set to 8.2.x to reduce the risk of regressions and disruption and help ensure a stable, on schedule minor release. See [policy, then meta] Document @internal APIs both explicitly in phpdoc and implicitly in d.o documentation for ongoing discussion of what can be changed in minor releases. Also see the Drupal 6 and 7 allowed changes policy.

Major releases (#)

Starting with the Drupal 8 to 9 major version upgrade, Drupal major releases will adopt a continuous upgrade path. Following the new core deprecation policy, APIs will be deprecated continuously over the course of Drupal 8 development. To make the transition to Drupal 9 easier and less costly for users and developers, no new BC breaks should be introduced in Drupal 9 other than the removal of deprecated code. That is, any API intended for removal in Drupal 9 should be deprecated in Drupal 8 first, with the new preferred API added in a backwards-compatible way in a Drupal 8 minor release.

Alphas for minor and major versions (#)

The goal of the alpha phase is to begin the preparation of the minor release and provide a testing target for theme or module developers and site owners. 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 for inclusion in that minor. Following the alpha release, such changes will be committed primarily to the next development branch instead.

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.

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
  • 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 (#)

Before each minor or major release there will be a release candidate phase. The following types of changes may be considered during the release candidate phase for inclusion in the first supported release of that minor or major version.

  • criticals
  • rc eligible issues, which include:
    • Non-disruptive coding standards changes (revert if they conflict with a critical). (Be sure to follow the scope guidelines for coding standards issues.)
    • Testing improvements (revert if they conflict with a critical).
    • Docs changes (revert if they conflict with a critical).
    • Updating a library to the latest patch-level release (revert if they conflict with a critical).
    • Updating to a newer major or minor version of a fully released library will be triaged by committers on a case-by-case basis.
    • Changes to functionality already marked experimental.
  • Issues prioritized by committers as RC target issues. Only core committers should add the 'rc target' issue tag.
  • Other issues may be backported to the RC at committer discretion once they have been committed to the development branch. We no longer evaluate "rc target triage" issues.

The primary goal of the RC phase is to ensure stability for release. As such, changes are restricted and made only at committer discretion.

Additional information

Experimental modules (#)

Experimental modules have their own versions, separate from core's, and may change even 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.

Is the change disruptive? (#)

A change is disruptive if it:

  • Introduces a BC break that will affect many contributed modules, or require some contributed modules to make non-trivial changes
  • 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 affect data on existing Drupal 8 sites.
  • Will require a data upgrade path.

Issue summaries matter (#)

It's important to have a good issue summary so branch maintainers can quickly understand each change and make fair decisions about it. With the definitions above in mind, be sure to describe:

If your issue summary is unclear or not up to date, branch maintainers may mark your issue "Needs work" for an issue summary update.

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 8 branch maintainers
The Drupal 8 branch maintainers are the core committers with the authority to commit functional code changes to the 8.x 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. Branch maintainers have final discretion over each issue's priority, but use your best judgment to set it accurately now.