Now that Drupal 8-beta 1 has been released. it’s important for all contributors to core to understand the criteria for acceptance of core patches during this phase of the development cycle.
This proposal is based on discussions between @Dries, @catch, @alexpott, @webchick, @effulgentsia, and @xjm, with input from numerous other core contributors (thanks everyone!).
Goals
- 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.
Important note about issues worked on during DrupalCon Amsterdam
Issues with work posted during DrupalCon Amsterdam will be given special consideration until Oct. 27 (which will be the commit freeze prior to the tagging of 8.0.0-beta2) (meaning they can still be accepted for commit even if they don't fit the criteria below). Drupal 8 branch maintainers will triage completed work from these issues separately so that your hard work from the sprints is considered for inclusion in beta 2. However, keep the criteria below in mind for all issues you work on going forward.
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:
- 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.
If your issue summary is unclear or not up to date, branch maintainers may mark your issue "Needs work" for an issue summary update.
What changes are allowed?
A. Not frozen in beta
Improvements can be accepted up until the first release candidate for:
- CSS
- JavaScript
- markup
- translatable strings
- documentation
- automated 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.
B. Mostly unfrozen in beta
Improvements can be accepted for the following if the issue is critical, or if branch maintainers judge the improvement to be greater than the disruption it introduces (see below).
- bug fixes
- external PHP and asset library updates
- usability and user experience improvements
- accessibility improvements
- performance improvements
- security improvements
- changes that reduce fragility
- follow-ups from a recent critical or major change
Otherwise, the change should be postponed.
C. Mostly frozen in beta
For any tasks that do not meet the above criteria, whether or not the change will be accepted depends on its priority:
- If the task is critical, the change can be accepted.
- If the task is major, the change can only be accepted if branch maintainers judge the improvement to be greater than the disruption it introduces (see below).
- If the task is minor or normal, the change should be postponed.
Keep in mind that branch maintainers have final discretion.
D. Frozen in beta
All new features should be postponed.
Even acceptable changes should have BC layers
If a change can be accepted based on the criteria above but introduces a backward compatibility break, the patch for the issue should also provide a backward compatibility layer if feasible and where the BC layer would not introduce significant technical debt, or where the API is sufficiently new that there is no likely chance of it having any consumers anywhere.
How do I know if the improvement is greater than the disruption?
Update your issue's summary, then get feedback from the branch maintainers. (You do not need a maintainer's approval if it specifically says above that the change can be accepted.)
Postponed until when?
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.
Drupal 9.0.x
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.
Diagram
A diagram is forthcoming so you don't have to read all this text every time. ;)
Example issues
A list of example issues and the reasoning for when and whether each can be accepted is forthcoming.
Next steps
If you have an outstanding Drupal 8 issue and you are unsure if it can be accepted during the beta phase, use these criteria to evaluate the change, and update your issue summary (as above). You can post the issue to link to your issue here for feedback.
Please comment below if you've read the issue here and are still unclear as to when during the release cycle the patch can be accepted.
Appendix: Some definitions
- Drupal 8 branch maintainers
- The Drupal 8 branch maintainers are the four core committers with the authority to commit functional code changes to the 8.0.x branch of core: catch, alexpott, webchick, and Dries. (Other 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 (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.
- 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.
- 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.
- Change disruption (#)
- 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.