So you're thinking about an upgrade?

I've been involved in a few discussions about the scope of projects to upgrade existing Sitecore instances in the last few weeks, and quite a lot of that discussion has focused around the "development environment" aspects of the upgrade work. So I thought I would write down some of the things that have come up in my conversations.

This isn't supposed to be a "how-to" guide, or a complete list of everything you need to worry about. But hopefully this post will provoke thought and discussions on some important topics around what might need to change – especially if you've not done an upgrade before...

For lots of people, the first major step in an upgrade project is to get your existing work compiling and running on the new version of Sitecore you're targeting. It sounds easy at the start, but on top of reading Sitecore's upgrade instructions, there can be quite a few things to think about:

• Which version do you want to upgrade to, anyway?
  It's always tempting to go for the very latest new release, but it's not necessarily the right one to pick in all cases. For starters, recently released versions may not be supported by all the add-ons you need. It's important to check that you can get a compatible version of any marketplace packages, or Sitecore add-ons for the version you choose. If you find you cannot, then you need to decide if waiting for compatible packages to appear is better than choosing a slightly older version of Sitecore. (Or for Open Source stuff, there's always the option of creating or compiling the changes yourself) You should also consider if the "latest and greatest" version is a major revision. If so, you'll be getting both bug fixes and significant new features – but there's a higher chance of encountering challenging issues with big changes like this. If your site won't directly benefit from the new features, is this worth the added risk to your project?
• Upgrading your references
  If you haven't already done so, now would be a great time to start consuming the Sitecore DLLs your code depends on via NuGet. But if you've already done that, you need to pay attention when you're upgrading. Obviously you need to pick the right NuGet package versions to match your target version of Sitecore, but if that's not the newest one in the feed it's all too easy to pick a wrong one. Visual Studio doesn't "remember" your version choices between packages you update, so be careful to pick the right one each time.
• You may need to upgrade other bits of software in your deployment too
  Sometimes changes in the version of Sitecore can change the supported versions of Windows and SQL Server, and even less dramatic changes in version might affect support for web browsers. You should check the compatibility table to see if any of these issues might affect your upgrade work. Some 3rd party packages rely on external software too – if you're using Coveo for search, for example, the package you install into Sitecore is closely tied to both the Sitecore version and the Coveo Server version – hence you have to consider upgrading all of those at the same time.
• You may need to make changes to your existing config patches and XDTs
  Depending on what versions you're moving between, you may find that some configuration that you have previously patched has changed. For example, in older versions of Sitecore, the logging configuration for Log4Net lived outside of the `` config element and hence you had to update it with XDT if you wanted to automate it. Now, however, newer releases have moved this inside the `` element so you can now use a normal config patch instead. You'll need to look for issues like this and make sure you adjust your project's config to match the version of Sitecore you're upgrading to.
• If you have 3rd party patches installed from NuGet, you may have to manually remove and re-add them
  Another side-effect of the changes that can happen to configuration is that you can have outdated patches in your source tree that came from NuGet packages. These can be outdated either because Sitecore's config structure changed, or because the 3rd party package changed. For these packages it can sometimes be easiest to completely remove the package and its files, before re-adding it. That ensures you get the right config in your upgraded project. A risk to consider here is that if a patch file is in source control, someone may have edited it rather than applying another patch – so it can be a good idea to check the source control history of these files to make sure you can preserve any changes that have been made.
• Are you using developer tools you could upgrade?
  A common discussion I come across in client project work is that people aren't keen on changing the versions of their tools because changing something that works can be risky. An upgrade project is a great time to re-consider this, and get those new features and bug fixes for your tool chain installed. Maybe you can even move to a newer version of Visual Studio?
• Any support patches you can remove?
  If you've previously added fixes from Sitecore Support to your deployment, then you'll need to check whether the bugs they addressed have been fixed in the release you're upgrading to. If they have, you can get rid of the support-patched DLLs and config files. But if they haven't then you need to talk to Sitecore Support again and get the correct version of the fix for the target version of your upgrade. Support patches for one version run a very high risk of not working with another version – so make sure you upgrade or remove them.
• Your serialised content probably needs updating too
  If content the schema has changed between the versions you're moving from and to, then all that stuff you've serialised may need updating after you've finished upgrading your development content database(s). For example, the appearance of the `__Final Renderings` field with Sitecore 8 requires you to think about whether any bits of your layout need to move into that field. And you'll need to re-serialise those changes as part of your upgrade.
• Does your development automation need updating?
  If you use stuff like scripted installs, or you have bits of your build process that you've automated with PowerShell or Gulp, then you'll need to think about whether changes to Sitecore (or your development tool chain) mean your scripts or code need to change.
• And finally, chances are your code needs to change too...
  Between versions, Sitecore (and 3rd party modules) sometimes marks APIs as obsolete, or removes APIs altogether. So you may find compiler warnings or errors cropping up when you try to build your code against upgraded dependencies. I'd always argue in favour of getting rid of all warnings that your code generates (as well as errors – obviously) so I think it's worth taking the time to fix warnings from obsolete APIs as soon as you find them.

After you get everything compiling and running in development, you then need to think about how other platforms may have to change to deploy this work. But having realised how much I've written already, that's a topic for another day...