Announcement: You can find the guides for Commerce 7.5 and later on the new Elastic Path Documentation site. This Developer Center contains the guides for Commerce 6.13.0 through 7.4.1.Visit new site

This version of Elastic Path Commerce is no longer supported or maintained. To upgrade to the latest version, contact your Elastic Path representative.

Upgrading Elastic Path

Upgrading Elastic Path

This document is a guide for upgrading your version of Elastic Path. You can apply this process for any Elastic Path version.
Note: This document is only a guide

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.

The upgrade process consists of three phases:
  1. Preparation - Gather information about your known customizations and decide how you want to mitigate your risks.
  2. 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.
  3. Upgrade - A workflow breakdown of the upgrade tasks.

Preparation

The preparation phase involves gathering information and mitigating risks before you perform the upgrade. The image below shows an overview of the preparation process.

Identify customizations

  • 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.
Determine versions

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".

Identify modernizations
  • 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)
Decide on a regression test strategy

Upgrades can break functionality in unpredictable ways. Flag customizations that lack written or automated test cases.

Reduce risk where possible
  • 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)
Train the team on new version
  • Upgrades introduce new technologies that require time to learn
  • Create a training plan using the list from Identify modernizations
Identify components to upgrade
  • Hosted infrastructure may need to be upgraded for the new EP platform
  • Identify the minimum set of components/dependencies that must be upgraded

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).

Apply reverse engineering patterns
Reverse engineering is a general software engineering practice. For inexperienced practitioners, a good starting point is "Reverse Engineering" in Chapter 2, Object-Oriented Reengineering Patterns (http://scg.unibe.ch/download/oorp). This chapter recommends a set of "patterns" to rapidly understand an unfamiliar system. Of note in this chapter are the following sections:
  • Chat with the Maintainers
  • Read all the Code in One Hour
  • Do a Mock Installation
  • Skim the Documentation
  • Interview During Demo
Risks in the codebase
Record these problems if you discover them while examining the codebase.
  • No test coverage
  • Code smells
  • Cross-cutting concerns
Risks in the infrastructure
Record these problems if you discover them while examining the environment installation, build, deploy, and release processes.
  • No Continuous Integration
  • Manual deploy / release process
  • Lack of staging environments
Upgrade Action
Arrange the unorganized list of features / customizations according to one of four upgrade actions:
  • 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

Upgrade

Workflow

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.

Source code preparation
Replace the customized source code in version control with the new EP release version. Perform the Inception process on the new version (enhancement and reversioning). Commit the changes.
Data upgrade - Overview

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).
Data upgrade - Pre 6.4 process

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.

Data upgrade - Post 6.4 process

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.

Data upgrade - Common data errors

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.

Extract customizations

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.

The following command will compare the code in folder /a and /b, and extract all the customizations in folder /b into a patch file: 
diff -U 3 --ignore-all-space --recursive --unidirectional-new-file /a /b > all-customizations.patch
Here 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.

Re-apply customizations

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.

Eclipse, Apply Patch Wizard:
IntelliJ, VCS | Apply Patch:
  • https://www.jetbrains.com/idea/help/applying-patches.html

Appendix

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:

  • \ep6.2-custom\com.elasticpath.core\WEB-INF\src\main\java\com\elasticpath\service\customer\CustomerService.java

Version 6.5, ten directories deep:

  • \ep6.5-custom\platform\core\ep-core\src\main\java\com\elasticpath\service\customer\CustomerService.java

The Eclipse Apply Patch Wizard can address inconsistent nesting depth with a feature called "ignore leading path segments".