The Magento Upgrade Guide

In using Magento, as with any software, it is important to keep up to date with the latest stable releases, as it allows the user to leverage all newest eCommerce functionality, while eliminating issues and vulnerabilities from past versions. However, upgrading your Magento install can be a complicated process, especially with sites that use many community extensions and other customizations. In this Magento Upgrade Guide, I will provide a thorough checklist for an eCommerce merchant to follow before and after upgrading their install. I will also present a guide for developers with the steps involved for performing a successful upgrade.

Note: This guide will only cover upgrading from Magento 1.x to a later release of Magento 1.x. This guide will not cover upgrading to Magento 2.

Before you Begin

magento

The first thing to note is that it is entirely possible that the upgrade does not go as planned. There are a number of things that can go wrong with the actual upgrade itself, in addition to site performance following the upgrade. For this reason, you should be as prepared and informed as possible going into the upgrade, and willing to test extensively before pushing the upgraded site live. The upgrade should always be executed on a test environment with a test database before it is attempted on the production site. Furthermore, prepare for an hour or two of downtime when you perform that upgrade on on your live store. I suggest promoting the upgrade early in the morning so as to correspond with low traffic and minimize any loss in sales. If tested properly, there should only be about 15-20 minutes of downtime.

Related: 10 Simple Steps to a Magento Enterprise Edition Install

Taking Stock

magento upgrade

Now that you have mentally prepared for the upgrade, it’s time to take inventory of your site. Make sure you know the answer to the following questions.

  • Which version of Magento is currently running?
    • The version number is shown in the footer on the backend admin panel.
  • How many extensions are installed on the site?
    • Have a developer take stock of what’s been installed into the app/etc/modules/ directory
  • Which of these extensions are being used in an integral manner (crucial to the day-to-day operations of the web store) ?
    • Any extensions that affect product display, promotions, checkout, shipping, payment should be noted here.
  • Have any of the extensions been customized by your developer?
    • If so, try to determine if they modified the extension directly or (better practice) added customizations in a separate module.
  • Which patches, if any, have been applied to the Magento core?
    • Have a developer compare the app/code/core directory with the base install of your version.

Once you have the full list of answers to the above questions, you can begin to get a good idea of how challenging the upgrade might be.

If your version of Magento is very old compared to the current one, you may run into some issues with some features. If there are a lot of extensions installed on the site, and they were not tested with the new version to which your site is upgrading, you could run into trouble. This is especially true for extensions that alter the functionality of key Magento processes, like checkout and promotions. For this reason, it is important to know which extensions can be disabled if they are the ones causing issues. Any patches or modifications to the Magento core will be lost with the upgrade and any database modifications could also potentially cause conflicts.

magento connect

If you are running a recent version of Magento, without a lot of customization and with minimal extensions, the upgrade will be a whole lot cleaner than if you are sailing a customized ship. The last step for now is to do a complete run through of the currently installed site, take stock of any bugs or issues you can find. Add products to cart, make test purchases, test out the salesrules, category pages (and layered navigation), go through the backend and make sure you can load all the configuration pages, and test any other custom functionality.

You should also contact each developer you purchased extensions from and ask them to provide the most recent version, provided it is compatible with the new version of Magento. Also, you should check all the freely available extensions that were installed for updates on Magento Connect, and grab the latest version if you can.

Now that you have done a thorough inspection of the site, and have a good idea of the challenges you will face, it’s time to contact your developer.

Related: Magento Layout XML Action Method Reference List

Conducting the Upgrade

magento upgrade guide
Note: This section assumes you have familiarity with software development and working with Magento in particular.

Before you Begin

  1. The upgrade should always be run on a local environment
  2. Ensure you are using Version Control in case anything goes wrong
  3. Use a local copy of the database. If you have a test or staging database, you should still make a copy so that if any issues come up, you still have a working database with the older version.
  4. Before committing anything, run extensive testing on the frontend and backend of the site.
  5. Grab a copy of the current Magento version (the one you are upgrading from)
  6. Get a copy of the newer Magento version (the one you are upgrading to)

