Minor Upgrades

Overview

This page describes the process for upgrading from one minor version to the next in Bloomreach Content (formerly Hippo CMS).

Purpose

Upgrade your project from the previous minor version to the current minor version.

Context

Minor releases of Bloomreach Content are backward compatible. Upgrading from one minor version to the next (for example, from 13.0 to 13.1) follows a standard set of steps. This page outlines those steps.

Info: Starting with version 16.6.0, Bloomreach has introduced a new Incubating Features and Extension Points Policy. This policy may affect backward compatibility for minor versions. For details, see the Incubating Features Policy.

Supported Upgrade Paths

Upgrade Only to the Latest PATCH Version Within a MINOR Version

Bloomreach Content uses semantic versioning in the format MAJOR.MINOR.PATCH:

Increment the MAJOR version for incompatible API changes.
Increment the MINOR version for backward-compatible functionality additions.
Increment the PATCH version for backward-compatible bug fixes.

When upgrading the MINOR version, upgrade to the latest available PATCH version of the target MINOR version. Upgrading to an earlier PATCH version may introduce compatibility issues.

Upgrading Across Multiple MINOR Versions

Upgrading the MINOR version by two or more (for example, from 14.0.0 to 14.2.2) is supported. You must review and apply all mandatory upgrade steps for each intermediate minor version.

For example, when upgrading from 14.0.0 to 14.2.2, review the upgrade instructions for:

14.0.x → 14.1.y
14.1.y → 14.2.z

You do not need to deploy after each intermediate step. You can deploy the upgraded project once, using -Drepo.bootstrap=true (see below), to move directly from 14.0.0 to 14.2.2.

Upgrade Procedure

Follow these steps to upgrade to a new minor version.

1. Update the Release Pom Version

Each project created with the Maven archetype uses the Hippo Release Pom as the parent in its root pom.xml.

Update the hippo-cms7-release version in your project's root pom.xml. For example, to upgrade to 14.2.2:

<parent>
  <groupId>org.onehippo.cms7</groupId>
  <artifactId>hippo-cms7-release</artifactId>
  <version>14.2.2</version>
</parent>

2. Remove Version Property Overrides

The Hippo Release Pom manages the versions of all artifacts in a release. Projects may override artifact versions in the root pom.xml to use newer bug fixes:

    <!--***START temporary override of versions*** -->
    <essentials.version>14.3.0</essentials.version>
    <hippo.hst.version>14.3.1</hippo.hst.version>
    <!-- ***END temporary override of versions*** -->

After upgrading to a new minor release, these overrides are typically no longer needed. Remove all version property overrides from your project's root pom.xml.

3. Enable Repository Bootstrap During Deployment

New releases may require changes to repository-stored configuration using the repository bootstrap mechanism. To apply these changes, enable repository bootstrap when deploying the upgraded project.

Set the repo.bootstrap system property to true:

-Drepo.bootstrap=true

4. Run Groovy Updater Scripts (If Applicable)

Some releases include Groovy Updater Scripts to update configuration or content in the repository.

After deploying the upgraded project, run any Groovy Updater Scripts as described in the upgrade instructions for that release.

5. Review Release Notes for Additional Steps

Always review the release notes and upgrade instructions for the new release. Complete any additional steps required for that specific version.