Last updated 17 February 2017.

The backport policy exists so that people working on issues can quickly see which versions a bug report or other issue should be fixed against and to avoid duplicate and unnecessary work.

Drupal 8.x minor versions

The primary target for bug fixes is the latest development branch of 8.x. For feature requests the primary target is the next development branch. More information on this subject can be found at the Core release cycle page.

Patches will be committed to the development minor dev branch, then cherry-picked backwards to ensure that there are no regressions from minor release to minor release. This also ensures that the development version has as many bug fixes as possible, since the criteria for which patches are eligible is wider than for the active minor branch.

Most patches can be cherry-picked between minor core versions, so will be applied to both branches by maintainers at the same time.

Some patches may require further testing, or changes in line with the backwards compatibility policy before they can be accepted into the current minor branch. Where this is the case core committers will indicate on the issue. In some cases we may decide to commit an issue only to the development minor branch, to avoid the risk of disruption in patch releases.

Drupal 7.x

Where an issue filed against 8.x also applies to 7.x, a separate issue should be opened against 7.x, related to 8.x via the 'Parent issue' field (this can be done using the "Add child issue" link on the 8.x issue). The new Drupal 7 issue should be prefixed with [D7] in the title to make it easier to distinguish it from the Drupal 8 issue. Alternatively the needs backport to D7 issue tag can be added to the parent issue to indicate that a child issue still needs to be created (but actually creating the child issue is preferred).

By default, 7.x issues should be marked postponed until the 8.x issue is fixed to avoid duplicate work. However, if there are good reasons to work on a fix independently (for example divergence between the 7.x and 8.x code bases or a different approach being needed), then the 7.x issue may be worked on and fixed independently. The 8.x issue can be closed normally once it has been fixed, the 7.x issue can be set to 'Active' when porting can begin.

Issues posted only against 7.x should have an explanation in the issue summary as to why there is no related 8.x issue (for example if they apply to a feature that was removed).

Drupal 6.x

Drupal 6 is end of life, but security issues may be posted against

Drupal 9.x

No bug reports should be posted against 9.x. There may be cases where all attempts to resolve a bug in 8.x get exhausted and the only way to resolve it is via an API break requiring a new major version, but this is something that should be discussed with framework and release managers before changing the version.

Once the 9.x branch is open for development, this policy will be updated to document the workflow for fixing issues that exist in both 8.x and 9.x. (The general goal, however, is not to hold up Drupal 8 backports on "ideal" fixes that involve far-reaching changes or refactoring that would only be appropriate for Drupal 9. Instead, the issue can usually be fixed in a minimal backportable way for Drupal 9 first, then a separate cross-linked Drupal 9 issue can be created for the far-reaching fix which can continue at its own pace.)

Why do we do it like this?

  • Applying fixes to the most recent version of Drupal first and backporting them afterwards ensures that the fix won't get "lost" (and never fixed) in future releases of Drupal, and helps prevent older sites from experiencing regressions when updating to the newer version.
  • The focus of core developers, especially those who are formal or informal gatekeepers for particular areas of core, is often on the current development version. Therefore patches against 8.x will usually get more attention than those against 7.x.
  • The active issue queues of previous stable versions should be limited to patches going through the backport process or those which don't apply to the new version, keeping them more manageable for branch maintainers who while the release is stable are in 'maintenance mode'.
  • Applying patches to the current development version gives them a window (even if it's a short one) to be tested in the 'unstable' version of core, before they are applied to the version that thousands of people are using. This gives a bit more time to find inadvertent bugs or other side-effects that may be introduced.

For more information on the history and rationale behind the current policy, see #1050616: Figure out backport workflow from Drupal 8 to Drupal 7 (the issue in which this was discussed and agreed upon) and #2462101: [policy, no patch] Update backport policy to account for 8.x minor versions and 7.x divergence (where the policy was updated for the new core release cycle).

See What patches may be added to a stable release of Drupal core? for further details.


mErilainen’s picture

"Patches will be committed to the development minor dev branch, then cherry-picked backwards to ensure that there are no regressions from minor release to minor release."
So now (8.3.0 was just released last week) bug fixes go to 8.3.x-dev and they are cherry picked to 8.4.x-dev? Isn't that "forward cherry-picking"? Or does that kind of term even exist?
Also there is inconsistency between terms "development branch" (on this document) and "development cycle" (on the referenced "Core release cycle" page). Is "current" the same as "latest"?

xjm’s picture

"Production branch" and "patch release branch" both refer to the branch for the release series of the current minor version. So if the latest release of Drupal is 8.4.2, the production (patch) branch is 8.4.x-dev, and the next release from the branch will be 8.4.3.

"Development branch" and "minor branch" refer to the branch for the next minor release, the one that hasn't been released yet. So if the latest Drupal release is Drupal 8.4.2, the development (minor) branch is Drupal 8.5.x and the next release from that branch will be Drupal 8.5.0.

We don't forward-port patches; we backport them. So if the latest release of Drupal is 8.4.2, and the issue is an allowed change for patch releases (like a non-disruptive bugfix), the patch is first committed to 8.5.x (the development branch) and then cherry-picked to 8.4.x . The first release that includes it will be Drupal 8.4.3.
However, if the latest release is 8.4.2 and the change is only allowed in minor releases (like a feature addition), the patch will be committed to 8.5.x only, not cherry-picked, and the first stable release that includes it Drupal 8.5.0.

The "development cycle" is just a general term that refers to the six-month minor release cycle for Drupal 8, where the branch goes through development, alpha, beta, and release candidate phases and is then release, and the overall major release cycle for the next major release.

Hope this helps! Maybe someone can incorporate these answers into the page text for this handbook page or other relevant ones so that it's more clear. :)