Leading practices when upgrading

This is for:

Developer System Administrator

To take advantage of new features, enhancements, and bug fixes that come with new releases of Coveo for Sitecore, you’ll need to eventually upgrade it. This page describes the best practices that you should consider when upgrading and going live with your deployment.

General leading practices

Multi-release upgrade

Each release of Coveo for Sitecore has a procedure describing the specific steps necessary to upgrade from the previous release.

If the version you need to upgrade to isn’t consecutive with the one you currently have, then proceed as in the following example.

Example : To upgrade from Coveo for Sitecore release x to release x+3

  1. Download and install the Coveo for Sitecore x+3 release package.

  2. If need be, also download and install Coveo for Sitecore SXA version x+3.

  3. Perform the release x+1 upgrade steps starting in step 2 (which often is the Manually update Coveo configuration files step). You don’t need to do the Publish your site step.

  4. At the end of the release x+1 upgrade steps, click Next version upgrade steps 〉. This will take you to the Coveo for Sitecore release x+2 upgrade steps.

  5. Perform the release x+2 upgrade steps starting in step 2. You don’t need to do the Publish your site step.

  6. At the end of the release x+2 upgrade steps, click Next version upgrade steps 〉. This will take you to the Coveo for Sitecore release x+3 upgrade steps.

  7. Perform the release x+3 upgrade steps, from step 2 to the last inclusively.

Illustration of the upgrade example above | Coveo

Alternatively, if there are too many releases between your current release and the most recent one, you can:

  1. Keep a copy of all the Coveo configuration files.

  2. Upload and install the most recent Coveo for Sitecore package.

  3. Using a merge tool, manually merge your custom changes made in your backed up config files to the new config files.

Tip

Never directly modify a Coveo file or item. The main Coveo configuration files are installed in the <SITECORE_INSTANCE_ROOT>\App_Config\Modules\Coveo\ folder of the Sitecore instance. Like for all other Sitecore configuration files, don’t edit them directly. Main configuration files have a companion file with a .custom.config extension in the <SITECORE_INSTANCE_ROOT>\App_Config\Include\Coveo\ folder. These files are patch files to be used without danger of overwriting during an upgrade. However, items and code files (.aspx, .cshtml, etc) can’t be patched. Before customizing those files, create a copy of them.

Test the upgrade in a non-production environment

Upgrades often require a few changes to the configuration files, so upgrading a production site may cause some downtime on your search pages.

Test on a fresh instance

When upgrading from Coveo for Sitecore 4 to Coveo for Sitecore 5 or from On-Premises to the Cloud using custom configuration, consider testing the new setup (Coveo for Sitecore 5 or Cloud) on a fresh instance. This way you will avoid any unrelated configuration issue that might result from a bad merge or manipulation.

Upgrade frequency

When actively developing a site, we recommend that you upgrade to each new release of Coveo for Sitecore. Then, once you go live, we recommend that you upgrade only once or twice a year to make sure that you take advantage of the latest enhancements and bug fixes. While you might not want to upgrade a site that’s running smoothly and without issues, these recommendations are based on the fact that upgrades become more complex as your current release becomes older.

If you encounter a problem or a bug that needs to be fixed, see the release notes to find out if the issue has already been fixed. If so, you need to upgrade to the associated release. If not, check Coveo Connect (Collaborate tab) to find an appropriate solution. Alternatively, you can report the problem to our support team. Issues fixed in the product are usually available in the next release, or in hotfixes for critical ones.