The upgrade of a Sitecore solutions should be easy. The architecture of a Sitecore XP/XM solution, provided by Sitecore Helix principles and other well-known best practices should structure the solution such that the core product can be upgraded in a matter of days instead of months.   

Why are Sitecore upgrades then such a challenge that companies try to postpone them for as long as possible and end up with many breaking changes. What makes things more complex than they should be?  

In this blog post we will try to answer that question and share with you the experience we gathered during an 8-month upgrade process we went through with one of our customers.  We upgraded a Sitecore instance with over 150 sites on it and moved all the solution onto a new more performant environment.    

Well-known upgrade issues   

When someone starts a Sitecore upgrade, they usually start with an investigation of the sites, extensions, integrations, and differences between the versions. They can then plan the upgrade and migration.   

We followed this path ourselves, but using our experience of past upgrades we knew that we had to investigate other areas, it is not surprising to find the following issues:  

• Sitecore Helix violations  
• Not unified version of libraries and thousands of references  
• Unused legacy code  
• Serialized content  

Unfortunately, these issues are common on many Sitecore projects and if this was the extent of the challenge, we could proceed like any other short upgrade project, but we had more to address.  

 Less common issues  

 They used a manual release process, as a result we identified these issues:  

• Configuration files stored on the servers but not being added to the repository.  
• Assets like JavaScript or CSS files were missing in different environments. 

To resolve this, we had to add files to the repository and very often also overwrite old files being stored there.   

As we went deeper, we noticed that environment specific configurations weren’t being used in the solution. We found that sometimes configuration from the repository was correct and sometimes it wasn’t – and remember that we had over 150 sites to upgrade and migrate. There is no easy way to fix something like that – we had to go site by site, config by config and tidy everything up.   

When performing a review of the solution before the upgrade it is worth checking if configuration files use role-based configuration. If not, and you also know that deployment processes are not automated – you can expect issues like those described above.   

Item serialization is something very common in Sitecore solutions. Developers that have worked with Sitecore solutions for a long time know that TDS is a great tool but with Sitecore Helix principles being used incorrectly you could end up with issues. Due to the solution’s size, the number of TDS’s projects were significantly slowing down the build process and was making development and deployment very slow. This resulted in developers creating separate solution files to work with the code and speed up their development process, this wasn’t ideal. 

The number of projects was only one issue, the other issue was that all of the TDS projects were out of sync and contained too many items. Serialized items like templates were fine but there were also many media items and other content.   

On top of all that, there was also code generation that needed to be resurrected to be useful again.  

Migration of all TDS projects to the new Sitecore version and reviewing all the items would take too much time – our solution in this case was to replacement of all TDS projects with Sitecore CLI serialization. Every project would follow the same set of basic serialization rule. 

Thanks to this decision we easily made serialization useful again, drop all of the bad decisions that have been made over the years and introduced best practices. 

Closing notes

As you can see, even though a Sitecore upgrade is usually straightforward it can contain a few catches that are not obvious at first glance. Hopefully this post will add to your list of things to look for before you start your next upgrade. 

This post is part of a series, check back to find out more.