Defer disruptive 11.3 deprecations for removal until 13.0

The main difference between this and what we did for 10.x-11.x is that we'd start deferring disruptive deprecations one minor release earlier relative to the next major release window. Even though we'd start with 11.3.x and 10.3.x, we have an additional 11.x minor release before 12.0.0 comes out this time due to how the release windows worked out with 9.x/10.x/11.x- which makes this confusing to talk about.

If we start deferring deprecations with the 11.3.x cycle, it means that on the earliest day that 12.0.0 can be released (the June window), the following core branches would have security support:

12.0.x (june 2026)
11.4.x (june 2026)
11.3.x (december 2025)
10.6.x (december 2025, whether we actually branch or continue on 10.5.x is TBD)

The exact EOL date of 10.x is also TBD, but we have the option to commit forward-compatibility fixes to 10.6.x while 11.3.x is in development.

11.2.x security support comes to an end in that June window too, so if there are 11.2.x deprecations that a module needs to deal with, then it may need to drop 11.2.x support when adding 12.0.x support or have two code paths etc. If we miss the June window, then 11.2.x is fully out of the picture too.

This means that at least for straightforward modules, they may be able to support 10.6.x, 11.3.x and 12.0.x with a single branch or at least very minor divergence between minor branches.

We already have annotation and procedural hook deprecations for removal in 13.0.0, either in core or planned very soon, because we know that's going to require a lot of effort to update for, so this is consistent with delaying the removal of those by a major release.

It also means that there should be a finite amount of things to account for in phpstan/rector from June this year.

I think this is fine, we need to tell the community as soon as possible to give them time to do stuff they were planning quicker now as long as it is possible.

I also have no issue with this, marking NR to get any other feedback from the community.

Think it makes sense

If a deprecation is for base classes, interfaces, or otherwise likely to affect a lot of modules, deprecate for removal in 13.x

Sure there will be some learning curves so posting this somewhere may also help. Where I'm not sure as I still find the drupal docs hard to navigate/search.

Where would all the hook deprecations fall under?

Procedural hooks haven't been deprecated yet. Similarly we haven't deprecated annotation discovery in 📌 Triggering deprecations for plugins using annotations when core plugin type has been converted to attributes Needs work either, I don't think either of those will happen for 11.2, so the earliest they could land is 11.3.

However, although I can't immediately find it, we'd already discussed deferring both of those deprecations for removal in Drupal 13 anyway.

For annotations, there are all of the plugin annotations to convert, but also all the plugin managers need to support attributes before that can happen. So for contrib modules that implement plugins for other contrib modules, there will be chains of 2-3 issues to get it all done. Deferring removal of that to Drupal 13 gives a solid three years for all of that to filter through.

Procedural hooks as a whole I think we would definitely defer removal to Drupal 13 - it's going to affect almost every single contrib and custom module.

But specific hooks like hook_module_implements_alter() we'd probably still remove in Drupal 12 because they have tricky bc layers to deal with, especially if it makes other conversions and clean-up easier to do in Drupal 12.

Since there's been no further feedback at needs review, let's see if there's more feedback at RTBC.

📌 [Plan] Determine how to deprecate procedural hooks. Active is where we discussed procedural hook deprecation.

If I am being honest I'm not sure I see how we can directly deprecate procedural hooks, it will more likely be a side effect of deprecating .module files. There just isn't a clean way to know whether a function is a hook or not. We can throw a message runtime in LegacyHook, but that seems riskier than we would want to be.

Side note, hook_module_implements_alter and hook_hook_info are also strange deprecations because we are just removing them in 12.

So essentially you get 1 to 1,5 year to adjust to internal deprecations and 3 to 3,5 years for public API deprecations as of 10.3?

The latter seems a bit on the high end if you ask me, but I agree that an absolute minimum of 1 year is too short for contrib and client projects to adapt to disruptive changes. Ideally, we have a 2-year window as a hard cut-off, but trying to align that with major core release dates is tricky.

Essentially you'd have to deprecate things right out the gate when a new major release is cut, which seems impossible unless you postponed deprecations from the last major. And that would essentially be the same deprecating over 2-4 years, but with extra steps.

So with that in mind I suppose RTBC +1, even though I'm not fully a fan of keeping dead weight around for more than 3 years.

If I am being honest I'm not sure I see how we can directly deprecate procedural hooks, it will more likely be a side effect of deprecating .module files.

Yeah that might be the case. In terms of this issue, we could still deprecate them in any minor version of 11.x, it's just that removal of support would be deferred until 13.0.0

@kristiaanvandeneynde yes it would be 3-3.5 years, although hopefully 3.

Essentially you'd have to deprecate things right out the gate when a new major release is cut, which seems impossible unless you postponed deprecations from the last major. And that would essentially be the same deprecating over 2-4 years, but with extra steps.

