Upgrading Elastic Path
Upgrading Elastic Path
This document is only a guide, not a step by step process to upgrade your Elastic Path software. Depending on your environment, data, and customizations you've made to Elastic Path Commerce, some of these changes may require you to perform additional steps before or after upgrade.
- Preparation - Gather information about your known customizations and decide how you want to mitigate your risks.
- Customization Analysis (Optional) - Analyze 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 - A workflow breakdown of the upgrade tasks.
The preparation phase involves gathering information and mitigating risks before you perform the upgrade. The image below shows an overview of the preparation process.
Create a list of all your known EP platform customizations.
- If you don't know your EP platform customizations, read Customization Analysis and reverse engineer the code to find them.
Gather the source code appropriate for your upgrade. For example, upgrading from EP 6.7 to 6.14 requires the original version "6.7 original", the customized version "6.7 custom", and the new version "6.14 original".
- Review the documentation and technology stack for the new version of EP.
- Review the Elastic Path Release Notes for bug fixes, new features, new technologies, code changes, deprecations, and so on.
- Important changes to the Elastic Path code base:
- 6.1: Binary-based extension model
- 6.4: Maven and Liquibase
- 6.11: Standard layout and naming conventions for extension projects and SCM repositories (Starting Construction Guide)
- 6.13: Standard deployment process (ThePusher)
Upgrades can break functionality in unpredictable ways. Flag customizations that lack written or automated test cases.
- Address the risks found during Customization Analysis
- Improve test coverage
- Refactor code
- Provision long-lead items ahead of time, such as new hardware or training
- Defer upgrades of independent systems (scope reduction)
- Upgrades introduce new technologies that require time to learn
- Create a training plan using the list from Identify modernizations
Customization Analysis (Optional)
Customization analysis is useful when an organization does not know what was customized on the platform. This section will help you derive a complete list of the customizations made to your organization's platform in a time-boxed investigation. This section focuses on breadth (completeness of the list), not depth (detailed understanding of each customization).
- Chat with the Maintainers
- Read all the Code in One Hour
- Do a Mock Installation
- Skim the Documentation
- Interview During Demo
- Feature should be upgraded as-is
- Problematic feature implementation to the point where it needs a re-write
- Feature could be achieved using functionality in a newer version of EP
- Unused code or feature that should be removed
Upgrading breaks the application for an extended period of time. This means a normal workflow that includes QA is not possible until the upgrade is mostly complete. Upgrade projects should transition between a normal and upgrade-specific workflow as follows:
The upgrade-specific workflow consists of the following issue transitions:
To Do > In Progress > Ready for Peer Review > In Peer Review > Done
We recommend separating the upgrade backlog from other development projects. Derive a list of backlog items from the above time line diagram. For JIRA users, try the simplified agile workflow for its easy workflow customization.
- For instructions on Inception and source code layout, see the Starting Construction Guide.
The database needs to be taken offline when upgraded, so expect downtime during the release. Obtain a copy of the production database for testing the upgraded schema and data:
- Sanitization means deleting personal information, security credentials, and environment-specific data (URL's, IP addresses, etc).
Prior to version 6.4, data upgrades were performed with vendor specific SQL. The SQL was distributed with the release, and the release documentation lists the order it must be run. Upgrade related data fixes must be included in the vendor SQL, which should be scripted by the upgrade team, as well as checked into source control.
Starting in version 6.4, Liquibase manages upgrading the database to newer versions. Upgrade-related data fixes must be included in an XML changelog which resides in the extension "core-schema" module.
Consider deleting transient data if it is problematic to migrate. For example, shopping carts and customer sessions fall into this group. Enable the EP database clean-up jobs if they are disabled.
This approach creates a patch containing all the customized code. Port the customizations between versions by applying the patch to the source code's target version.
Start by arranging the source code into local root folders for ease of reference. For example, upgrading from EP 6.7 to 6.14 will need folders "/commerce-legacy/ep6.7-original", "/commerce-legacy/ep6.7-custom" "/commerce-legacy/ep6.14-original", "ep6.14-custom". Remember to clean ignored files and build artifacts from the source folders. Break large patches into many smaller patches and put them in your issue tracker.
diff -U 3 --ignore-all-space --recursive --unidirectional-new-file /a /b > all-customizations.patchHere is an improved version of the command that ignores the reversioning changes. This example is for an upgrade with a starting version of 6.10:
diff -U 3 --ignore-all-space --recursive --unidirectional-new-file -I '<version>610\.0\.0' -I 'Bundle-Version: 610\.0\.0' -I 'version=\"610\.0\.0' /a /b > all-customizations-without-reversioning.patch
Verify the diff command output by diffing the current and prior diff files each time you modify the arguments. This will ensure the new command does not accidentally ignore something important. Remember to peer-review the patch files for binary changes.
We recommend applying small patches with an IDE GUI-based patch tool. Take extensive notes when you cannot understand the merge conflicts. Alternatively, use a three-way merge tool such as P4Merge or KDiff3. We do not recommend using rudimentary patch commands.
Appendix: General advice
Maintain a working IDE & environment for the old version during the upgrade. This supports comparing behavior of the old vs. new code in a debugger.
Appendix: Upgrading over the 6.4 version boundary
Many files changed location due to "Mavenization" of the codebase between version 6.3.2 and 6.4. File path changes degrade the upgrade tool-chain. For example, look at the uneven nesting of source folders:
Version 6.2, nine directories deep:
Version 6.5, ten directories deep:
The Eclipse Apply Patch Wizard can address inconsistent nesting depth with a feature called "ignore leading path segments".