HomeDev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideGitHubNuGetDev CommunitySubmit a ticketLog In
GitHubNuGetDev CommunitySubmit a ticket

Upgrade Optimizely

Describes how to upgrade your Optimizely solution through Visual Studio and the NuGet package manager.

The Optimizely framework is a set of NuGet packages that are part of a web application, which you can host locally or in the cloud. You upgrade Optimizely through Visual Studio and the NuGet package manager. Releases are available weekly to keep your solutions up to date.



Looking to upgrade to ASP.NET Core and CMS 12? See Why upgrade to Optimizely Content Management System (CMS 12)?.

Upgrade steps

Optimizely products consist of a main NuGet package with dependencies to other required packages. When updating, you only have to select the main package.

Optimizely release packages are published to the Optimizely NuGet feed. You can download and install release packages from here with the Package Manager or command prompt in Visual Studio.

  1. If not already done, add the Optimizely NuGet feed to the NuGet package manager in Visual Studio. See Install a sample site.
  2. Right-click on References in your project, and select Manage NuGet Packages.
  3. Select Updates > Episerver and click Update for the EPiServer.Cms package. This adds the latest changes to your project.
  4. Compile your solution and start the website. If you have configured DataAccessOptions.UpgradeDatabaseSchema to false, you may see a system application exception caused by conflicting application and database schema versions, as each one targets a specific Optimizely version. In that case, you should use the EPiServer database command-line interface (CLI) tool to update the database.
  5. Reload the website and verify that you can access the user interface.

Release management

Semantic versioning

Optimizely follows semantic versioning. Release packages are numbered with a three-digit series, such as 12.12.0.

  • The release is called a major version when the first digit is bumped. Major versions are releases that have some breaking changes. By breaking changes, a developer may have to change something in their code before they can upgrade.
  • The release is called a minor version when the second digit is bumped. A minor release has some new features.
  • The release is called a bugfix version when the third digit is bumped. It only contains bug fixes. It does not contain any new functionality.

Example of releases:

11.0.0 (breaking changes) -> 11.1.0 (contains same functionality as 11.0.0 plus some new functionality) -> 11.1.1 (contains same functionality as 11.1.0 plus some bug fixes) -> 11.2.0 (same functionality as 11.1.1 plus new functionality) -> ... -> 11.8.2 (contains all features and bug fixes from previous versions plus new bug fixes) -> 12.0.0 (breaking changes).

Continuous releases

Instead of doing large releases once or twice a year, Optimizely uses a continuous release process with short development and test cycles, and releases versions every week or fortnight.

This way, each release only contains a limited number of features and bug fixes, speeding up the time to market and making upgrading smoother. Each release package is cumulative, which contains previous updates.

As a developer, you decide how often you want to upgrade, but the more you upgrade, the smoother it is.

How frequently should you upgrade?

The upgrade frequency of the Optimizely platform is entirely up to you and is probably driven by specific features and fixes you want or need. Update packages are cumulative, but the longer you wait between upgrades, the more likely it is that bigger changes will be introduced, which may result in a larger upgrade project.

If you find and verify an issue in the Optimizely platform, you should do the following:

  1. Upgrade your staging environment to the latest minor version within the same major version to see if the issue was resolved in a later minor version.
  2. If the issue is unresolved, go to the release notes and see if the issue was resolved in a later major version. If so, read the change log up to that version and consider whether an upgrade is reasonable. Major releases often have their documentation, such as Upgrade to Optimizely Content Management System (CMS 12) for example.
  3. If you consider the upgrade too big or the issue was not resolved in any update, contact customer support for a possible workaround.
  4. If customer support does not have a workaround, you may request a patch version within your current major version. Your request is triaged by the Optimizely development team with the following criteria for approving or declining a patch version:
    1. Actual impact for the customer.
    2. Identified regression issues for the patch.
      If the patch version is declined, the issue will be treated as a bug that will be prioritized for the next update.

See also the blog: EPiServer Continuous Release Process by Per Ivansson on June 19, 2014.

Release information

  • Optimizely release notes
    The Optimizely development teams use a software tracking system to track work items. When a feature or bug fix is in test, it is displayed in the Optimizely release notes feed with the status 'Soon to be released''. As soon as the feature or bug fix is approved and released, it is associated with a specific release, and the status is changed to a release date. Use the release notes to see details about what is included in a specific package version for a product. You can also use the filters in the release notes feed to create a list of, for example, all new user interface features that have been released during the last six months.
  • Optimizely updates
    Once a week, all release packages that are ready for release are published to the Optimizely NuGet feed. At the same time, an update summarizing the weekly release information is published to the Optimizely release update feed. Use the weekly updates as an overview to browse updates and decide when to upgrade a solution.

Beta features

To get access to features that are being developed, you can install Beta features. See Beta features.

Related topics