Document how contrib hook_update_N() should be numbered now that modules can be compatible with multiple major branches and versioned semantically

Updated issue summary with remaining tasks and new section with proposed doc update artifacts.

New patch with typo fix caught in #23 and interdiff attached.

Formatting fix (oops, markdown) for IS update I just made.

FWIW, I think it makes sense to have these recommendations go into the documentation for hook_update_N(). But it does sound like some consensus/decision needs to be made there.

+++ b/core/lib/Drupal/Core/Extension/module.api.php
@@ -527,19 +527,42 @@ function hook_install_tasks_alter(&$tasks, $install_state) {
+ *   example, if you add hook_update_81001(), you cannot later
+ *   add hook_update_9101(). Instead, you would need to use hook_update_90101().
  * - 2 digits for sequential counting, starting with 01. Note that the x000
  *   number can never be used: the lowest update number that will be recognized
  *   and run for major version x is x001.
  * Examples:

This is no longer true CORE_MINIMUM_SCHEMA_VERSION is frozen at 8001, at least until we resolve 📌 Decide what to do with Drupal::CORE_MINIMUM_SCHEMA_VERSION and surrounding logic Active .

I think it might simplify things here if we stopped talking about non-semantic contrib module versions. Everyone who needs to read this is starting a new module and there's no need for them to use non-semantic versions.

I'm not sure what to do about the CORE_MINIMUM_SCHEMA_VERSION reference.

1. is this a critical?
2. should this be postponed on 📌 Decide what to do with Drupal::CORE_MINIMUM_SCHEMA_VERSION and surrounding logic Active

Re: #48:

1. Since @xjm made it critical in #9, yes.
2. In practice, that's sort of happening by default, but I still think it'd be better to move this forward and document something "now", even if we haven't figured out #3106712, yet.

So should 46 go forward or should this be NW for a different version to cover what we can now.

Re: #46: Thanks! A few (more) points:

1. +++ b/core/lib/Drupal/Core/Extension/module.api.php
   @@ -517,8 +517,8 @@ function hook_install_tasks_alter(&$tasks, $install_state) {
   + * module. To upgrade from Drupal 6 or 7 to Drupal 8 or 9), use the
   

   This would now need to say "10", too, but that gets clumsy. How about?

   "To upgrade from Drupal 6 or 7 to any higher version, use the migrate API instead."

   ?

   But even that isn't totally relevant here. You *can* use hook_update_N() for major version upgrades, too. It's just the older versions of core were so non-BC that a direct in-place upgrade wasn't possible and you need a migration. But when documenting hook_update_N() for contrib/custom modules, they can/should use hook_update_N(), even for major version jumps...

2. +++ b/core/lib/Drupal/Core/Extension/module.api.php
   @@ -527,19 +527,42 @@ function hook_install_tasks_alter(&$tasks, $install_state) {
   + *   Note that this must be higher than hook_update_last_removed().
   

   This seems like an important point, somewhat buried here. Probably this should go higher up, before we dive into the details of the recommendations?

Re: #47:

1. This is no longer true: CORE_MINIMUM_SCHEMA_VERSION is frozen at 8001

   Yup, good point.

2. I think it might simplify things here if we stopped talking about non-semantic contrib module versions. Everyone who needs to read this is starting a new module and there's no need for them to use non-semantic versions.

   Not sure I agree, here. Lots of projects still have bespokever version strings. Lots of people might still need guidance on how to number their DB updates before, during, and after the transition to semver.

3. I'm not sure what to do about the CORE_MINIMUM_SCHEMA_VERSION reference.

   Maybe add a @todo? 😂

Here's a new patch that hopefully addresses the helpful feedback in #47 and #51.

1. Clarifies that modules can use hook_update_N() for either minor or major upgrades but that sites should use Migrate API.
2. Moves sentence about N being higher than hook_update_last_removed() and adds an @see reference.
3. Adds a @todo about CORE_MINIMUM_SCHEMA_VERSION with a URL of the related issue (I hope I put this in an appropriate place and that my comment is accurate -- please check!)

Change looks much better now. Will admit this has given me some headache in the past.

+++ b/core/lib/Drupal/Core/Extension/module.api.php
@@ -516,30 +516,61 @@ function hook_install_tasks_alter(&$tasks, $install_state) {
+ *   example, if you add hook_update_81001(), you cannot later
+ *   add hook_update_9101(). Instead, you would need to use hook_update_90101().
  * - 2 digits for sequential counting, starting with 01. Note that the x000
  *   number can never be used: the lowest update number that will be recognized
  *   and run for major version x is x001.
+ *
+ * @todo Remove reference to CORE_MINIMUM_SCHEMA_VERSION (e.g., x001) once
+ *   https://www.drupal.org/project/drupal/issues/3106712 is resolved.
+ *
  * Examples:

The @todo is fine but the numbering is still confusing here, we should explicitly say the minimum number if '8001'.

There is no 9001 or 100001 minimum in 9.x or 10.x - when the follow-up is resolved, it's more likely to be '1' or '1000', pretty sure we're never going to increase it above 8001.

Thanks @catch for clarifying. New patch and interdiff from my last patch both attached.

Looks good.

Committed/pushed to 10.1.x, cherry-picked to 10.0.x and 9.5.x, thanks!

This issue is closed, but from the current documentation it is still totally unclear about how to start numbering the hook_update_N() functions for modules, that use semantic versioning!

So, I created a separate issue ✨ Standartize numbering of hook_update_N following the module semantic versioning Active to improve this, please take a look.