Tips for Applying Cumulative Sitecore XM/XP Patches and Hotfixes

A while back, Sitecore changed their patch model to be cumulative rather than iterative. This makes perfect sense because it greatly reduces complexity and the overhead of supporting each historical / outdated patch. This approach allows Sitecore to be more focused and effective. For example, and to Sitecore's credit, they recently started doing more security auditing of their codebase and released a flurry of security patches over the past year. This has posed challenges for partners in terms of how they manage / apply / test patches. From what I've seen and heard, the Sitecore community has been struggling with this change.

This post covers some challenges, approaches, and learnings with regards to applying cumulative patches for Sitecore XM/XP, be they hotfixes or not.

One unique challenge I encountered was an error related to a cumulative patch which was difficult to troubleshoot because the patch was not documented anywhere.

In my case, on my local site, the Content Editor search was broken. The following error message was displayed:

In the Sitecore logs:

The offending code:

As far as I could tell, this code was not part of the default Sitecore installation. I did some investigating, and this config appears to have originated from the Sitecore.Support.008435 package. Support packages such as this are often "ephemeral" in the sense that since Sitecore now only does cumulative fixes, historical patches lack public documentation because they are replaced as new cumulative patches are released; that is, for a given version of XM/XP, Sitecore maintains a centralized SharePoint directory containing the cumulative patch, and updates it in real time. The changes and documentation are also not crawlable because the SharePoint directory requires authentication. Case in point:

In my case, the issue seems to have been at least partially caused by the fact that the CloudCumulative version of the patch was installed on all environments, including local environments. Presumably, a step in the right direction would be to apply the OnPremCumulative version on local environments and to continue troubleshooting from there, if needed. This then begs the question: how should one manage patches across different environments/architectures?

Generally speaking, don't expect much help or documentation when it comes to patches. Make sure you have solid processes in place.

Some interesting discussions have taken place within the Sitecore community about how to manage patches. I don't take credit for any of the following discussion points that took place in the Sitecore Slack, but I wanted to surface them for the public:

🥸 said:

DLLs in Hotfixes vs NuGet references: I logged a support ticket asking exactly the same question (whether Sitecore plans to release NuGet packages for the latest security patch) and the answer was that "Sitecore does not provide NuGet packages for hotfixes". That then begs the question - what's the best way to maintain your solution structure. You'll need to remove the NuGet references for these updated DLLs - right? If someone can expand on this a bit - I would greatly appreciate it.

😺 said:

I've generally deployed hotfixes over top as part of Cl/CD, as there shouldn't be anything added in a hotfix that your code relies on (ie for adding as NuGet in a solution)

🥷 said:

i follow the other path. reference the hotfix DLLs in the project especially if Sitecore.Kernel is in the hotfix package to avoid mysterious errors.

👨‍🚒 said:

I prefer to go the route that 😺 posted, as it is rare that the changes impact development. If you add them to a project, then this can create issues with upgrades, as well as potential issues when someone makes a new project and uses a NuGet package instead of the hot fix DLL.

💂‍♀️ said:

Been following a similar route to 🥷, but create a separate Support project in the solution. The NuGet packages in the other projects are left alone (we use .wpp.target files to prevent Sitecore DLLs being published). We can then delete this "feature" during an upgrade.

👨‍🚒 said:

That works with wpp and makes sense.

To summarize, some of the high level approaches include:

• Templated CI/CD deploy step that installs files on top of the solution
• Include patch files directly in solution
• Install (patches which are not hotfixes) as NuGet packages
• Apply changes directly in the affected environments and don't include in code or CI/CD (not recommended)

Diving in a little more to this approach, there are pros and cons.

One con that comes to mind is that patches are only applied upstream, so there may be environment deltas between local and upstream installs. This can result in local issues that don't appear in upstream environments, thus potentially resulting in wasted time if a developer is trying to troubleshoot an issue that isn't an actual issue. In this case, you should probably indicate in the README that a patch will need to be manually applied in local environments. Better yet, you can automate this via Docker install scripts.

One pro is that the CI/CD approach is highly scalable if you are managing many sites. You get a lot of oversight and the ability to quickly deploy patches to all of your sites.

The code in solution approach can certainly be appropriate for some implementations. The big question is how to best do it. Some things to consider:

• Where should the files actually live within the solution, and how do you differentiate and reconcile the interactions and deploy order of the patches?
• How to deploy the patches in local environments?
• How to deploy the patches in upstream environments? Recall that local and cloud installs can have different architectures.
• How to prevent atrophy of documentation within the code?

You will also want to consider upgrade implications.

• Sitecore does not provide NuGet packages for hotfixes.
• There are various approaches for applying cumulative patches. The one you choose will depend on your team's preferences and your CI/CD pipeline. Personally, I like the CI/CD approach.
• Keep documentation (who, what, where, when, why) for when you apply cumulative patches. Including this documentation in the code has the benefit of being version controlled and easily accessible by multiple teams who may not have access to the programs where you may store other documentation (Confluence, Notion, etc.).
• Know the differences between packages for different types of deployments and understand that you must apply the patch that applies to the specific environment you are working in (example: don't install OnPrem patches on cloud environments, and vice versa). Come up with processes to ensure that the correct versions are installed on the correct environments:
  • Cloud
  • CloudCumulative
  • OnPrem
  • OnPremCumulative
• Keep track of how and where you applied previous patches.
• Apply the latest cumulative patch before contacting Sitecore Support.
• If the issue persists, contact Sitecore Support.
• Compare your code deltas with the latest cumulative patch and also the default Sitecore installation to identify deltas.
• Automate regression testing where possible.

Or, migrate to XM Cloud and let Sitecore handle the patching for you. 😎

KEEP PATCHING,

MG