Yeah this is what we did with some issues from 8-9 and... exactly.

It wouldn't be only @internal deprecations for removal in Drupal 12, we might decide to deprecate some other things for removal in 12.0.0 if they're low impact on contrib and will cause problems to keep around in core, but the default would be that yes.

+1 from me too

In some (hopefully rare) cases we will have no choice: from what I can see at the moment 📌 Passing a $options array to constraint constructors is deprecated, use named arguments instead Postponed is something we are going to have to fix/deprecate in 11.3 for removal in 12, because Symfony is forcing our hand; let's hope that they don't pull off something similar in Symfony 7.4 because then we will have to do the same in 11.4 for removal in 12.

I think #12 is fine, if we default to Drupal 13, then in cases where we need to deprecate for removal in Drupal 12 we still can. As long as it's not a change that will affect hundreds of modules then the overall effect is the same.

It might be better to talk about "the last minor release before 12.0" or "the minor release accompanying 12.0" because I'm confused myself as to what the actual intent of the IS is. Do we want to start already deferring deprecations right now, possibly a full 18 months before 12.0.0 might be released? That seems extreme to me. It could be three entire minors.

That said, I would definitely defer deprecations on a case-by-case basis (e.g., I would not deprecate procedural hooks for removal in 12.0.0 no matter what!).

@xjm the main reason is so that a module that's compatible with 11.2 and 10.5, with all deprecated usages fixed, has a decent chance of also being compatible with 12.0.0 assuming it comes out in June.

If there are new removals due to APIs added in 11.3, it makes it harder for modules to add 12.x support at the earliest possible point (during beta/rc or earlier), this is something @berdir has brought up during previous major release cycles iirc.

Even though those three releases won't be supported at the same time, 12.0.0-beta1/rc1 etc will come out before support is dropped for 11.2 if the first window is hit.

We'd still be able to deprecate things for 12.x if there's a good reason to, just the default would be for removal in 13.x

Contrib modules and best effort BC layers in @internal code etc. would all still be for 12.x too.

It would be good for that to move into the IS, which explains the "what" but not the "why". It sounds like we want to enable contrib developers to decouple when they do their upgrades from when core does theirs, is that the idea? In the same way that the branch support lets site owners.

Also if we're going to announce this to people (which @gábor hojtsy suggests and is a good idea) I would like to be able to make a compelling case for why, so that's a reason to actually do the work here I think.

I know it might feel like a rush now since 11.x is already including new deprecations not present in 11.2.x, but we can also internally ask the committer team to check with the team about disruptive deprecations they want to backport while this policy discussion is open.

There is also a much older policy discussion somewhere about the struggle for contrib to support the last two months for the security-supported branch at the same time as the betas for the major. Can we add that to the related issues? It might have good context.

Meant this, for IS updates and a "why" statement.

Added some notes to the issue summary.

Trying for plain english on the policy language:

The last version for a disruptive deprecation is the minor release one year before the first release window for a next major release. The first release window may be in June, August or December as outlined in the release process overview.

After that, a disruptive deprecation will be scheduled for removal in the major release two major releases ahead instead of one.

This allows more modules to support the next major release and the currently supported minor releases.

or

A disruptive deprecation is allowed up to, and including, the minor release one year before the first release window for a next major release. The first release window may be in June, August or December as outlined in the release process overview.

After that minor release, a disruptive deprecation will be scheduled for removal in the major release two major releases ahead instead of one.

This allows more modules to support the next major release and the currently supported minor releases

The only issue I have with both of those versions is it's not clear what the difference is before/after the cut-off, e.g. it doesn't explicitly say that deprecations are removed in the next major release at first.

Is this better? Adding the extra detail does make the sentence harder to read but it is still correct.

A disruptive deprecation scheduled for removal in the next major release is allowed up to, and including, the minor release one year before the first release window for a next major release. The first release window may be in June, August or December as outlined in the release process overview.

After that minor release, a disruptive deprecation will be scheduled for removal in the major release two major releases ahead instead of one.

This allows more modules to support the next major release and the currently supported minor releases

I presume this would go some where in the allowed changes → .

#25 looks good, it's not particularly easy to read but this is not exactly a straightforward thing to explain.

Thanks. Yes, it isn't easy to explain this one. I moved that proposal to the issue summary. I'd be OK with adding this text, assuming we all agree it is accurate, and tweaking it later.

Are #17 and #18 addressed?

Could we flip it and say something like disruptive deprecations within a year of the next major must skip that major for removal?

Maybe this?

"Disruptive deprecations added to minor branches within one year of the next major release should schedule the removal of that deprecation one additional major release ahead. This allows more modules to support the next major release and the currently supported minor releases."

That reads much clearer to me!

Nice! I added the proposal from #29 to the issue summary.

Great suggestion @nicxvan!

I'm completely comfortable with the updated IS and the new proposed policy text, so re-TBCing.