Release cycle FAQ

What's an API change?

As a general rule, an API change means anything that would cause a module or theme developer, or someone writing documentation about the next version of Drupal, to have to redo work. Changing function or hook signatures, adding/removing API functions and hooks, adding/removing/changing theme functions, adding/removing/changing template files or template variables, and so on.

Once we hit API freeze, we only allow API changes if they go towards fixing critical bugs. If there's a way to fix a "major" or "normal" bug without changing the API, we go with that, same as we do in stable releases.

What's a critical bug?

A critical bug is something that breaks Drupal so horribly in a way that affects so many users that we can't possibly release without it being fixed. Priority levels of issues has a good breakdown of the differences in priority levels.

As a general rule, these include:

• Upgrade path-related bugs
• Bugs that cause data loss
• Bugs that create security vulnerabilities
• Serious regressions from behaviour that worked in previous releases
• Bugs that cause testbot to fail

The ultimate call on what is critical or not is with the core maintainers.

There is, however, a much longer list of things that are not critical bugs, including:

• Awful problems that also existed in previous releases. If they were not bad enough to block the release of the previous version of Drupal, they will not block the next release, either.
• Edge cases that, while pretty terrible, affect a small minority of users and those users have some kind of reasonable way to work around the problem.
• Developer Experience (DX) problems that do not prevent Drupal from being used.
• User Experience (UX) problems that do not prevent Drupal from being used.
• Themer Experience (TX) problems that do not prevent Drupal from being used.

What's the harm in letting in API changes late?

There are consequences every time we deviate from the overall release plan:

• Takes time and focus away from critical, release-blocking issues: Since none of us are being paid to work on Drupal core, we need to allocate our attention and focus in the most efficient way. That generally means focusing on critical, release-blocking bugs first, everything else second.
• Sends a signal to all other core contributors that we're still in "polish" phase: All of us have our own pet niggles with Drupal that we really wish were better than they are. Tweaking a theme function here. Adding a hook there. If the core maintainers send up the signal that these sorts of patches are still on the table, suddenly everyone wants to jump in and add their own pet project, too. Which means critical issues aren't being looked at, and core maintainers need to divide their attention.
• Creates morale issues and dissent: The flip side of the above. When people perceive favouritism or special treatment (contributor X's "polish phase" patches are getting committed during release phase while contributor Y's were bumped to Drupal 9), it builds resentment and mistrust. It also builds this feeling when the vast majority of the team is working hard on the "core" issues leading directly to release, but there are other people off in the sidelines scratching their own itches.
• Makes the release cycle even longer: Each one of these patches are not something that happens for free. Each patch that goes into core needs to be read, evaluated, reviewed, tested, tweaked, tested again, given final look-over by a core maintainer, and finally committed. This is all time not being spent on the "core" issues that get the release out the door.

  Additionally, every time code changes, it opens up the possibility for follow-up issues, or at the very least re-rolls in other patches to fix tests or whatnot.

• Eliminates incentive to join with community at appropriate times: If we don't ever end code thaw, and we don't ever end polish phase, what on earth is the incentive for helping out during those times when we as a community really need people to rally?

  If we are changing APIs and the theme system months after we declared an API/markup freeze, what's the incentive for porting modules and themes during API freeze? Much safer to wait until the next version actually ships, which inevitably leads to a major core release with 0 contributed module support, which isn't good for anyone.

Will one little patch like this end the world? No, of course not. But it's death by a thousand cuts. So core maintainers and major core contributors tend to give more and more pushback the later in the cycle major changes are introduced.

What about normal and minor priority bug fixes?

No thresholds have been added for normal and minor priority issues, however the 'mini code slushes' will allow normal and minor bug fixes to be committed while working towards getting the major/critical queues below threshold.

What about Drupal 6?

Issue thresholds do not apply to Drupal 6. There are significant changes between Drupal 6 and Drupal 7, and Drupal 6 does not have many automated tests. This makes the process of backporting even bug fixes more involved than from Drupal 8 to Drupal 7.

Can I add new major or critical issues when the counts are over the threshold?

Yes! These are thresholds rather than limits - and only affect which patches will be committed, not what can be reported or worked on during code slushes. One thing to bear in mind is that having the thresholds is likely to lead to closer triage of the core issue queue, and more of a distinction made between bugs, tasks and feature requests. You may find your issue is triaged to a different priority or category. Issues can be better triaged if there is a clear explanation of the problem (including steps to reproduce) and/or a clear explanation of the proposed solution.