Commerce

7.5.x

Upgrading Elastic Path Commerce

This section provides generic instructions to upgrade a version of Elastic Path Commerce to a newer version of Elastic Path Commerce. However, this section does not provide step-by-step instructions to upgrade your Elastic Path software. Depending on your environment, data, and customizations that is made to Elastic Path Commerce, you might have to perform additional tasks before or after the upgrade.

The upgrade process consists of three phases:

  1. Preparation: Gathers information about your known customizations and decide how you want to mitigate your risks.
  2. Customization Analysis(Optional): Analyzes determine what customizations are made. This optional phase is for organizations if the customizations made to the platform is unknown.
  3. Upgrade: Performs the upgrade to a newer version of Elastic Path Commerce.

Elastic Path recommends maintaining a working IDE (Integrated Development Environment) for the old version during the upgrade. This supports comparing functionality of the old code with the new code in a debugger.

Preparation

The preparation phase involves gathering information and mitigating risks before performing the upgrade. The following diagram shows an overview of the preparation process:

Upgrade Preparation

  1. Identify customizations: Create a list of all known Elastic Path platform customizations. To know your Elastic Path platform customizations, see Customization Analysis and reverse engineer the code to find them.

  2. Determine versions: Get the appropriate source code for your upgrade.

  3. 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 or other details

  4. Identify a regression test strategy: Identify customizations that lack written or automated test cases.

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

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

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

    Components to Upgrade

Customization Analysis

Customization analysis helps you derive a complete list of the customizations that are made to the platform in a time-boxed investigation. This section focuses on the completeness of the list, not on the detailed understanding of each customization.

Customization Analysis

  1. Apply reverse engineering patterns: Reverse engineering is a general software engineering practice.

    For more information, see Reverse Engineering in Object-Oriented Reengineering Patterns.

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

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

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

Upgrade

Workflow

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:

Upgrade Timeline

The upgrade-specific workflow consists of the following issue transitions: To Do > In Progress > Ready for Peer Review > In Peer Review > Done

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.

Upgrading Elastic Path Source Code

  1. Replace the customized source code in version control with the new Elastic Path release version.

  2. Apply all available patches.

    For available patches, see the Changelog.

  3. Update the version of the code if required.

    For more information, see the Branching and Versioning section.

  4. Commit the changes.

Upgrading Database

Liquibase manages upgrading database to newer versions. You must add the upgrade-related data fixes in an XML changelog at extensions/database/ext-data/src/main/resources/schema.

  1. Get a copy of the production database for testing the upgraded schema and data:

    Production Database

  2. Perform sanitization of data.

Sanitization of data is deleting personal information, security credentials, and environment-specific data, such as URLs, IP addresses.

warning

When upgrading database, ensure that database is offline. This causes downtime during the release.

Troubleshooting common data upgrade errors

  1. Delete transient data, such as shopping carts and customer sessions, if it is problematic to migrate.
  2. Enable the Elastic Path database clean-up jobs if disabled.

Extracting customizations

Elastic Path recommends creating a patch file containing the customized code.

  1. To create a path file, port the customizations between two versions by applying the patch to the target version of the source code.

    1. 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, /ep6.7-original, /ep6.7-custom /ep6.14-original, and ep6.14-custom folders.

    2. Remove unwanted files and build artifacts from the source folders.

    3. Break large patches into smaller patches and put them in your issue tracker.

  2. 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.patch

    Following 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.patch

    Replace version number with the current version.

  3. Verify the diff command output by comparing the current and prior diff files each time you modify the arguments.

Re-applying customizations

Elastic Path recommends applying small patches with an IDE(Integrated Development) 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.

Last updated on 5/8/2024
← PreviousConsuming Support Fixes →