What patches may be added to a stable release of Drupal 7?

Last updated on
6 October 2020

Preamble

The short version is: Don't break (known) existing contrib modules and themes or (unknown to us) potentially existing custom modules and themes.

However, the automated testing framework in Drupal 7+ provides a bit more of a safety net to catch regressions and therefore some classes of patches that were not possible before are now possible to add to a stable release (subject, as always, to the backport policy).

The following table outlines the general guidelines on what types of changes can be made. Final discretion always lies with the Drupal core maintainers. (See the original, lively discussion at http://groups.drupal.org/node/210973)

Note that Drupal 8's policy is covered separately.

What constitutes Drupal's APIs?

This table defines what parts of the Drupal codebase are considered stable and reliable APIs, and which parts module and theme developers should not rely on. The goal is to provide a greater degree of clarity about what constitutes Drupal's APIs and what constitutes implementation details.

Type of change Description Guidelines
Data change Anything that would break the "we break your code, not your data" rule. Critical issue only
API change Changing return values of a function/hook, adding new required parameter to function/hook. Would force contributed modules to change because something in core changed. Critical issue only
API addition Optional parameters on a function/hook, new hooks/helper functions. Would provide new capabilities which contributed modules could choose to rely on. Release notes mention
Data structure (form/page array element) change Moving page elements to different fieldsets/containers, adding additional form elements, etc. Affects modules that do heavy altering of forms/pages.

A proposed framework for evaluating these changes is at http://groups.drupal.org/node/210973#comment-701613

Generally, critical issue only. While these seem harmless enough on the surface, they can have unintended consequences. (e.g. #1346760: Add a scalable weight select element broke Context module)
Markup change Changing output of theme functions, template files to remove wrapper markup, add . Requires changes to themes in order to stay in sync with core. Critical issue only
Markup addition Additional classes or attributes exposed to template files. Themes could make use of them if desired, but would not be required to. Release notes mention
String change (admin-facing) Any changes or additions to any admin-facing string (string wrapped in t() or st()). Forces translators to translate new/changed strings, and multilingual sites see English strings until this is done. Release notes mention, but string-affecting patches will be committed as early in the monthly release cycle as possible to give translators time to prepare.
String change (user-facing) Any changes or additions to any user-facing string (string wrapped in t() or st()); for example comments or the log in form. Forces translators to translate new/changed strings, and multilingual sites see English strings until this is done. Major/Critical string problem only. (e.g. typo, string is saying completely wrong information)
String change (error message) Any changes or additions to any error messages (string wrapped in t() or st()); for example form validation errors or error messages coming from exceptions. Forces translators to translate new/changed strings, and multilingual sites see English strings until this is done. Major/Critical string problem only. (e.g. typo, string is saying completely wrong information); imagine trying to debug a problem on your site in Martian. :)
UI change Any changes or additions to the user interface, such as new administrative pages, re-ordering of fields, etc. Release notes mention, as long as the "conceptual" things for users to know remain the same to grapple with, and the change is not systemic (e.g. switching the order of all form buttons).
Feature addition Any changes or additions to the user interface, such as new administrative pages, additional options on an administrative page, new permissions, etc. Release notes mention, as long as they are "opt-in." For example, a new checkbox that could optionally be checked, a new theme or module which could be enabled or not.

Note that #1505456: Add a "Backports" or "Drupal update" module to Drupal 7 core so that UI changes from Drupal 8 can be backported is a discussion about creating a "backports" module in core to hold features / UI improvements from the next Drupal version, which could loosen these guidelines further.

Help improve this page

Page status: No known problems

You can: