Problem/Motivation

See original discussion in #3108658: Handling update path divergence between 11.x and 10.x for some background and https://www.drupal.org/about/core/policies/core-release-cycles/release-p... for an overview of the new release cycle.

As of Drupal 11, we're starting to release 'maintenance minors' on the previous major branch - the first of these will be Drupal 10.4, released after Drupal 11.0.0.

For a while, we've supported minor releases for one year. This introduces a new problem that we've never had before, and didn't fully think through when we originally decided to issue maintenance minors.

The idea of a maintenance minor is broadly twofold:
1. To enable contrib modules to maintain support for both Drupal 10 and 11 more easily. This means selected API additions can be backported from 11.1.x to 10.4.x
2. To update PHP and JavaScript dependencies, so that it's easier to keep on security- (and bug-)supported versions of those dependencies until 2026, as well as allowing us to support newer PHP versions when they come out, like PHP 8.4

Both #1 and #2 mean that for example when Drupal 10.4 is released, it is likely to be a on a newer version of CKEditor 5 than Drupal 11.0.0. It is also likely to have small API additions and bugfixes not available in 11.0.0 too.

Additionally, a module that adds support for a new API added in 10.4 - let's say an annotations to attributes conversion, or just calling a new method to avoid a deprecation, could reasonably expect to add a core dependency that is >= 10.4 without having to do >= 10.4 || >= 11.0

Proposed resolution

Now that #3108658: Handling update path divergence between 11.x and 10.x is in, we could add an empty hook_update_N() to 11.1, and backport this to 10.4 to use the new equivalent updates API, and if a site updates to 10.4, then tries to update to 11.0, system_requirements() will prevent the update from going ahead when it finds the equivalent update is missing on 11.x. This would prevent a site from thinking it has done a successful update, then hittting weird issues (and potentially in the worst cases data loss or site downtime) after that, however, it would still be annoying to only be told you can't update to 11.0 when you've already updated your code base, and then have to either roll your code base back to 10.4, or keeping going to 11.1.

We should also see if we can come up with another strategy, either in code or on d.o or via the release process, to prevent this situation as much as possible.

Sub-issues

Remaining tasks

User interface changes

Introduced terminology

API changes

Data model changes

Release notes snippet

Comments

catch created an issue. See original summary.

catch’s picture

catch
he/him
Primary language English
commented
Parent issue: » #3332028: [meta] Requirements for tagging 11.0.0
xjm’s picture

xjm
she/her
Primary language English
commented
Title: Prevent 'downgrades' from maintenance minors to older minor releases for the next major version » [meta] Prevent 'downgrades' from maintenance minors to older minor releases for the next major version
Issue summary: View changes

Reorganizing the IS a little and surfacing the urgent child issue.

xjm credited Balu Ertl.

xjm credited drumm.

xjm’s picture

xjm
she/her
Primary language English
commented
Issue summary: View changes

Some ideas from @Balu Ertl in #d11readiness Slack:

  • Write an article on drupal.org/blog. Include a well-drawn illustration to visually support the understanding through an example (eg. CKEditor might get newer in 10.4 than in 11.0).
  • On the release notes page of 10.4, 11.0 and 11.1 compose a paragraph of text referencing the article above.
  • Post a change record focusing mainly on the related code change (if any), referencing the above article only as a background.
  • Core’s newly implemented Announcements module should also show up a post in relation with this topic – (if that feed is different from the Drupal blog)
  • Make sure the above article is curated into the upcoming editions of the Weekly Drop newsletter
  • Tweet the article link by the TheDropIsAlwaysMoving

@drumm also said in a meeting with some core committers and DA infra staff that we should do whatever we can to enforce this at the Composer level, and not add any special custom metadata to Drupal.org about it (i.e., ideally not branch or release configurations on d.o.)

drumm’s picture

drumm
he/him
Location NY, US
commented

If I understand correctly, everything is still backports and 11.1 will be released before 10.4. A forward upgrade will always be possible, but should skip the earlier minor versions.

Ideally the Composer solver should disregard 11.0 when someone has 10.4. Maybe conflict could be added to the site’s root composer.json?

Otherwise, a post-update warning is good. Many might be skipping 11.0 when 11.1 is available anyway. Someone who does land in this situation isn’t at a dead end.

xjm’s picture

xjm
she/her
Primary language English
commented
Parent issue: #3332028: [meta] Requirements for tagging 11.0.0 » #3465335: [meta] Requirements for tagging 11.1.0-beta1 and 10.4.0-beta1

A lot of the specific implementation issues for this will end up as part of 10.4. We might also want to backport things to 11.0 where necessary, but that meta will be marked fixed shortly, so tracking under the active one instead.

longwave’s picture

longwave
he/him
Primary language English
Location UK
commented
Status: Active » Needs review

The child issues are done, so I think this is done too?

dww’s picture

dww
we/he/they
commented

At #3463226-25: Use the new equivalent updates API to prevent updates from 10.4.0 to 11.0.0, @catch raised the possibility we might want another pair of equivalent updates to prevent downgrading from 10.5.x to 11.1.x. Should we open another follow-up for that under this meta?

