Upgrading Elastic Path
Upgrading Elastic Path
This document provides generic instructions to upgrade a version of Elastic Path Commerce to a newer version of Elastic Path Commerce. However, this document does not provide step by step instructions to upgrade your Elastic Path software. Depending on your environment, data, and customizations you've made to Elastic Path Commerce, you might have to perform additional tasks before or after the upgrade.
- Preparation: Gathers information about your known customizations and decide how you want to mitigate your risks.
- Customization Analysis (Optional): Analyzes and determine what customizations you've made. This optional phase is for organizations who don't know what customizations have been made to the platform.
- Upgrade: Performs the upgrade to a newer version of Elastic Path Commerce.
- Identify customizations: Create a list of all known Elastic Path platform customizations. If you don't know your Elastic Path platform customizations, see Customization Analysis and reverse engineer the code to find them.
- Determine versions: Get the appropriate source code for your upgrade.
- Identify modernizations: Do the following:
- Review the documentation and technology stack for the new version of Elastic Path.
- Review the Elastic Path Release Notes, for the current version of Elastic Path and for all versions until the version you are upgrading to, for bug fixes, new features, new technologies, code changes, or deprecations.
- Identify a regression test strategy: Identify customizations that lack written or automated test cases.
- Reduce risk where possible: Do the following:
- Address the risks found during the Customization Analysis.
- Improve test coverage.
- Refactor code.
- Provision the resources that require time to arrange ahead of time, such as new hardware or training.
- Defer upgrades of independent systems (scope reduction).
- Train the team on new version: Create a training plan using the list at Identify modernizations to train the team on new technologies, if any.
- Identify components to upgrade: Identify the minimum set of components or
dependencies that must be upgraded. Hosted infrastructure might need to be upgraded for the
new Elastic Path platform.
Customization Analysis (Optional)
Customization analysis helps you derive a complete list of the customizations that are made to
your organization's platform in a time-boxed investigation. This section focuses on the
completeness of the list, not on the detailed understanding of each customization.
- Apply reverse engineering patterns: Reverse engineering is a general software engineering practice. For more information, see Reverse Engineering in Chapter 2 Object-Oriented Reengineering Patterns at http://scg.unibe.ch/download/oorp.
- Identify risks in the source code: Record the following problems if you find them
while examining the source code:
- No test coverage
- Code smells
- Cross-cutting concerns
- Identify risks in the infrastructure: Record the following problems if you find them
while examining the environment installation, build, deploy, and release processes:
- No Continuous Integration
- Manual deploy or release process
- Lack of staging environments
- Prepare upgrade action list: Arrange the unorganized list of features or
customizations for one of the following upgrade actions:
- Upgrade feature as-is
- Problematic feature implementation that requires reimplementation
- Implement a new feature using functionality in a newer version of Elastic Path Commerce
- Remove unused code or feature
Upgrading breaks the application for an extended period of time, so a normal workflow that includes QA is not possible until the upgrade is complete. Upgrade projects must transition between a normal and upgrade-specific workflow as in the following diagram:
The upgrade-specific workflow consists of the following issue transitions:
Elastic Path recommends separating the upgrade backlog from other development projects. Derive a list of backlog items from the above time line diagram. JIRA users can use the simplified workflow for its easy workflow customization.
- Get a copy of the production database for testing the upgraded schema and data:
- Perform sanitization of data, which is deleting personal information, security credentials, and environment-specific data, such as URL's, IP addresses.
- Delete transient data, such as shopping carts and customer sessions, if it is problematic to migrate.
- Enable the Elastic Path database clean-up jobs if disabled.
- To create a path file, port the customizations between two versions by applying the patch
to the source code's target version.
- Arrange the source code for each version of Elastic Path into two directories for each version, one for customizations and one for unmodified Elastic Path source code. For example, upgrading from Elastic Path Commerce 6.7 to 6.14 needs, "/commerce-legacy/ep6.7-original", "/commerce-legacy/ep6.7-custom" "/commerce-legacy/ep6.14-original", and "ep6.14-custom" folders.
- Remove unwanted files and build artifacts from the source folders.
- Break large patches into smaller patches and put them in your issue tracker.
- Run the following command to compare the code in the directory /a and /b, and extract the
customizations in the directory /b in to a patch file:
diff -U 3 --ignore-all-space --recursive --unidirectional-new-file /a /b > all-customizations.patchFollowing is an example is for an upgrade without reversioning changes:
diff -U 3 --ignore-all-space --recursive --unidirectional-new-file -I '<version>version number\.0\.0' -I 'Bundle-Version: version number\.0\.0' -I 'version=\"version number\.0\.0' /a /b > all-customizations-without-reversioning.patchReplace version number with the current version.
- Verify the diff command output by comparing the current and prior diff files each time you modify the arguments.
Elastic Path recommends applying small patches with an IDE GUI-based patch tool. You can also use a three-way merge tool, such as P4Merge or KDiff3. Elastic Path does not recommend using rudimentary patch commands.The Eclipse Apply Patch Wizard addresses inconsistent nesting depth with the ignore leading path segments feature.