Product versioning, releases and artifacts

A product release identifies one tested combination of TSM artifacts. Its version is shared by the release manifest and the Maven BOM. Individual components keep their own physical artifact versions: product release 2.4.3.1 can contain tsm-ticket:2.4.3.1 and an unchanged tsm-ordering:2.4.3.0.

A platform is the complete deployment, including customer extensions, configuration and infrastructure such as PostgreSQL and Kafka. It is not another name for a product release. Existing technical identifiers such as tsm-platform-bom, tsm-platform-parent and tsm-platform-parent-aggregator remain unchanged.

Release contract and rollout

This chapter defines the target release contract for TSM 2.4 and 2.5. Adoption in repositories, registries and pipelines is tracked in TSM-4335. Publishing this documentation does not mean that every existing pipeline already implements it. Previously published artifacts retain their identities; do not reinterpret legacy versions or overwrite them during migration.

Open full-size diagram · Download editable Excalidraw source

What the four numbers mean

2 . 4 . 3 . 1
│   │   │   └─ hotfix of an already released update
│   │   └───── update: compatible features and fixes
│   └───────── feature line
└───────────── product generation

Version	Meaning
2.4.0.0	Initial release of feature line 2.4.
2.4.3.0	Update 3 of feature line 2.4.
2.4.3.1	First corrective assembly of Update 3. No new product feature.
2.4.3.15	Corrective assembly 15, not a requirement that every component has patch 15.
2.4.4.0	Next update, which may include compatible new functionality.
2.5.0.0	Next feature line, with a planned upgrade and compatibility assessment.

This is a TSM four-part scheme, not Semantic Versioning. Release notes can display “TSM 2.4 — Update 3, corrective assembly 15” alongside technical version 2.4.3.15. Do not introduce a second BF15 or timestamp identity for the product release. Timestamps and CI IDs describe build events.

An issue found before the first final Update 3 release remains part of stabilization. A fix after 2.4.3.0 has been released creates 2.4.3.1. A new feature after that update is closed belongs to the next update, not to its hotfix counter. Release frequency and support commitments are separate from the numbering scheme.

Assembly version versus component version

This example assumes only the ticketing implementation changed and its dependency analysis requires no other component rebuild.

Artifact	Product release 2.4.3.0	Product release 2.4.3.1
Product manifest / tsm-platform-bom	2.4.3.0	2.4.3.1 — new assembly
tsm-ticket JAR and OCI image	2.4.3.0	2.4.3.1 — changed
tsm-ordering JAR and OCI image	2.4.3.0	2.4.3.0 — reused
tsm-commons library	2.4.3.0	2.4.3.0 — reused
Product UI OCI image	2.4.3.0	2.4.3.0 — reused
Product UI NPM package	2.4.300	2.4.300 — reused
System configuration ZIP	2.4.3.0	2.4.3.0 — reused

Only changed physical artifacts receive the current release version. Reused artifacts keep the same version, checksum and digest; they are neither rebuilt nor retagged with a new component version. The manifest and BOM are always new because they describe a new combination. The same reuse rule applies when releasing a new product update such as 2.4.4.0.

“Changed” includes changes to dependencies, build parents, plugins, base images and packaged configuration. A shared-library fix may require rebuilding several services even if their own source files have not changed. The pipeline derives and verifies this dependency impact against baseRelease; a manually entered list of repositories is insufficient. A temporarily inseparable Maven reactor group must be recorded as one release unit until it can be split.

Git branches and exact source identity

Git reference	Purpose	Maven during development	OCI convenience tag
2.4	Ongoing development of the feature line	2.4-SNAPSHOT	2.4
release/2.4.3	Stabilize Update 3; maintain its released baseline	2.4.3-SNAPSHOT	2.4.3
release/2.4.4	Stabilize the next update independently	2.4.4-SNAPSHOT	2.4.4
product/2.4.3.1	Protected final tag in every participating repository	Exact versions from the manifest	Exact component versions

The same rules apply to 2.5 and release/2.5.0. Feature branches merge into their target development line. Short-lived bugfix branches use the affected supported release baseline. For a production incident, first identify the deployed manifest and its exact source commit; do not accidentally include unrelated later work. Bring the fix into the supported release branch and forward-port it to every affected later update/line.

Snapshot branches keep their SNAPSHOT versions. At freeze, the orchestrator records developmentRevision, creates a detached release materialization commit with final versions for changed artifacts, and records it as releaseRevision. This commit is retained by the product tag; it does not move the long-lived snapshot branch. For an unchanged repository, reuse the previous release commit.

Every participating source repository has the same tag name, for example product/2.4.3.1. Multiple product tags may point to the same commit in an unchanged repository. Creating such a tag must not trigger another component build or publication. In a multi-module repository, source membership and the list of artifacts to publish are separate concerns.