quietone’s picture

quietone commented

@dww, yes, that makes sense to me. Thanks.

catch’s picture

catch
he/him
Primary language English
commented

Yeah at some point we will have a 10.x minor with no updates or new APIs, and an update to 10.6.x to 11.2.x might be OK, but even if that happens we probably still need an issue each time so we don't forget to check.

catch’s picture

catch
he/him
Primary language English
commented

We didn't do this for 11.2/10.5. It is probably OK, now there's a couple of 10.x maintenance minors people should be able to figure out the relationship between the 11.x and 10.x branches for people who are already on 10.x. Maybe we need an extra sentence for the minor release notes to say '10.X.x users should update to 11.X.x or higher', that might be enough of a reminder without having to add a new update function every minor.

Wondering if we want to specifically open an issue to do the same thing again for 12.1 though (and whatever the equivalent 11.x maintenance release is that comes out) to prevent downgrades to 12.0 though, since then it'll be new again for people who started on 11.x - so always do this for the second release on a major branch or something.

quietone’s picture

quietone commented

I added a draft sentence to the 10.6.0 release notes google doc. Once that is agreed to it can be used in future release notes.

As for making the 12.1.x issue, in order to remember that for each major release I added a new item to #3449806: [12.x] [meta] Release Drupal 12 in 2026.

quietone’s picture

quietone commented
Status: Needs review » Reviewed & tested by the community

I should add that the 'release prep' issues for minor releases already has an item for using the equivalent update, so that should be happening for each minor release. For example, #3528698: [meta] Release preparation steps for 11.3.0 and 10.6.0.

With all that I think we have this 'in place' for the future as well.

xjm’s picture

xjm
she/her
Primary language English
commented

This does make me a bit nervous, but backporting empty update hooks to patch releases would be not-nice, so I guess we're sort of stuck for 10.5.x.

Since we've officially deferred disruptive deprecations, 10.6.x is more likely to be API-compatible with 11.2.x than 10.5.x was with 11.1.x, so I agree that release notes are probably sufficient for the next minor. However, I do think that we should resume adding them again with 12.1 and do so consistently in the future. We could even script this, honestly.

xjm’s picture

xjm
she/her
Primary language English
commented

Maybe we should add this to docs in addition to the metas?

xjm’s picture

xjm
she/her
Primary language English
commented

Adding credit for @quietone.

xjm’s picture

xjm
she/her
Primary language English
commented

Also to our minor spreadsheets. It should be on the same day as opening the release branch for the new minor, immediately after it.

godotislate’s picture

godotislate
he/him
commented

Since we've officially deferred disruptive deprecations, 10.6.x is more likely to be API-compatible with 11.2.x than 10.5.x was with 11.1.x, so I agree that release notes are probably sufficient for the next minor.

Can I suggest that the update hook not be skipped for 10.6.x? At the very least, to prevent someone from going from 10.6.x to 11.1.x, however unlikely that might be? Especially since 10.5/11.2 have the breaking CKEditor5 changes.

xjm’s picture

xjm
she/her
Primary language English
commented
Status: Reviewed & tested by the community » Needs review

@godotislate, that's a great point!

quietone’s picture

quietone commented

Added an item to the minor spreadsheet for this.

quietone’s picture

quietone commented

Since the point raised in #20 is specific to 10.6 I think that would be better discussed in it's own issue, a child of #3528698: [meta] Release preparation steps for 11.3.0 and 10.6.0.

Maybe we should add this to docs in addition to the metas?

What docs are these?

xjm’s picture

xjm
she/her
Primary language English
commented

What docs are these?

Um... well... that's a good question.

  1. One of them is an unpublished Google doc about release manager process for minors.
  2. Maybe also in the definition of maintenance minors although that is a bit high-level so maybe not.
  3. And something on the continuous upgrade path policy actually since this is about parity between the old and new major branches, although I keep struggling with exactly where to make any changes to that policy in its content.
catch’s picture

catch
he/him
Primary language English
commented

Someone in slack actually did go from 10.5 to 11.1 - we found out because they re-applied a patch that 'applied' to 11.1 but wasn't actually compatible with it, only 11.2, and hit errors that way. This patch issue is something that could happen to any site on 11.1 trying to update a patch file, but it does show that we're fixing a real and not entirely theoretical problem of people trying to update to the wrong versions and should probably try to do this each minor.

xjm’s picture

xjm
she/her
Primary language English
commented

In that case maybe we should backport this for 11.2/10.5? Edit: Well not really "backport" in this case, just fix in a patch release I mean.

catch’s picture

catch
he/him
Primary language English
commented

I think that the likelihood of this happening diminishes the longer the releases are out, the person in slack was trying to go to 11.1 to avoid a drush issue with 11.2 (probably dependencies, not sure if it's actually fixed or not, but if it is, or will be soon, that reason would go away). So 50/50 on preventing more people doing this vs. potentially some disruption from adding a no-op update to patch releases on both branches.

Version: 11.x-dev » main

Drupal core is now using the main branch as the primary development branch. New developments and disruptive changes should now be targeted to the main branch.

Read more in the announcement.