Branch and Version Number Convention

Branching and Versioning

Version Number Conventions

The following conventions are recommended for versioning customer projects:

Best practices

• Do not reversion development branch on each release

  Updating the development branch version number on each release is additional work, adds noise to the commit history, and provides marginal value.

  It is more effective to update version number only on release branches and to use the same development version throughout the project.

• Update versions numbers only on the release branch

  Update versions numbers on the release branch immediately after it is created. This will distinguish release artifacts from development artifacts. Do not merge version number changes back into development

Recommended versions for development branch

Extensions

• Version Convention: 0.0.0-SNAPSHOT
• Maven Example: 0.0.0-SNAPSHOT
• OSGi Example: 0.0.0.qualifier

Core Commerce & Commerce Manager

• Version Convention: <productMajorVersion><productMinorVersion>.<productBuildNumber>.0-SNAPSHOT
• Maven Example: 703.0.0-SNAPSHOT
• OSGi Example: 703.0.0.qualifier

Recommended versions for release branch

It is possible to release using either SNAPSHOT or release versions. It is easier to use SNAPSHOT versions, but this may not be acceptable for all clients.

Extensions and Cortex Resources

• Version Convention: <extensionMajorVersion>.<extensionMinorVersion>.[<extensionBuild>]
• Maven Example:
  • 1.0.1
  • 1.0.1-SNAPSHOT
• OSGi Example:
  • 1.0.1
  • 1.0.1-qualifier

Core Commerce, Commerce Manager, & Commerce Data

• Version Convention: <productMajorVersion><productMinorVersion>.<productBuildNumber>.<extensionVersionRepresentation>
• Maven Example:
  • 703.0.101
  • 703.0.101-SNAPSHOT
• OSGi Example:
  • 703.0.101
  • 703.0.101-qualifier

note

Project teams may adopt variations on the above scheme for versioning extension projects. The key principal is that the <extensionVersionRepresentation> element should clearly represent the extension project version.

The normal practice is to reversion the Core Commerce and Commerce Manager whenever the Extension project is reversioned. The versioning scheme should make it easy to correlate these project versions.

The rationale behind the product versioning convention is:

• OSGi restricts us to a maximum of three numeric version elements, plus a suffix. Note that SNAPSHOT versions have a suffix of .qualifier
• The first two version elements are reserved for product use to identify the product version and build
• The final element is available for customer projects

Updating Version Numbers

Elastic Path provides a script to re-version all Elastic Path Commerce code.

tip

On Windows, use either Git Bash, MinGW, or Cygwin to run the script.

Assumptions

The examples on this page make the following assumptions:

• Module directories have the same names as ones provided in source release packages
• The development branch is checked out
• The projects are being reversioned to SNAPSHOT versions for development as recommeneded in branching and versioning

Versioning Elastic Path Commerce Modules

This script re-versions all Elastic Path Commerce modules.

Example:

cd <modules-parent-folder>
./devops/scripts/set-ep-versions.sh 703.0.0-SNAPSHOT 0.0.0-SNAPSHOT

Usage:

Set the version for Elastic Path Commerce modules.

Usage: set-ep-versions.sh [OPTIONS] PLATFORM_VERSION EXTENSION_VERSION

OPTIONS:
    -b, --build                  Build modules upon completing the versioning.
                                 The 'skipAllTests' property is set to speed up build.
    -s, --maven-settings FILE    Alternative path for Maven settings.xml to use.
    -h, --help                   Print this help.