To reconstruct the source workspace, load the repository list from the manifest, check out that product tag in each repository and verify its commit against releaseRevision. A missing tag or mismatch blocks checkout; there is no fallback to a default branch. Git cannot publish tags atomically across repositories: retries must accept an existing tag only when it points to the expected commit, and must never move it. The central release record is published as complete only after all source tags and artifact references have been verified.

Maven: BOM, parent and runtime artifact

A service can expose a library JAR for extensions and a separately packaged runtime artifact/OCI image. The manifest identifies the exact coordinates, packaging and classifiers of the artifacts actually published; do not infer a runtime coordinate from the image tag.

The product BOM cz.datalite.tsm:tsm-platform-bom:2.4.3.1 declares the real Maven versions in the assembly. Consumers import it and do not substitute the BOM version into every dependency:

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>cz.datalite.tsm</groupId>
      <artifactId>tsm-platform-bom</artifactId>
      <version>2.4.3.1</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>
<dependencies>
  <dependency>
    <groupId>cz.datalite.tsm</groupId>
    <artifactId>tsm-ordering</artifactId>
  </dependency>
</dependencies>

Here the resolved ordering version is 2.4.3.0. A BOM and the dependencies it manages need not have equal versions; see Maven BOMs.

Separate component version, build parent version and dependency BOM version. For example, ticket 2.4.3.1 can be built using a previously released parent and dependency BOM 2.4.3.0. The resulting release BOM 2.4.3.1 then describes the new assembly. Record the actual parent and dependency baseline for each artifact, including reused components.

An existing parent that imports the BOM using ${project.version} is still coupled to that BOM. While that coupling remains, changing the BOM reference changes the parent artifact too, and the parent must be versioned and recorded accordingly. Decoupling the parent and ensuring resolved versions survive in published POMs is a rollout prerequisite, not a reason to silently reuse a modified parent under an old version.

Registries, UI and immutable artifacts

The Maven/NPM/configuration artifact repository (Nexus or the configured Artifactory instance) stores libraries, POMs, configuration ZIPs and release records. Harbor stores OCI images and scan results. These stores contain both development artifacts and released artifacts with distinct write/retention policies.

Artifact	Development example	Final example
Maven library	tsm-ticket:2.4.3-SNAPSHOT	tsm-ticket:2.4.3.1
Backend OCI	tsm-ticket:2.4.3	tsm-ticket:2.4.3.1
Product UI OCI	tsm-ui:2.4.3	tsm-ui:2.4.3.1 if UI changed
NPM package	Unique 2.4.300-dev.842	2.4.301 if that library changed
System configuration	Snapshot build with commit/checksum	tsm-system-config-2.4.3.0.zip if reused

Development OCI convenience tags can move; every physical build remains traceable through commit, CI ID and digest. Final Maven/NPM/ZIP versions and four-part OCI tags are immutable. Configure Harbor tag immutability and release repository permissions accordingly. Security gates evaluate the exact image digest; a later vulnerability database update can change the scan result without changing the image.

Product UI follows the same four-part OCI numbering as the backend. Only NPM requires the three-part representation used here:

npmPatch = update * 100 + hotfix
2.4.3.0  → 2.4.300
2.4.3.1  → 2.4.301
2.4.3.99 → 2.4.399
2.4.4.0  → 2.4.400

For this mapping, hotfix must be in 0..99; reject overflow and collisions rather than silently publishing an ambiguous version. Development NPM publications use unique prerelease identifiers; a mutable OCI tag does not authorize republishing an NPM version. Record both representations and lock exact dependencies. This encoding does not make the TSM compatibility policy equivalent to SemVer: do not rely on a broad NPM range as a compatibility guarantee.

The product release manifest

The immutable manifest is the authoritative complete inventory, including source revisions, Maven artifacts, parents/BOMs, NPM packages and integrity, OCI images and digests, configuration packages and checksums, build receipts, compatibility requirements, migrations and verification evidence. changedComponents is a difference against baseRelease, not a deployment inventory.

The following is an illustrative excerpt, not a deployable inventory or a finalized schema. Placeholder hashes must be replaced and all product components included in a real release. The manifest's checksum belongs in an external receipt/sidecar, avoiding a self-referential hash.

apiVersion: release.tsm.datalite.cz/v1alpha1
kind: TsmProductRelease
metadata:
  name: "2.4.3.1"
