Last updated 7 October 2015.
This document applied to the Drupal 8 beta phase and is no longer applicable to core development. It is retained here for reference only. Refer to the Allowed changes during the Drupal 8 release instead.
For background discussion, see.
- Reduce technical debt and focus on necessary work to complete Drupal 8.0.0.
- Set guidelines to help contributors avoid focusing energy on issues which won’t be committed until 8.1.x or 9.0.x, since it can be frustrating to get a patch to RTBC only to find it won’t be committed until 6-48 months in the future.
- Avoid moving issues to 8.1.x or 9.0.x prematurely when they're still acceptable and valuable during this phase of the release cycle.
- Reduce the need for contributors to consult core maintainers when contributing to the beta phase.
- Provide example issues with the reasoning for when and whether each can be accepted.
Table of contents
- How to evaluate issues
- What changes are "unfrozen"?
- What changes are "prioritized"?
- Is the change disruptive?
- Do I need a BC layer
- Appendix: Some definitions
How to evaluate issues (#)
Use the beta evaluation HTML template for issue summaries to evaluate an issue and document your assessment.
- Assess and correct the issue category and issue priority. Make sure only actual feature requests are marked as such; make sure only actual bugs are marked as such (i.e. a failing test can be written); set the priority correctly. Maintainers have final discretion on issue priorities.
- Assess whether it is a change only to one or more unfrozen categories (see below): CSS, markup, translatable strings, documentation, automated tests.
- Assess whether the primary purpose of the change is a prioritized change (see below): performance, security, usability, accessibility, bug fix, or a followup to a recent critical or major.
- Assess whether the issue reduces fragility. Examples: narrowing an API, removing unused and untested functionality, correcting misspelled or wholly inaccurate method names. Whether or not an issue reduces fragility is at core maintainer discretion and should be discussed on a case-by-case basis.
- Assess whether the impact is greater than the disruption (see below). If the summary doesn't communicate the impact or the disruption, leave a note on the issue asking the contributors to update it. Whether or not the impact is greater than the disruption is at core maintainer discretion and should be evaluated on a case-by-case basis.
- Ensure the above information is clear from the issue summary (see below). You can use the beta evaluation template.
- If the issue is a feature request, it should be postponed.
- If the issue is unfrozen or critical, proceed with the issue.
- If the issue is major or a prioritized change, evaluate the issue's impact versus its disruption to determine whether it should be postponed.
- Otherwise, postpone the issue. Types of issue that should be postponed include:
What changes are "unfrozen" (1)? (#)
Improvements can be accepted up until the first release candidate if they only change the following:
- translatable strings
- automated tests (excluding BrowserTestBase tests)
Additionally, the provision of a Drupal 6/7 to Drupal 8 migration path is not strictly coupled to the release cycle, so that code remains unfrozen.
What changes are "prioritized" (2)? (#)
The following kinds changes are prioritized because they improve Drupal 8's stability or move Drupal 8 closer to a releasable state:
- bug fixes
- external PHP and asset library updates
- usability and user experience improvements
- accessibility improvements
- performance improvements
- security improvements
- follow-ups from a recent critical or major change
- code already marked for removal by 8.0.0
- Bugs and tasks that are tagged for backport to Drupal 7 and/or Drupal 6
Additionally, certain changes that reduce fragility are also prioritized. For example: Narrowing an API, removing unused and untested functionality, correcting misspelled or wholly inaccurate method names. Whether or not an issue reduces fragility is at core maintainer discretion and should be discussed on a case-by-case basis.
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 beta sites.
- Will require a data upgrade path.
Do I need a BC layer? (#)
For allowed changes that would introduce a backward compatibility break, a BC layer is needed unless:
- a BC layer is not feasible,
- providing a BC layer would introduce significant technical debt, or
- the API is sufficiently new that it is unlikely to be used anywhere.
What does it mean for the change to be postponed? (#)
Changes that are no longer accepted during the Drupal 8 beta phase will be allowed again in either a minor version (8.1.x) or the next major version (9.0.x).
Minor version target (e.g. Drupal 8.1.x)
New features, API additions, or internal refactoring that can be implemented in a non-BC-breaking way, or with a BC layer.
Major subsystem rewrites: for example, refactoring the render API to use object oriented programming techniques. Removing backwards compatibility layers added during the beta and in minor releases.
Issue summaries matter (#)
- What the change is
- Why the change is desirable
- Why the change has the category and priority it does
- What the impacts of making the change are for both core and contributed modules (see the notes about change disruption above).
If your issue summary is unclear or not up to date, branch maintainers may mark your issue "Needs work" for an issue summary update.
Appendix: Some definitions (#)
- Drupal 8 branch maintainers
- The Drupal 8 branch maintainers are the core committers with the authority to commit functional code changes to the 8.0.x branch 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.
- Backward-compatibility 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.
- 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.
- Minor version (e.g. 8.1.x)
- Drupal 8 introduces a six-month minor release cycle. Minor releases provide new improvements and functionality without breaking BC for public APIs. See the proposal to manage the Drupal 8 release cycle.