Version Components Appropriately

Decisions on semantic version changes should be based on the impact to consuming services. While the version used for a release often seems inconsequential to a single developer, it is a critical communication tool used to set and manage expectations for everyone involved in the release process (other developers, PMs, CM, Operations, V&V, etc.).

For example, if a team consuming a service notices a new major release on a service they use, it serves as a warning that breaking changes will likely occur when they upgrade their existing code. It also informs the PM for the project that the upgrade will likely require additional time and attention to fully understand and address potential issues. This page provides some concrete guidelines for how VA Mobile components should manage their component versions.

As defined by Semantic Versioning, increment the:

  • MAJOR version when you make incompatible API changes,

  • MINOR version when you add functionality in a backwards-compatible manner, and

  • PATCH version when you make backwards-compatible bug fixes.

We consider a "bug fix" to also be inclusive of other low-risk, internal changes such as code refactoring or minor performance optimizations.

Release Scopes

Patch Releases

A patch release is a backward-compatible change in behavior to a service or library. Most importantly, it represents to clients and consumers that the update is a low-risk upgrade. Example changes include simple bug fixes, code cleanup, or other internal refactoring.

Patch Deployment Checklist

  1. pom.xml: Project version should match the version being deployed.

  2. Git Branch: Changes are merged into main and the appropriate release branch. Release branches follow the Release/{major}.{minor} pattern. For example:

    • A patch release would result in version 1.0.1 being checked into the Release/1.0 branch.

    • A new, backward-compatible feature would result in version 1.1.0 being created in a new Release/1.1 branch.

    • A new, breaking set of changes would result in version 2.0.0 being created in a new Release/2.0 branch.

  3. CHANGELOG.md: List what has changed from the past version to the current version.

  4. Kubernetes files should reflect the proper image being deployed.

Minor Releases

A minor release indicates there has been a backwards-compatible introduction of new functionality (new service endpoints or public methods on a library) or significant modification of the behavior or underlying architecture. It indicates a higher-risk upgrade for existing clients and involves additional reviews and approvals from VA leadership.

Minor Release Checklist

In addition to all of the patch release checks above, the following updates should also be made as appropriate:

  1. Merge changes to main and create a new release branch following the Release/{major}.{minor} pattern.

  2. Document any new environment variables.

    • Note that production environment variables (anything not prefixed with DEV_*) must follow semantic versioning — new variables require a minor release, while removing or changing variable names will result in a major version.

  3. Document any new or modified service dependencies.

    • Update the SRVDD document and sequence diagrams with these changes.

  4. Update the Swagger document and/or Javadocs to reflect any new or modified endpoints or public methods.

  5. Update all service and library dependencies.

    • Run mvn versions:display-dependency-updates -DprocessDependencyManagement=false against the project to ensure that any project-specific dependencies have been upgraded to the latest stable version (any specified by the parent image can be ignored).

Major Releases

Major releases indicate breaking changes. Major releases are generally discouraged because they require that we provide support and maintenance for all major releases until clients are able to upgrade (6 months).

Library Release Scope

A library is code that a system runs off of, distributed as a "JAR". These are building blocks — they aren’t something that can stand alone, but rather something that can be used across services and are not unique to any single one. A library must go through the deprecation process if it is no longer going to be used. Libraries and Nexus are the same; the images are different. Libraries don’t need to be built in SQA (only things with an image do), so once a library is built on sandbox, it’s good to go.

  1. CHANGELOG.md: List what has changed from the past version to the current version.

  2. README.md must be present. It must be updated if it is a major or minor release.

  3. Jenkinsfile: The DEPLOY_VERSION parameter matches the pom.xml version.

Service Versioning Rules

Feature Major Minor Patch

Introduce any new public-facing functionality

✓

✓

Make meaningful changes to the Swagger service contract

✓

✓

Add new service or library dependencies

✓

✓

Change or upgrade any dependencies

✓

✓

Add environment variable names (not values)

✓

✓

Refactoring code

✓

✓

✓

Remove/change existing endpoints or environment variables

✓

Performance optimizations

✓

✓

✓

Bug fixes

✓

✓

✓

Make other backward-incompatible behavior changes

✓

Public Java methods have complete Javadocs for any new endpoints

✓

✓

Public Java methods have complete Javadocs for all endpoints

✓

Service endpoints, including paths and query parameters, are specified in the Swagger document, and summary, description, and example fields are included

✓

✓

Deprecated endpoints or environment variables are removed

✓

SRVDD and README are reviewed for accuracy and updated as appropriate

✓

✓

Result in Fortify warnings or new critical/high findings

✓

✓

✓

Library Versioning Rules

Feature Major Minor Patch

Introduce any new public methods

✓

✓

Upgrading, changing, or adding library dependencies

✓

✓

Refactoring code

✓

✓

✓

Remove or change existing public methods

✓

Performance optimizations

✓

✓

✓

Bug fixes

✓

✓

✓

Make other backward-incompatible behavior changes

✓

Public Java methods have complete Javadocs for any new public methods

✓

✓

Public Java methods have complete Javadocs for all public methods

✓

Deprecated public methods are removed

✓

Upgrading Java version

✓

Result in Fortify warnings or new critical/high findings

✓

✓

✓