This series of devlogs is intended to help beginners with the Sitecore upgrade work. You’ll follow along with my thought processes and what you need to start an upgrade.

If you did upgrades in the past, you will find most of the content here is dreadfully boring. However, you can still get some insights especially around the issues I encountered.

There's no way for a product team to anticipate all the troubles one goes when upgrading software. But, you will see what went wrong as I was upgrading and how to workaround some of the issues and limitations.

In this first part, I start with the planning phase.

How do you start?

Before you download the upgrade package and start reading the documentation, you should do some initial work involving the stakeholders of your company.

Let's start by making an initial assessment around the upgrade.

Make an initial assessment

Ask some questions. At minimum, get the following covered.

What is the current Sitecore version and the target version?

Depending on the current version, you need to make gradual upgrades. e.g. if the current version is 8.0, you need to upgrade to Sitecore 8.1 first before upgrading to Sitecore 10.1.

Will the migration include historical Sitecore analytics and/or contact data (i.e. xDB)?

Assuming that you have a XP instance, instead of a XM, do the stakeholders want to keep the historical data collected by xDB?

In some cases, business don’t mind losing the historical analytics data in Sitecore since they collect them through external tools such as Google Analytics.

Also, it is important to know that MongoDb has been removed in version 10.1. You need to migrate the data to SQL Server using the Express Migration tool.

Is xDB being used right now? Should the upgrade enable xDB/xConnect?

If the answer is yes, you should check if you have the proper licenses for that - ask your Sitecore Sales rep. If there’s no intention to use xDB, consider using the CMS-Only mode (cost saving).

In CMS-Only mode, the xDB/xConnect is disabled and no analytics data is collected.

Do you plan to use any of the new Sitecore 9.x or 10.x features (JSS, EXM, Marketing Automation, Horizon, Cortex, etc)?

You might be looking forward to working with JSS, but before you do so, please check if your license supports it.

Once again, ask your Sitecore Sales rep.

Are there any Sitecore or 3rd party modules in use?

This is an important step in the assessment. Depending on the module in usage, you will incur in additional effort to either upgrade the module, recompile it in case it is no longer updated by Sitecore/or the Community, replace it, or completely decommission it.

If the module is maintained by a vendor, do they have a version compatible with the upgrade? When do they plan to release it?

Gather a list of all Sitecore environments (Production, Stage, Test, Dev, etc.) to include as part of the migration

Upgrading Sitecore requires you to set up new environments or update existing ones.

How many Sitecore websites you’ll upgrade, and if they are hosted on a single Sitecore instance or hosted as separate Sitecore instances

This will affect the estimate efforts. Also, should you upgrade them in parallel, are there any interdependencies, should them both be upgraded?

Any custom connectors/integrations that need to be migrated

This would include products such as Marketo, SAP, Salesforce, among others.

Any installed Sitecore support patches

You can file a ticket to the Sitecore Support asking whether those patches are fixed in the target version.

The current roadmap — either in progress or planned — that could impact or be impacted by the migration

At some moment, you need to start a code freeze to deploy the upgrade.

Talk to the stakeholders about the roadmap. Make them aware that at a given date (or week) no new releases will take place until the upgrade goes live.

Does the instance utilize the Sitecore Search API? Which search engine is being used with Sitecore?

You might be using Coveo Search, or a custom search implemented using Elasticsearch, for example.

Is there a released version compatible with the target Sitecore version?

Take these things into account for the upgrade.

What type of hosting you are currently using for your Sitecore instances and do you plan to migrate those?

On prem, Cloud, or Hybrid. Consider the costs and the cloud provider preferred.

Get an architecture diagram for each server instance, in each environment

This would include:

• Content Delivery roles
• Content Management roles
• Other Sitecore roles (like Processing/Aggregation, Reporting, Publishing)
• Additional servers (such as SQL Server, MongoDB,and SOLR indexing servers)
• Caching or session services (like Redis)
• CDN service provider(s) used per environment

Approach for the upgrade process

• Side-by-side instances (separate servers): In this approach, you work completely separated from existing production and testing environments. Be aware of the additional infrastructure and cost requirements, associated with spinning new server(s) for the target version of Sitecore and its infrastructure.
• Side-by-side instances (same servers): In this approach, you run the upgrade in the same server where the current Sitecore version resides. You need to make sure the OS, IIS, .NET Framework, etc. are meeting minimum requirements of the target Sitecore version, and using a common infrastructure such as SQL, MongoDB, SOLR, etc.
• In-place Sitecore instance upgrade: Run the upgrade against the current version of Sitecore. Replace/upgrade the current version with the target version in each environment. In 99% of cases, this approach is not even an option, as it completely replaces current environments while having the site down during the upgrade. This could be an option in case the site has not been released yet. It might have started being developed in an older version and now business wants to take advantage of the new features in newer Sitecore versions.

Website visitor numbers

This number can help you to evaluate whether the planned upgrade architecture will support the workload.

