In this article we will be going to share how we have handled Magento 2 upgrades, noting any common gotchas, and issues we have run into. Ensuring a smooth as possible upgrade is incredibly important to us.
Note: that this assumes you are using composer for your project, and that your installation is created using composer create-project --repository-url=https://repo.magento.com/ magento/project-community-edition [your/dir] [version].
This guide also assumes you are running this on a local installation before running on a staging or production environment (we have a few tips for this at the end of the article too!).
Step One. Read the release notes.
Every release will contain detailed release notes, it's important to get familiar with the areas that are changing in each release. You can find these over on the devdocs: Magento 2 release information
Make notes on the areas changing, perhaps they fix issues where you have put in place your own workarounds. If you have put in place workarounds, it'll be worth making sure the latest release does fix this.
What we've done on projects is make use of a README in the root of our projects to keep notes on our specific overrides to get around bugs. Usually we package each fix up into its own module then we can simply remove the module when that issue has been fixed in a release.
Step Two. Dry run composer update
This is incredibly important. Always run a dry-run and look what the packages that are changing. If you're upgrading from 2.0.x to 2.1.x you will likely come across breaking changes. It should be less common within minor releases, but always check what the underlying modules are changing to.
For example, an upgrade from 2.0.13 to 2.1.1 you will see the Magento_Cms module goes from version: 100.0.6 => 101.0.1. Notice that the major version has changed here. That suggests that the module update will contain breaking changes.
You can perform a dry run with the following:
composer update --dry-run
With this information, make a note and if anything jumps out such as a major version jump such as mentioned above you should make sure these areas are working as expected.
Step Three. Run the composer update.
Once you're happy you understand what is being updated, it's time to run the update.
composer update
Part of the composer update will replace files in your base installation. For example, .htaccess in the root directory will be updated. So be sure that your repo is under version control so that you can see what is changing, and if you have made any customisations, you can bring them across afterwards.
This is a good point to commit the upgrade. You'll be committing the composer.json and composer.lock plus any modified files to the base installation.
Step Four. Review possible breaking changes.
This is the most important step for a successful upgrade. You will want to use the notes you collected from steps 1 & 2, and begin going over the modules and comparing against your customisations.
Most common area to look at will be your theme. Start here then move onto 3rd party extensions, and your own module code afterwards.
I personally have used git diff to check for differences between two files. You can use it to compare two files, not just the changes in your git history, and it comes with sensible defaults, so it's easy to read!
git diff vendor/magento/module-checkout/view/frontend/templates/cart/minicart.phtml app/design/frontend/MyTheme/MyPackage/Magento_Checkout/templates/cart/minicart.phtml
I'll do this for every template file, assess the changes and see if they need to be brought over to the theme. Keep a look out for changes to x-magento-init scripts, javascript, the data-mage-init attributes, and any Knockoutjs template changes as these are the most likely signs that there might be a breaking change for functionality.
Where possible, I try to avoid copying template files into themes, but it is inevitable. Just make sure the changes you are making have to involve overwriting the template and can't be included in some other way (layout configuration is your greatest tool here). It'll ease your upgrade path, and you'll thank yourself later.
Step Five. Upgrade the database, nuke compiled/generated files
You will need to remove all generated code, any compiled assets, and cache. Delete the following:
var/divar/generationvar/cache(If you're using redis, or another cache storage system, flush these too!)var/page_cachevar/view_preprocessedpub/static/*(note the asterisks will delete all files, excluding any hidden dot files, which is desired. Don't delete the directory)
Then make sure you flush Varnish at this point too if you're using it.
Next up, it's time to upgrade the database!
bin/magento setup:upgrade
Fingers crossed this all goes well!
Note: I'm assuming you're doing this locally, and that your Magento 2 installation is using developer mode (use: bin/magento deploy:mode:set developer to get this.)
Step Six. Test everything.
Yes, everything.
Take into account all the critical features, and start with those. These include:
- Browsing the catalog, using layered navigation, searching.
- Ability to add products to your cart. From listing pages, and from product view page.
- Ability to checkout successfully (guest account, registering during checkout, logging in with a user)
- Test all the payment methods
- Test all the shipping rates appear as expected
- Ability to login/register for an account.
Depending on the functionality of your store this list will continue to grow (for example wishlist, and product comparison may be important features on your store). Be sure to test everything you know your customers are using and expect (even the features they don't use).
Next up, test all your third party extensions that provide additional functionality, both in the admin backend, and the frontend. Again, be sure that critical features are working.
Step Seven. Production & Staging Environments.
Once you are in a position to deploy to a staging or production environment you should consider what commands your deployment process should execute post-deployment. Such as upgrading the database, recompiling DI, and deploying static content.
Take a look at the following for an example
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy --theme=mypackage/mytheme en_GB
bin/magento setup:static-content:deploy --area=adminhtml en_US en_GB
bin/magento cache:flush
This will ensure that your environment is now upgraded, and configured. Then you can repeat step six for testing on your staging and production environment.
What else can you do?
There is more that can be done to improve your upgrade process. For starters, how about unit tests, integration tests, and functional tests? These can quickly flag broken functionality between upgrades with you simply running a few commands. However, to be in a position to rely on these tests though, you need to have a comprehensive suite of tests, and a level of coverage that you are happy with. This is certaintly something to aim for no doubt.
Closing thoughts
Upgrades are complicated tasks, they are time consuming and should not be underestimated. Always lean on the cautious side. This is not a fault of the platform, naturally you're making lots of customisations to a store, meanwhile the Magento 2 team are hard at work fixing and improving the platform.
Always be sure to use staging environments that replicate your production environment, as nobody wants the nasty surprise that there is some process, step, or configuration setting that is different which sets everything on fire once you hit production.