Skip to content

ADR 7: Use JHA Version Standard

Status

Proposed

Context

We are currently using multiple versioning patterns in PayCenter. To align as a BU, we should adopt a pattern based on the JHA version standard as seen here and here.

Challenges

Team SDLC differences

Each team may have a different release/branching pattern that may affect numbering. For example, Blue ties releases to the sprint iteration, RTP ties it to the month:

Example

  • Blue: 2024.96.0.888 // where 96 is the sprint
  • RTP: 2024.01.18.01-1 // where 01 is the month

PayCenter Suite version

There is a desire to have a PayCenter Suite version that represents the overall version of a product. To accomplish this, the primary identifiers will be the year and month.

Example

  • PC Suite version - 2024.10.1.1
    • Zelle Suite - 2024.10.1.1
      • PCS Service - 2024.10.1.1.777 - Oct release
      • PCS Service - 2024.10.1.1.790 - Hotfix during month
      • PCS Service - 2024.10.1.2.840 - Oct 15th release (not currently done)
      • Zelle WSO2 - 2024.10.1.1.455 - Oct release
      • Zelle WSO2 - 2024.10.1.1.570 - Hotfix during month
    • Portal Suite - 2024.10.1.1
      • Zelle API - 2024.10.1.117 - Oct release
      • Zelle API - 2024.10.1.119 - Hotfix during month

In this example, the PayCenter Suite version remains 2024.10.1.1 until the November release. If PayCenter starts adopting an intra-month release cadence, the Patch value would increment.

Decision

PayCenter will implement the JHA standard with the following differences:

  • Point is the current month.
  • Build is an optional element to represent a CI build.
JHA Element Year Point Compat Patch
PayCenter Element Year Month Compat Patch Build
Example 2024 10 1 1 555

PayCenter Version Standard Elements

█ Year: Represents the year of the build or release.

  • For CI builds, this value is typically calculated from the current date.
  • For release builds, this value is typically determined by the release branch.

█ Point: Represents the month of build or release.

  • For CI builds, this value is typically calculated from the current date.
  • For release builds, this value is typically determined by the release branch.

█ Compatibility: Starts with a value of 1. Incremented when breaking changes are included in a product release.

  • This will generally stay with a value of 1 until we need to communicate breaking changes.
    • One example could be if we start providing client libraries.

█ Patch: Indicates a new release of software. Never used to determine compatibility.

Increment as needed to represent a unique (non-hf) release.

Example

  • 2024.10.1.1.444 - Oct release
  • 2024.10.1.1.477 - Oct hotfix
  • 2024.11.1.1.534 - Nov release
  • 2024.11.1.1.579 - Nov hotfix

Note

Hotfixes generally do not change this value as they apply to an existing release.

To support intra-month releases or facilitate release flow, the value could be incremented each full release and based on something in CI (sprint).

Example

  • 2024.10.1.33.444 - Oct release
  • 2024.10.1.33.477 - Oct hotfix
  • 2024.11.1.34.534 - Nov release
  • 2024.11.1.34.579 - Nov hotfix

█ Build: Indicates a new build of software. Optional.

  • For most teams, this is the build id from the CI system.

Consequences

Positive outcomes

  • Provides a consistent version system among PayCenter products.
  • Maps to product and BU-level PayCenter Suite concept to provide an aggregate version.
  • Allows a PayCenter product to communicate compatibility.1
  • Conforms with the JHA standard.

Drawbacks

  • Two elements are dedicated to the date.
  • We cannot utilize the Point element to notate intra-month deployments.
    • This is not an issue right now, but will be for projects with greater deployment frequency.
    • To alleviate this, the optional JHA Patch element is required for the PayCenter pattern.

Reference

JHA Version Standard Elements

image.png

█ Year: The year the product version is released. Very useful for large or strategic campaigns/releases. Never used for compatibility determination or identifying breaking changes.

█ Point: Includes new or updated feature/function, bug fixes. The point increment always begins at 0 within a year increment change.

█ Compatibility: Ever increasing value from this point forward. Incremented when breaking changes are included in a product release.

█ Patch/Build: Indicates a new build of software. Normally for small (optional) bug fixes. The build indicator always begins at 0. May not be used by all products and assumed 0 if omitted. Never used to determine compatibility

This is semver for comparison:

Given a version number MAJOR.MINOR.PATCH, increment the:

MAJOR version when you make incompatible API changes MINOR version when you add functionality in a backward compatible manner PATCH version when you make backward compatible bug fixes Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

The JHA pattern appears to be based on semver with this mapping:

  • Year = just the year
  • Point = MINOR
  • Compat = MAJOR
  • Patch = PATCH

  1. From JHA standards:

    Customers can look at the compatibility version of a product to determine if there is potential integration at risk indicated by an increased compatibility number.

    Products taking a dependency upon or integration with other JHA products can look to the compatibility number to know if integration certification or re-certification is warranted before delivering/releasing software products to customers.

    ↩