Standartize numbering of hook_update_N following the module semantic versioning

Which documentation page or file needs to change?

Which documentation page or file needs to change?

I think this page: https://www.drupal.org/docs/drupal-apis/update-api/introduction-to-the-u... →

And the inline documentation here: https://api.drupal.org/api/drupal/core%21lib%21Drupal%21Core%21Extension...

contrib doesn't have 0.x major versions, it starts with 1.x AFAIK, so numbers starting with 0 wouldn't exist. They also wouldn't work, the update number is a single integer, and right now the lowest number that you can pick is 8001 (for now, it references an issue to remove that requirement). There is AFAIK an issue to change that, but anything else is entirely up to you.

I do agree that the documentation can be improved, the part about core compatibility can be dropped, it's only about your own module.

I think the most sensible thing is then to just start with 10000 or 1 major 00 minor and 00 for the update number. I'd not put in patch for contrib modules because that will just require you to update it whenever there's a new patch version.

Also found an issue that we can't use numbers with leading zeros because it leads to not finding the hook_update function, so if we use hook_update_08001 - it will show the error:

  In update.inc line 357:
    Function commercetools_update_8001() does not exist

So, updated the description again.

Here is a suggestion for numbering pre-stable release numbers like 0.1.0:

Let's stick to 8001+ for that case, because .80 is used in some software version numbering as alpha, .90 as beta (eg in KDE releases like 5.80.0 - 6.0-alpha1, 5.90.0 - 6.0.0-beta1, 5.95.0 - 6.0.0-beta2, 6.0.0 - 6.0.0 release).

Updated the issue body with the new changes, please review.

that is even already closed, but in the results I see no improvements in recommendations on how to number the hook_update_N functions, related to the semantic version number of the module.

The linked API document and commit did add changes to describe versioning involving contrib modules that utilize semver.

The linked issue and pages say that the numbering is
CcMmII
Cc = 1-2 digits for minimum version of core supported (this also guarantees our update hooks never have a leading 0 for 0.y.z branches)
Mm - 1-2 digits for module major version
II = 2 digit incremental.

Start thinking about what number to choose for hook_update_N of the new release of a contrib module, that is compatible with Drupal 9.x, 10.x, 11.x together.

 If your module is compatible with multiple major versions (e.g., it has a core_version_requirement of '^8.8 || ^9'), use the lowest major core branch it is compatible with (8 in this example).

is it this is possibly a support request for misunderstanding of what the current 'suggested' format is?

Is core useful as part of the value? Maybe not, although it does add that nice protection for 0.x branches and allow modules to reset their counters every time the module drops support for a version of core.

Under the existing standard do we need to consider starting any counter at 110000 minimally for 0.x branches since these may be in the wild already?

I would actually suggest a minimum of 20000 if that is done in case 📌 Decide what to do with Drupal::CORE_MINIMUM_SCHEMA_VERSION and surrounding logic Active decides that we will bump the minimum version to 120000 in the 12.x release (unlikely, however we never know what will happen with this value in the future until it is actually removed) as that would at least hold us for up to 16 years.

Biggest question to ask: How many incremental do you need each minor/major for each minimum core supported by a module? Do you really need 99 update hooks per MINOR release or is 99 per major sufficient in which case the existing numbering scheme already covers this. I have heard of some long running modules in the past (before hook_post_update()) having issues, is that still a problem today?

Second question is if you have a long running issue, do you really want to edit the update hook number in a MR because the module released a new minor release while the issue was in-progress?

Tagging as Needs IS update, recommend removing the references to no standard and adjust to reflect why the existing recommended format should be changed.

contrib doesn't have 0.x major versions, it starts with 1.x AFAIK, so numbers starting with 0 wouldn't exist.

They do have :) Here is a pretty fresh example: https://www.drupal.org/project/experience_builder → - version 0.1.0-alpha1

Interesting, I didn't know that's possible. So yes, starting with 8001 is the best we can do for 0 major version I guess. It is very rarely used, so shouldn't be a huge deal. I would probably hide that a bit and not start with this scenario. it should remain an exception, and experience builder very much is, it's an experimental major new thing that's developed and expects to take months of work. Most projects by the time they are released on drupal.org are probably reasonable stable and usable and should IMHO in most cases start with 1.x and alpha/beta releases.

See also the related slack discussion recently: https://drupal.slack.com/archives/C1BMUQ9U6/p1732887634276909

Re #10, from that thread from me:

yes, I think the core compatibility thing should be completely dropped, that doesn't mean anything anymore

that dates back to when drupal core major versions increased the minimum version number, but that is still at 8000 and can not be increased, because all modules would then suddenly have invalid updates

and lowering is also tricky because drupal stores that number as the last update for newly installed modules. so the easiest option is IMHO to document to use 6 digits and just forget about that weird 8000 thing

Self correction on the last part: 5-6 digits and we can forget about the 8000 thing except for 0.x major branches.

D12 will not increase the number because it can not. And we can also not easily lower it without update functions that lower the initial value for currently installed modules and modules could then only rely on that once they require at least D12 or whatever version would make that change.

The technical constraints are pretty simple: first update must be at least 8001 and each following update must user a higher number (Insert "Numbers must go brrr" meme). That's it.

IMHO, this is a documentation task to define a common standard within the current technical constraints and the proposal makes sense to me. If [# #3106712] ever gets resolved and that min number requirement is removed we can just update it and you can then start with 1 or 1000 or whatever core will do.

Is it worth it to include the contrib minor version? It's additional detail than previously, where the Compatibility-Major.PatchLevel scheme melded together changes that would now be separated to semantic minor and patch releases. I expect in most cases update functions are going to be tied to minor-level changes, so there would be a lot of M0101, M0201, M0301....

The minimum schema version sets the lower bound of numbering at 8000 while it still exists, but the default recommendation could just be Mdddd (major without leading zero + 4 digit increment). Only a note would be required for pre-stable 0.x.x versions to start the update numbering at 8001.
Contrib modules could choose to include the minor version if they will be concurrently supporting minor releases for a longer duration, or just leave an arbitrary gap (e.g. +10) to account for the potential of patch-level updates.

> Is it worth it to include the contrib minor version?

IMHO, yes absolutely. Yes, in most cases, it won't be needed and old minors won't get updates. But if you ever have that situation, for example due to a security issue that's also fixed on an old minor and you have a continuous list of update function numbers, it's going to be really complicated to untangle. You'd need to reshuffle update functions since some people will have already run a certain update then on the old minor, others will update directly to the latest minor.

This might be related.

The proposal looks good to me, agreed with #14 on minor releases - there needs to be space to add an extra update just in case, otherwise you end up with potentially unresolvable situations you can't go back in time to fix.

I think it would be worth trying to convert this into update hook_update_N() documentation.

I would put the pre-release stuff at the end/as a footnote because writing updates for prereleases is not that common in contrib and it's the most confusing part of the proposal with the 8000 restriction.