Reorganize "Update and migration"

[adriendupuis]

Question	Answer
JIRA Ticket	IBX-9082
Versions	All
Edition	All

• Isolate 4.6.latest patch upgrade on new page "Update from v4.6 > Update to v4.6"
  • Before: https://doc.ibexa.co/en/latest/update_and_migration/from_4.5/update_from_4.5/#v462
  • After:
    • https://ez-systems-developer-documentation--2519.com.readthedocs.build/en/2519/update_and_migration/from_4.5/update_from_4.5/#update-to-v46latest
    • https://ez-systems-developer-documentation--2519.com.readthedocs.build/en/2519/update_and_migration/from_4.6/update_from_4.6/ (taking the opportunity to recall the Composer commands, there is a tendency to forgot recipes)
• Deduplicate 4.5.latest
  • Before:
    • https://doc.ibexa.co/en/latest/update_and_migration/from_4.4/update_from_4.4/#v452
    • https://doc.ibexa.co/en/latest/update_and_migration/from_4.5/update_from_4.5/#v452
  • After:
    • https://ez-systems-developer-documentation--2519.com.readthedocs.build/en/2519/update_and_migration/from_4.4/update_from_4.4/#update-to-v45latest
    • https://ez-systems-developer-documentation--2519.com.readthedocs.build/en/2519/update_and_migration/from_4.5/update_from_4.5/#v452 (unchanged)
• Deduplicate 3.3.latest upgrade
  • Before:
    • https://doc.ibexa.co/en/latest/update_and_migration/from_2.5/to_3.3.latest/ is unmaintained and outdated
    • https://doc.ibexa.co/en/latest/update_and_migration/from_3.3/update_from_3.3/ is maintained and up-to-date
  • After:
    • https://ez-systems-developer-documentation--2519.com.readthedocs.build/en/2519/update_and_migration/from_2.5/to_3.3.latest/ redirects
    • https://ez-systems-developer-documentation--2519.com.readthedocs.build/en/2519/update_and_migration/from_3.3/update_from_3.3/ is the chosen one
• Update 2.5 to 3.3 plan's links
  • Before: https://doc.ibexa.co/en/latest/update_and_migration/from_2.5/update_from_2.5/
  • After: https://ez-systems-developer-documentation--2519.com.readthedocs.build/en/2519/update_and_migration/from_2.5/update_from_2.5/
• Update transition to 3.3.latest upgrade
  • Before: https://doc.ibexa.co/en/latest/update_and_migration/from_2.5/to_3.3/#next-steps
  • After: https://ez-systems-developer-documentation--2519.com.readthedocs.build/en/2519/update_and_migration/from_2.5/to_3.3/#6-update-the-database

Side-note(s) about unsolved issues in this batch

• File names (and, so, URLs) could better express the contents.
• IBX-9082 created to not forget to continue.

Checklist

• Text renders correctly
• Text has been checked with vale
• Description metadata is up to date
• Redirects cover removed/moved pages
• Code samples are working
• PHP code samples have been fixed with PHP CS fixer
• Added link to this PR in relevant JIRA ticket or code PR

[vidarl]

1. There is one flaw in the upgrade doc that should also be addressed.
   In the composer update command, we always refer to the latest maintenance release. ie like here we ATM refer to 4.6.12

2. Then we later run migrations

3. And after that we run schema updates like for 4.6.4

Step 2 might fail since code may require the schema changes that are applied later

So, once you upgrade to latest maintenance release, the next step should always be to get schema up2date.. Then run remaining upgrade scripts in correct order

[adriendupuis]

1. There is one flaw in the upgrade doc that should also be addressed.
   In the composer update command, we always refer to the latest maintenance release. ie like here we ATM refer to 4.6.12
   …

Step 2 might fail since code may require the schema changes that are applied later

So, once you upgrade to latest maintenance release, the next step should always be to get schema up2date.. Then run remaining upgrade scripts in correct order

(Note: this issue was already there and not inserted by this reorganization.)

I see no quick easy fix for that. Because of migration changes in 4.6.2 in https://github.com/ibexa/dashboard/commit/f2f220b101a97ce2232325a7c42acf26be7f9efc and https://github.com/ibexa/installer/blob/4.6/upgrade/db/mysql/ibexa-4.6.1-to-4.6.2.sql we can't propose to move to 4.6.0, execute migrations, and then upgrade to 4.6.latest, and run the database update.

@vidarl I'm adding this issue to IBX-9082 for later.

[mnocon]

It's much clearer, thank you! I agree that we can further improve this in a follow-up.

Good job spotting and deleting the outdated instructions for 3.3

[vidarl]

we can't propose to move to 4.6.0, execute migrations, and then upgrade to 4.6.latest, and run the database update.

I didn't propose that either. Upgrading code to latest 4.6.x is better ( and less work than go through 4.6.0 first).
I am just saying than upgrading schema should be the next step, not running migrations or other php scripts that might fail due to not-up2date-schema ...

@vidarl I'm adding this issue to IBX-9082 for later.

Ok, I am fine about addressing this later. But it should be addressed at some point