(opening this one as a reply to this comment from #995446: Update the 7.x porting guided by upgrade.boombatower.com that is now closed-fixed)

Update numbers should be numbered according to module's target core (7xxx for D7) + major version number:

- 70xx for generic D7 API support updates
- 71xx for the 7.x-1.x branch
- 72xxx for the 7.x-2.x branch
...and so forth

Now, I know that in hook_update_N documentation it states to not renumber updates - as Frederik has already pointed out. Here are my arguments on this:

1. This *will* confuse people that expect updates to be numbered as described above.
2. We are sure to have future reports of issues by people affected by the fact in argument 1 above, so I thought I'd start it here before one of them did ;)
3. According to the module's stats there's only ~30 people using a 7.x dev of the module. Based on that + the fact that D7 is not yet out I am pretty sure that these people are not using it on production sites, but rather testing things out like myself. People testing dev releases are (or at least should be) aware that they might break things.
4. If we let this linger on, then it will be too late to correct it once people start using it in production sites (so I'm setting this issue to at least 'major').
5. One can always do a full uninstall of the module (disable - uninstall from the corresponding tab - remove folder) and they will have no database issues - I guess. If they do have issues despite doing a full uninstall, then arguments 3 & 4 take effect to serve as an excuse/reason.

Thanx in advance for considering this one.

Comments

Freso’s picture

Freso CreditAttribution: Freso commented
Status: Active » Closed (works as designed)

But the updates are already numbered as described. The first update, languageicons_update_6000(), was made for people migrating from the old "languageicons" module of the i18n package, and thus targeted the Language Icons releases for Drupal 6, which were the first releases that was broken out of the I18n suite. The second update, languageicons_update_6200(), removes a site variable that was introduced during development of 6.x-2.x, but removed again before 6.x-2.0-alpha1, thus this targets the 6.x-2.x branch of Language icons and will only affect those who used development versions of the module.

Renaming these functions would only cause Drupal to run them again, which would make no sense, as they either should have already been run, or should not need to be run (e.g. a fresh install). There's a reason the documentation says not to rename update functions.

klonos’s picture

klonos
he/him
Primary language English
Location 90% Melbourne, Australia - 10% Larissa, Greece
CreditAttribution: klonos commented
Status: Closed (works as designed) » Active

I am sorry Frederik, but I have to insist, because I believe you must have misinterpreted the documentation. The examples section in the documentation are for 5.x & 6.x modules and they simply have not been updated to include examples for 7.x modules. Where it says:

mymodule_update_6000(): This is the required update for mymodule to run with Drupal core API 6.x.

...the equivalent example for a 7.x module would be:

mymodule_update_7000(): This is the required update for mymodule to run with Drupal core API 7.x.

Also, it clearly states (and this is not an example but rather coding standards guidelines):

Database updates consist of 3 parts:

- 1 digit for Drupal core compatibility*
- 1 digit for your module's major release version (e.g. is this the 5.x-1.x (1) or 5.x-2.x (2) series of your module?)
- 2 digits for sequential counting starting with 00

The 2nd digit should be 0 for initial porting of your module to a new Drupal core API.

*(this should be 7 for 7.x modules)

klonos’s picture

klonos
he/him
Primary language English
Location 90% Melbourne, Australia - 10% Larissa, Greece
CreditAttribution: klonos commented

So, to explain this better, consider the case of one that would upgrade their site from drupal 6 to drupal 7 and thus the language icons module from a 6.x version to a 7.x:

- any 'initial' updates required to simply upgrade from 6.x to 7.x would be placed in the 70xx range of updates, starting of course with update 7000.

- once the site is updated to 7.x, then any subsequent updates from any 7.x version to a newer 7.x would be numbered in the 71xx range (xx would be simply used to increment updates' numbers).

- if a new 7.x-2.x branch is created and it requires any upgrade path updates, then these updates would be in the 72xx range.

No mater what though, according to the coding guidelines, updates in a 7.x version of a module (D7 core) are required/expected to be in the 7xxx from.

klonos’s picture

klonos
he/him
Primary language English
Location 90% Melbourne, Australia - 10% Larissa, Greece
CreditAttribution: klonos commented

The documentation tries its best to explain what I say in #3 with this:

mymodule_update_6200(): This is the first update to get the database ready to run mymodule 6.x-2.*. Users can directly update from 5.x-2.* to 6.x-2.* and they get all 60XX and 62XX updates, but not 61XX updates, because those reside in the 6.x-1.x branch only.

+ it also explains pretty simply the logic/mechanism behind the updates offered to the user based on the previous major (think core) & minor (think branches) versions of their module.

klonos’s picture

klonos
he/him
Primary language English
Location 90% Melbourne, Australia - 10% Larissa, Greece
CreditAttribution: klonos commented
Issue tags: +Coding standards, +db update numbers

There are quite a few modules making the same mistake (some even number their updates 1, 2, 3 and so on). I think that the hook_update_N documentation needs updating + more examples in order to clarify things.

+adding tags to be able to identify these issues easily.

klonos’s picture

klonos
he/him
Primary language English
Location 90% Melbourne, Australia - 10% Larissa, Greece
CreditAttribution: klonos commented
Title: Update numbers should be numbered 71xx (according to module's target core and major version number) » Update numbers for the 7.x branch should be numbered 71xx (according to module's target core and major version number)

...clarifying things in the title a bit ;)