Take for instance the kb Sitecore Managed Cloud Standard – topologies and tiers for Sitecore XP 10.0. As you can see, depending on the approximate visits per month range, you scaling strategy will vary and incur in more costs.

Existing build and deployment process

How is the solution currently deployed?

If you don’t have a CI/CD in place, maybe this is the opportunity to get some budget to set this up.

How long a freeze is acceptable for the stakeholders

You must let everybody known that at some point content update will need to wait until you go live with the upgrade. This could be 3 days, a week, or more. Speak to the business and come to an agreement.

Also, code freeze is important, since you don't want to merge code on the go-live date. Or even worst, get a call from Bob-the-marketer complaining that his new fancy hero banner is no longer available after the upgrade.

If possible, what are the current known issues

You might want to know what is not currently working, so you don't waste time trying to bug fix something that was not broken by the upgrade.

"What is in there" phase

At this stage, you should challenge your initial assumptions about the upgrade.

You will get databases backup, the website folder, the latest source code, all from production (if possible), and finally install everything on your machine.

Double-check everything:

• current Sitecore version
• actual Sitecore/third-party modules installed
• Sitecore Support patches
• is the solution following the Helix guidelines?
• is there any automated process to publish assemblies and configs (Gulp, Powershell, customizations done to MSBuild)?
• is there any Sitecore system file (.configs, .aspx pages, etc) that have been overwritten?

You'll also read the release notes from the versions between the current and the target one. See what have been deprecated, what have been removed, what are the breaking changes. For example, if you are using SXA, and have created NVelocity templates, those no longer work on newer Sitecore versions. You must migrate them to Scriban templates.

Read the installation and also the upgrade guide of the target version.

Gather every information you think will have an impact in the chronogram.

Risk assessment

After you get familiar with the solution you will upgrade, the release notes, the upgrade guide, you should list all the risks in the project and how you could mitigate them.

A risk is something that could potentially go wrong and impact your planning or completely block your progress. Trust me, when you are upgrading software a plethora of things can go wrong.

Some of the common risks are:

• Historical analytics data such as page visits, contacts, EXM, Marketing Automation, Form Submission, collected prior to migration can be no longer available.
• Compatibility issues between third-part modules and the target Sitecore version.
• Third-party module is no longer supported by the open source community and thus incompatible with the target Sitecore version.
• Known issues in the target version
• Site SEO being impacted
• Breaking changes in your code due to upgrading a Nuget package, the target Sitecore version, or a third-party module.
• Frequent merges to get the latest features and potentially delaying any progress.
• Changes in the scope of the upgrade. For example, besides upgrading you have to implement a new feature and go-live together with the upgrade.

Estimates and Planning

Here, you should list all the tasks and milestones for the project, and put some estimates on them.

If you don't have any idea from where to start, I breakdown some of the common tasks:

Milestone: Local Upgrade Work

• Setup local Sitecore instances (restore database backups from production, configure website, rebuild indexes).
• Local project/solution setup.
• Update the target framework to .NET 4.8.
• Update the Sitecore Nuget Packages.
• Replace local Sitecore libraries with Nuget Packages.
• Update/Remove usages of deprecated and obsolete code from the Sitecore API.
• Update Nuget Packages mismatches between the solution and target version.
• Remove from solution the Sitecore Support patches that are fixed in target version.
• Fix breaking changes caused by updates in the Sitecore API.
• Run SQL scripts to upgrade the databases.
• Install Sitecore XP 10.1.0 and connect the databases.
• Deploy upgraded Sitecore solution and fix any breaking changes.
• Run Post-upgrade steps.
• Upgrade/remove Sitecore modules.
• Update/Recompile third-part modules.
• Migrate search engine from Lucene (removed) / Azure Search (marked to be removed in newer releases) to Solr.
• Merge latest code changes from release branches into upgrade branch.
• Ad hoc tests and bug fixing.
• DevOps Pipeline Creation.

Milestone: DEV/UAT/PROD

• Infrastructure (on-prem/cloud): new servers, security, installation, databases, etc.
• Deploy solution into the environment.
• Run Post-upgrade steps.
• Troubleshooting and bug fixing.
• Go Live.
• xDb Migration.

During this stage, you will be tempted to add some technical debts into the scope.

• Should you completely refactor the solution to Helix?
• Maybe that caching implementation could be fixed?
• Maybe rework those url redirect logics?

Be careful with adding too much to the scope as it might become a burden once the go-live date approaches. Try limiting the scope to solely doing the upgrade.

And always involve in the planning phase every person that will be impacted by the upgrade, from the marketing team to the infrastructure guys, up to the Bob-know-it-all from the engineering department.

Conclusion

That's it for this first part.

I had to get the non-technical stuff away so we can focus on more hands-on work in the next parts.

Coming next, I'll be writing about the software requirements, tools to speed up your upgrade, issues, and how to upgrade your solution.

Credits

Photo by Ylanite Koppens from Pexels.