spec:
  version:
    product: "2.4.3.1"
    baseRelease: "2.4.3.0"
    type: HOTFIX
  changedComponents: [tsm-ticket]
  sources:
    productTag: product/2.4.3.1
    tsm-ticket:
      developmentRevision: "<frozen-snapshot-commit>"
      releaseRevision: "<final-version-commit>"
    tsm-ordering:
      releaseRevision: "<reused-release-commit>"
  maven:
    bom: cz.datalite.tsm:tsm-platform-bom:2.4.3.1
    components:
      tsm-ticket:
        coordinate: cz.datalite.tsm:tsm-ticket:2.4.3.1
        checksum: "sha256:<jar-checksum>"
        builtWithParent: cz.datalite.tsm:tsm-platform-parent-service:2.4.3.0
        dependencyBom: cz.datalite.tsm:tsm-platform-bom:2.4.3.0
      tsm-ordering:
        coordinate: cz.datalite.tsm:tsm-ordering:2.4.3.0
        checksum: "sha256:<unchanged-jar-checksum>"
        builtWithParent: cz.datalite.tsm:tsm-platform-parent-service:2.4.3.0
        dependencyBom: cz.datalite.tsm:tsm-platform-bom:2.4.3.0
  containers:
    tsm-ticket:
      image: registry.datalite.cz/tsm/tsm-ticket
      tag: "2.4.3.1"
      digest: "sha256:<new-ticket-digest>"
    tsm-ordering:
      image: registry.datalite.cz/tsm/tsm-ordering
      tag: "2.4.3.0"
      digest: "sha256:<unchanged-ordering-digest>"
    tsm-ui:
      image: registry.datalite.cz/tsm/tsm-ui
      tag: "2.4.3.0"
      digest: "sha256:<unchanged-ui-digest>"
  frontend:
    packages:
      tsm-framework:
        version: "2.4.300"
        integrity: "sha512-<package-integrity>"
  configuration:
    package: tsm-system-config-2.4.3.0.zip
    checksum: "sha256:<unchanged-config-checksum>"
  verification:
    integrationTests: "<report-uri-and-checksum>"
    securityScans: "<reports-for-exact-image-digests>"

The validator checks that every changed component has new immutable artifacts, every reused component matches its previous references, and the inventory agrees with the BOM and build receipts. A newly introduced or retired component is an explicit inventory change. Snapshots, unresolved references, missing checksums and unverified combinations block final publication.

From development to an installed release

1. Develop and stabilize. Branch builds use traceable snapshots in development/update validation environments. Product REF is reserved for released product assemblies.
2. Freeze and plan. Lock the release number, freeze all source/build inputs, compare against the previous manifest and compute the affected dependency closure.
3. Materialize and build. Create final-version source commits and build only changed artifacts into staging. Reuse existing immutable artifacts directly. Generate the candidate BOM and full inventory.
4. Verify the final combination. Test the actual final artifacts together, including integration, smoke, API/event compatibility, migrations and security gates. Passing tests on a preceding snapshot alone is insufficient.
5. Publish and complete. Publish verified new artifacts/BOM, verify all protected product tags and their exact revisions, then publish the complete manifest as the final release commit point. A partial run is not an available product release. Resume idempotently without overwriting existing content.
6. Promote and observe. Product REF and downstream delivery pipelines consume that released inventory. Record desired manifest, actual image digests and installed configuration package state. Promote the same verified product artifacts; do not rebuild them for each environment.

A regular deployment can use an immutable reference such as registry.datalite.cz/tsm/tsm-ticket:2.4.3.1. The manifest records its digest, and the deployment check verifies the registry and running image against that digest. A tag alone is not sufficient evidence of the actual installed state.

A failed final build before publication remains a staging attempt. Once an artifact version is published, any content correction requires a new version. Failed attempts and partially published artifacts must be accounted for by the release ledger; never delete/move final tags to make a retry succeed.

Configuration, customer extensions and upgrades

Product system configuration is a versioned baseline from tsm-system-config, validated with the clean product. Its packages contain managed TSM configuration, not credentials, customer business data or infrastructure provisioning. A customer clone records its product baseline and its own changes; upgrades must reconcile both rather than overwrite customer configuration with a new vanilla export.

The release inventory always identifies the complete desired configuration package set. Full ZIP versus a derived delta installation package remains a rollout decision. A full managed-scope package is the recommended authority; an optional delta must identify exact base/target packages, explicit deletions, ordered migrations and drift checks. It must not be inferred from an uncontrolled comparison of live environments.

A customer extension records its own artifact version and the exact product BOM/libraries used to build it. For example, a customized ticket service can combine product tsm-ticket:2.4.3.1 and customer code in one runtime artifact. A customer delivery manifest references the immutable product manifest and its own artifacts; customer batch naming and combined customer UI builds are governed by the customer's delivery process.

Upgrades verify runtime contracts, shared libraries, event schemas, database migrations, running processes and configuration scope. An independently released component is not automatically compatible with every deployment. Rollback must account for data/schema and configuration migrations, backups and forward recovery; reverting an OCI tag alone is not a rollback plan.

During adoption, inventory current published versions and freeze a verified legacy baseline first. Move branch/tag parsing, BOM/parent separation and release validation to the new contract before the first four-part release. Keep legacy release identities resolvable. Supported update lines, backport windows and customer rollout dates require explicit release/support policy; they cannot be inferred from a version number.