Beginners Guide to Upgrading Sitecore For The First Time

Upgrading Sitecore can be a wildly different experience from project to project. Some sites will upgrade easily, some will have you swearing and shouting at your screen. I've been using Sitecore for around 5-6 years now and in that time I've seen a lot of wild and wacky issues occur while upgrading. Over the years though I've found that if you follow some basic core principles you can make life a lot easier.

Read The Documentation

When upgrading version x to x, read the documentation. It might be tedious but you will need to follow the recommended process in a certain order. You cannot easily jump from Sitecore version 6 to 8.1 for example, but you have to incrementally upgrade, one step at a time. As part of each step, you will also need to update any modules if and when they happen. When you visit the Sitecore SDN for the version you want to upgrade to, you should see a list of all the steps you need to go through in the prerequisites area. You will need to follow every step from your current version to the version you want to upgrade to on each environment. Document what modules you have installed and read the upgrade notes for each package before you begin. For example, WFFM adds extra steps and needs to be upgraded at certain points in the process. If you forget to do this, then you may have to start the whole process from scratch again. Sitecore Modules Compatibility Table is a great place to see which modules will need to be upgraded and when.

Seperate Custom Config Files Changes As Much As Possible

In most website builds, you will need to add some degree of web.config customisation. You may need an app setting or something similar. When you upgrade, the web.config file is usually the file with the most amount of changes. Instead of messing around with nasty merging, if you separate your customizations into a separate configuration file and reference it in your web.config, when upgrading you only have to worry about merging the include lines, making your life a lot easier. To do this, take any changes you've made in your web.config and push them into a custom config files in your 'App_Config' -> 'Include' folder. After you've done that you can mostly just use the default Web.config that comes with the version you are upgrading to.


When upgrading it's really easy for the business to want to add feature x or y at the same. Push back and say no to these requests. When you do an upgrade, stick to a like-for-like upgrade. This prevents the possibility of extra bugs being introduced and new issues that can cause you heartbreak.

Do Not Try To Rush

Upgrading Sitecore can be a time-consuming process. On a recent project, it took over 16 hours to refresh the search indexes, link database and do a smart publish. As the process can be tedious, it can be very tempting to try and skip some steps to try and make the process quicker. From my experience, anytime I've tried to rush an upgrade, it's always taken more time in the long run. When you rush and skip steps, things will inevitably go wrong. Each step in the process is usually there for a reason (even if you don't know the reason yourself) so trust it.

Back Up At Each Major Step

During an upgrade, you usually have to go through a very structured set of steps. You run an upgrade, you publish your code to the website, you install modules, you upgrade NuGet packages etc.. at each and every step BACK-UP your webroot. If things go awry instead of having to start from scratch each time, it's a lot easier if you start from the last step in the process. You can only do this if you are very thorough with your backup plan. Also, remember when you upgrade you will have to upgrade your dev, test, authoring, live servers, so don't delete any of these back-ups until you have finished. I've made the mistake a few times of upgrading my local dev versions, deleting all the backup folders only to realise I needed them when it came to upgrading the next environment.

Beyond Compare

One life-saving tool to have in the toolbox when upgrading Sitecore is the ability to be able to compare your webroots file and folder structures to different states. For example, comparing your current webroot to a fresh version x install will show you what config changes have been made, what files are missing etc.. Out of all the comparison tools I've used Beyond Compare and I find it by far the most useful and UI friendly diff tool. sitecore_beyond_compare Beyond compare isn't free, so you may have to settle for Win Merge

Jon D Jones

Software Architect, Programmer and Technologist Jon Jones is founder and CEO of London-based tech firm Digital Prompt. He has been working in the field for nearly a decade, specializing in new technologies and technical solution research in the web business. A passionate blogger by heart , speaker & consultant from England.. always on the hunt for the next challenge

Back to top