This page is dedicated to reference best-practice by steps to conduct a successful major upgrade of Magento 2 software, especially on an old fashion website not maintained during a long time.
The upgrade must be plannified between developer and business team, in order to make it in the best conditions.
Magento created a very helpful tool who was been recently released: https://business.adobe.com/blog/the-latest/introducing-upgrade-compatibility-tool
This tool can be installed here: https://experienceleague.adobe.com/docs/commerce-operations/upgrade-guide/upgrade-compatibility-tool/install.html?lang=en#download-the-upgrade-compatibility-tool
The idea behind this is very simple. It checks all override made in your code and tell you which are incompatible with the targeted Magento release. This tool will be very useful for step VII. In any case, it's important to know that there is only 5 things in your custom code that could break a Magento 2 upgrade:
- Plugins
- Preferences
- VirtualClasses
- Database change (patch schema and upgrade)
- Template override
We need to define the technical stack that will be used for our upgrade
For example on magento 2.4.3, WE MUST:
- upgrade mysql to version 8
- upgrade php to >=7.
- install elasticsearch (or install https://github.com/zepgram/module-disable-search-engine)
...
WE SHOULD:
- upgrade composer to version 2
- upgrade redis to version 6
...
You can find full details on system requirements here: https://devdocs.magento.com/guides/v2.4/install-gde/system-requirements.html
In order to accompish this upgrade, we'll need:
- To adapt local dev e,vironment to handle the system requirements
- Create a shared environment who can handle the system requirements for QA You can start steps IV., V. and VI. while this step is processed, but I strongly recommend you to finish it quickly after step VI.
You'll probably create a dedicated branch in order to handle this.
During whole development phase in order to accomplish this upgrade, your dedicated branch will have to be frequently rebased from your main branch. You must keep in mind, that every change made on main branch may break your current work. That’s why the best context when you upgrade magento is to simply “freeze” developments during that period. The freeze can be minimized to steps VII., VIII., IX.
Most of the time this will not be possible, so you must alert your business team about this and tell them that any additional development during that period may slow the upgrade project.
If the code has not been maintained during a long time (no refactoring, dead code, dead package, dead extension etc...), you must contact business and technical team in order to analyse what can be cut in the fat before the migration.
Keep in mind that least code => faster upgrade
So you must try to delete dead code, dead modules, dead features. In fact, keeping only features who matters for business has multiple advantages:
- Less code to maintain
- Less QA test
- Improve performance (less plugins/observers etc...)
- Improve readability
- Improve your global understanding of the project
For this step, you must remove everything that can be removed from your previous analysis.
If the analysis show that you have a lot of code to remove you may have the choice here to minimize risk and ligthen this migration by merging you code to your main branch and validate everything works correctly before the migration.
Otherwise if you want to handle only 1 global QA, you can continue to steps VI., everything will be validated anyway.
This is pretty frequent, even now because sometimes composer is not known for his benefits. Anyway, in some project you will have external module installed in app/code. This is bad for 3 reasons:
- You cannot benefit tiers updates with composer update
- Your development team may believe they can commit code
- The end customer become the maintainer of this external code despiste he didn’t code it
So even if a module cannot be installed through composer (because there is no repository), you must make a package and install it with composer. This way, they are referenced, code cannot be directly committed, and atleast you will just have to upload a zip and run composer update command in order to upgrade it.
Firstly I recommend to mark all preferences, following this format:
@warning v2.y.z - full override
All preferences should be migrated into plugin or when it’s not possible make a composer patch it will be easier for next Magento upgrade.
Secondly we are going to handle the change that magento had introduce and may break our custom code (plugin/preference/virtualClass).
To do this, run the command line and replace current-version and coming-version accordingly:
uct upgrade:check magento --current-version=2.3.5-p2 --coming-version=2.4.3
You can also add --ignore-current-version-compatibility-issues option to keep only compatibility issues with your coming version.
Thirdly adapt all classes who can be adapted. Sometimes some class will not be retro-compatible: this is a breaking change, these classes must be marked with a comment and will be handled after the upgrade in order to adapt it correctly with additions made by Magento.
Step III. must have been done here before to process.
Now our new technical stack is ready, everything who could be anticipated has been done we may now be able to update Magento code and dependencies.
To make sure that Magento code base will be updated run this command:
rm -rf vendor/
rm -rf composer.lock
Then go to your composer.json and change the targeted version of magento/product-<type>-edition.
If you do not want to update a package to his latest version because it’s currently compatible with the targeted Magento version, you should also
handle your composer packages by forcing their current version.
E.G.: "xyz/module-payment": "^7.2" to "xyz/module-payment":"~7.2.3"
When you’ll run composer update, you'll be able to master the command by handling independently package versionning, this way you'll now which package must be updated or not according to magento dependency.
Once the composer install is done you may mark the package updated, and make sure you didn’t overriden them, otherwise you will adapt them on step IX.
Commit all your change here: your code base and resources are now ready and you can finally handle the last development step.
Here is the good part: we are now ready for our Magento 2 upgrade, so let's do it.
- You will handle your custom change made on database who may break the setup:upgrade
- Here you will handle the class who couldn’t be handled in step VII.
- You will also handle override of extension who have been updated during step VIII.
In order to accompish the step 1) run: bin/magento setup:upgrade, error may be prompted here, fix them.
Then run bin/magento setup:di:compile, if something was missed during step 2) and 3) error will be prompt, fix them.
Then run bin/magento bin/magento setup:static-content:deploy, to validate that theme files can be generated.
Once everything has been validated by QA and automated test on dedicated environment. Your dedicated branch can now be merged in your main branch.
- Before your upgrade, you must back-up your production database.
- Then you will force a maintenance mode of your application.
- You are now ready for upgrade, press the button.
- Validate with your QA team that everything is fine before to remove maintenance mode.
- If something is detected during maintenance mode, you must decide with your team if you quickly fix the error or if you rollback with your previous back-up.
- After your removed the maintenance mode, if everything is going bad here, you must keep in mind that the only way to rollback is by importing the back-up made before the upgrade (which may lead to data loss) and to redeploy the previous code (before the merge). Hopefuly this will not happen if you correctly followed all previous steps.
- If everything is fine, well it’s done, great job! In addition your next upgrade should be easier.