Getting Started

  1. Use a good ‘diffing’ tool (I commonly use PHPStorm, though Kaleidoscope is a popular tool for OSX) to ensure the core of your Magento site (the contents of app/code/core) is unmodified. Any modifications of the core will be lost.
  2. Ensure any theming done in the design or skin folder has been done in the custom theme, with the exception of design packages coming from extensions (which may be found in base/default). Any direct modifications to Magento core files will be lost.
  3. Use your diffing tool to merge the contents from the newer version of Magento into your install, replacing all files in all directories (not just app) with incoming changes. Keep all the files you have modified, such as local modules and custom design packages.
  4. Make sure to keep in mind any deletions of core files in upgraded versions of Magento. If these deleted files are left on the site, it can cause a lot of issues. (Mage_GoogleCheckout is an example of a module that was stripped down heavily in later releases of Magento 1.x)
  5. Clear the cache entirely.
  6. Hit the homepage of the site. This will trigger the installation of any new tables or data that come with the upgrade. If any errors occur with the installation itself, try to resolve them by debugging.
  7. Once the installation has completed and you can hit the homepage successfully, trigger a full reindex from the site from shell. See this guide for a quick rundown on reindexing from shell if you are unfamiliar with the process.
  8. If the reindex completes successfully then it’s now time for testing.

Testing

Now that the upgrade has taken place, you must test to ensure the core functionality of the Magento site is still working as expected.

  1. Start with critical path testing. Hit the homepage, navigate to a category page, and subsequently to a product page. Add that product to your cart. You should repeat this process by navigating to a product page via catalog search, and also through any other channels, such as a quickview.
  2. Ensure you add all product types to cart. If the store sells configurable products, simple products, groups, bundles, downloadables etc. they must be tested to ensure the add to cart functionality is working.
  3. Once you’ve filled the cart, conduct a full test checkout to ensure nothing is broken in the most vital area of your site. Place a test order and fulfill it in the backend to ensure all is good. (Ensure you are using test credentials for the payment method and shipping methods being tested)
  4. Test additional functionality such as price rules and product relations. Ensure these modules are functional.
  5. Now it’s time to test the extensions that are vital to the site. If these extensions are not working, you will either need to disable them or upgrade them from the developer with a version that is compatible with your upgraded version of Magento.

Going Live

At this point you have conducted rigorous testing of your upgrade and are confident the site is working properly. The next step is to promote the upgrade to production. Since you will be uploading a whole bunch of files, and since the upgrade itself is a rigorous process for the database, you should put the site in maintenance mode by creating a maintenance.flag file in the root of the site.

  1. Ensure you have a recent backup of the live database before doing anything.
  2. It is extremely important to upload the files using a versioned deployment system, but if you do not have access to such a system, make sure you take a backup of the filesystem, in case of a rollback.
  3. Now you are ready to upload the files. Trigger the deployment and flush the cache.
  4. Hit the homepage of the site so the upgrade will take place. Since the site is in maintenance mode, you should make sure to whitelist your IP in index.php so you can actually hit the site.
  5. Now that the upgrade has concluded without errors, trigger a full reindex from shell again.
  6. Before lifting maintenance mode, conduct critical path testing like you did above, and then ensure that somebody places a test order.
  7. Once all is confirmed and working, you can now lift maintenance mode by removing the maintenance.flag file.

Moving Forward

magento upgrade guide
Congratulations, as you by now have come out the other side victorious! Your site is running on a fresh and clean version of Magento, and your customers are happily browsing the site once again. You should keep an eye on performance over the next few weeks to determine if the upgrade has caused any issues with high traffic.

I hope this guide was informative and helpful for you as you look to improve your Magento store!

Related: 8 Easy Ways to Improve Magento Site Speed