Introduction to Bloomreach Experience Manager Upgrades (to v11 or v10)
For projects upgrading to v12 or later, follow the current introduction instead.
In order to take advantage of improved code and new features, you should upgrade your Bloomreach Experience Manager project regularly.
Major Upgrade vs. Minor Upgrade
BloomReach distinguishes between major upgrades and minor upgrades.
By major upgrade, we mean to deploy a new version of your Bloomreach Experience Manager project, which uses a newer Bloomreach Experience Manager release with a major version number larger than the one currently deployed (e.g.from 10.2 to 11.0).
By minor upgrade, we mean to deploy a new version of your Bloomreach Experience Manager project, which uses a newer Bloomreach Experience Manager release with a minor version number larger than the one currently deployed (e.g. 11.1 to 11.2) or a patch version number larger than the one currently deployed (e.g. 11.1.0 to 11.1.1).
While BloomReach makes sure that minor upgrades are backwards compatible, providing you with bug fixes and minor improvements only, major upgrades require more attention from Bloomreach Experience Manager developers. During a major upgrade your environment, project code and project configuration may need to change.
For a minor upgrade, in general it is sufficient to follow the generic instructions for minor upgrades.
The system requirements can change for major releases. Verify your system and infrastructure matches the requirements when planning an upgrade.
To supports Bloomreach Experience Manager customers and partners in upgrading their implementations, BloomReach provides the Bootstrap Configuration Upgrade Verifier. A specific Upgrade Verifier is made available for each supported upgrade.
The availability of an Upgrade Verifier implies a supported upgrade. For example, if an Upgrade Verifier is available to upgrade from Bloomreach Experience Manager release A to Bloomreach Experience Manager release C, the direct upgrade from A to C is supported by BloomReach and it is not necessary to first upgrade to any intermediate version (e.g. B).
Fitness for Upgrade
Keeping your project fit for upgrades lowers the cost and risk associated with upgrading your Bloomreach Experience Manager project. In addition, upgrading regularly helps obtaining (and maintaining) the knowledge necessary to efficiently and successfully upgrade your Bloomreach Experience Manager project.
The "fitness for upgrade" of your project covers two main areas:
- The project sources
- The project configuration
These two areas are described in more detail down below. In order to keep the risk associated with upgrading low, we also recommend that you do not combine the development and deployment of new features with an upgrade. It may even be beneficial to prepare an upgrade by developing and deploying a project version which is fitter for upgrade than what was deployed before.
In order to keep your project sources fit for upgrade, consider the following:
- Keep the foot-print of your project small, the less code you have, the less code you need to upgrade. Avoid unnecessary complexity and code duplication. Remove unused (or no longer used) code and resources, your VCS remembers them for you.
- Avoid code forks. If you can't implement a feature without forking Bloomreach Experience Manager code, get in touch with BloomReach and see if there are other ways to accomplish your goal. Also, BloomReach may be willing to extend the CMS to enable you to implement the desired functionality in a fork-free way.
- When you can't avoid forking, document the exact version and origin of the forked code, as well as the reason behind the forking. Some forks are of a temporary nature (intent). Document the conditions under which a fork can be abandoned, refer to JIRA issues if applicable.
- Keep your repository data well-organized. Be careful including data which may mess up your production content or configuration.
- Use Maven version overriding sparingly, regularly check if your overrides are still necessary, and remove them if not. If you need to override a version, document why you're doing so. This will come in handy when removing the overridden version later on.
Your project configuration is primarily stored in the JCR repository. While your sources are "safely" packaged inside the deployed WAR, your project's configuration can change at runtime. An upgrade may cause the reloading of parts of your project configuration, and unless your project-specific configuration changes (or extensions) are properly included in your project's repository data, you run the risk of losing them during an upgrade.
For example, consider the situation where you deployed a new version of your project, which includes a new feature. A week after the deployment, you notice that some parameter, controlling the behavior of your new feature, should be adjusted. Luckily, you expose that parameter through a property of some configuration node in your JCR repository. You use the Bloomreach Experience Manager Console to adjust that property, and you're done. - No, not yet. The repository data of your project still contains the old value, and if a future upgrade happens to reload that property, your desired value will be lost. To avoid that, you need to incorporate your configuration change into your repository data.
As a Bloomreach Experience Manager developer, you're probably used to tweaking a project's configuration through the Bloomreach Experience Manager Console. Adjustments are made quickly, and it is easy to forget to incorporate them into your project's repository data. As a remedy to this problem, BloomReach supplies the upgrade verifier tool as of CMS 7.8.8. This tool helps you spot all "post-bootstrap" configuration changes, such that you can integrate them into your repository data (or get rid of them when no longer needed).
Testing the Upgrade
After an upgrade, you want to make sure that all of your project's features are still working as intended. Therefore, the Fitness for Testing of your project also contributes to the Fitness for Upgrade. The effort to test all features can be quite extensive, certainly if the knowledge of what features are included in the project, how they are supposed to work and how they can be tested has faded or is lost. For this reason, having a set of automated end-to-end tests covering the relevant features of your project is of utmost value. Such a set of tests both documents and proves the (in)correctness of the project's features.
If you have to resort to manual testing, you will value a dedicated set of content and configuration for testing the features in a development environment. The set should be small to avoid unnecessarily long bootstrap times, but large enough to support testing all features. Place resources to bootstrap the test content and configuration into a separate Maven module such that you can easily include (or exclude) it from your project. Typically, you don't want to encounter this data on your production system.