Product versions and release artifacts
A Product Release identifies a complete TSM assembly. Its release manifest lists the exact backend, frontend and configuration artifacts that belong together; its Maven BOM selects the Maven component versions. The release number identifies this assembly, not a requirement to rebuild every component.
For an installation, select a published release and use the individual artifact references in its manifest. For customer extensions, use the release BOM and the exact frontend dependencies. The release notes describe the functional scope of releases.
Version numbers
TSM uses four numbers: generation · feature line · update · patch. For 2.4.10.2, this means generation 2, feature line 4, update 10, patch 2.
| Identity | Example | Meaning |
|---|---|---|
| Product feature line | 2.4 | Development within the same product line. |
| Product update | 2.4.10 | An update being stabilized and maintained. |
| First release of the update | 2.4.10.0 | The first published assembly of update 10. |
| Patch release | 2.4.10.2 | A subsequent published assembly of the same update. |
| Development artifact | 2.4.10-SNAPSHOT | A moving Maven development version, not an installation baseline. |
Changes before publication are part of the candidate being prepared. Changes after publication require another release number. A published release record keeps its original artifact references.
Branching and release creation
Development continues on the feature-line branch, for example 2.4. Preparing an update creates the maintenance branch release/2.4.10. Its Maven components, product parents and BOM use 2.4.10-SNAPSHOT, including the dependencies managed by the snapshot BOM.
A final release freezes the source revisions from that maintenance branch and creates the final source state separately. The immutable Git tag release/2.4.10.2 identifies the final release state; checking out the tag gives a detached HEAD. The maintenance branch stays on 2.4.10-SNAPSHOT for subsequent fixes. Final release sources do not require an additional release materialization branch.
The release compares the selected sources and dependencies with a previous published baseline. Changed build inputs can require a rebuild even when the component's own source did not change. A GENESIS release builds the complete inventory without reuse; UPDATE and HOTFIX releases may reuse compatible published artifacts.
New product parents and the BOM receive the target Product Release version. Newly built Maven components use these final parents and BOM. A reused component retains its original version and original build dependencies. Reuse does not relabel its bytes with the new release number.
Corrections are merged into the maintenance branch and carried into other affected branches. An environment such as TEST or PROD is a deployment target, not a source branch.
One assembly, several artifact versions
The published 2.4.10.2 assembly illustrates selective release creation:
| Artifact | Version or image tag in Product Release 2.4.10.2 | Explanation |
|---|---|---|
| Product BOM and parent family | 2.4.10.2 | Describe and build the new assembly. |
tsm-ticket Maven artifact and backend image | 2.4.10.2 | Newly built ticketing patch. |
tsm-billing Maven artifact and backend image | 2.4.10.1 | Reused from the previous patch. |
tsm-ordering Maven artifact and backend image | 2.4.10.0 | Reused unchanged. |
| Product UI application image | datalite-2.4.1001 | Reused application build. |
| Product UI NPM packages | 2.4.1000 | Reused library publications. |
The complete manifest includes the other components as well. Install each image using its own recorded tag; do not replace every tag with 2.4.10.2.
Product NPM versions have three numbers, with patch = update × 100 + frontend patch, for example UPDATE 2.4.10 with frontend patch 1 produces 2.4.1001. The frontend owns its patch counter within the UPDATE; it does not have to match the Product Release patch. A backend-only release can retain the previous frontend publications. The mapping supports frontend patches 0–99 and does not cause unchanged packages to be republished. Package versions, the UI application image tag and the Product Release version are separate entries in the manifest.
Where to obtain artifacts
| Artifact | Distribution | Customer use |
|---|---|---|
| Product release manifest, release notes and verification information | Release delivery or download location provided by DataLite | Select the complete assembly and inspect its exact references. |
tsm-platform-bom and product parent POMs | Nexus Maven repositories | Build extensions against a published product assembly. |
| Backend libraries, clients and published JARs | Nexus Maven repositories | Compile dependencies or use a supported JAR distribution. |
| Backend and application OCI images | Harbor at registry.datalite.cz | Pull the named release images for deployment. |
| Published UI NPM packages | Nexus NPM repository | Build the customer UI with exact package versions and integrity. |
| Configuration packages and migrations, when included | The artifact locations recorded in the delivery | Install or upgrade the managed configuration and data. |
DataLite supplies the repository URLs, namespaces and read access relevant to the delivery. Development Maven artifacts use snapshot repositories; final artifacts use release repositories. NPM prereleases and moving development image tags serve development and are not final installation references. The release manifest is supplied as a release record; its availability should not be inferred from the existence of a Maven BOM.
OCI references are readable named tags, for example:
registry.datalite.cz/tsm/tsm-ticket:2.4.10.2
registry.datalite.cz/tsm/tsm-ordering:2.4.10.0
registry.datalite.cz/tsm/tsm-ui:datalite-2.4.1001
The manifest also records each image digest. Before installation, verify that the named tag resolves to that digest. Use the named tag in deployment configuration; retain the digest as integrity evidence. When mirroring an image into a customer registry, preserve its content and verify the resulting digest.
How to read the manifest
TsmProductRelease is a YAML release record, not a Kubernetes resource to apply. These are the principal fields:
| Field | Meaning |
|---|---|
metadata.name, spec.version.product | Product Release identity. |
metadata.requestedBy, metadata.requestedAt, metadata.createdAt | Request author, submission time and manifest assembly time. |
spec.version.baseRelease, spec.version.type | Comparison baseline and release policy. |
spec.releaseTag, spec.sources | Exact source identities for reproducing the release. |
spec.maven.bom, spec.maven.parents | Published BOM and parent family for the assembly. |
spec.maven.components | Exact Maven coordinates and original build lineage of each component. |
spec.containers | Backend image repositories, named tags, digests and origins. |
spec.frontend.packages, spec.frontend.apps | Exact NPM dependencies and complete UI application images. |
spec.systemConfig, when present | Configuration artifact and installation baseline information. |
spec.verification | Recorded checks and any explicit exceptions. |
Request metadata identifies who requested the release and when; createdAt records when its manifest was assembled. Timestamps use ISO 8601 with an explicit UTC offset in the Europe/Prague zone. Quote timestamp values in hand-written YAML. Older release records may lack these fields.
This excerpt of 2.4.10.2 shows a new build alongside a reused component. It omits the remaining inventory and verification fields and is not a complete standalone manifest.
spec:
version: {product: "2.4.10.2", baseRelease: "2.4.10.1", type: HOTFIX}
releaseTag: release/2.4.10.2
sourceLine: release/2.4.10
maven:
bom: cz.datalite.tsm:tsm-platform-bom:2.4.10.2
parents:
product: cz.datalite.tsm:tsm-platform-parent:2.4.10.2
service: cz.datalite.tsm:tsm-platform-parent-service:2.4.10.2
lib: cz.datalite.tsm:tsm-platform-parent-lib:2.4.10.2
components:
tsm-ticket:
coordinate: cz.datalite.tsm:tsm-ticket:2.4.10.2
builtWithParent: cz.datalite.tsm:tsm-platform-parent-service:2.4.10.2
dependencyBom: cz.datalite.tsm:tsm-platform-bom:2.4.10.2
tsm-ordering:
coordinate: cz.datalite.tsm:tsm-ordering:2.4.10.0
builtWithParent: cz.datalite.tsm:tsm-platform-parent-service:2.4.10.0
dependencyBom: cz.datalite.tsm:tsm-platform-bom:2.4.10.0
containers:
tsm-ticket:
image: registry.datalite.cz/tsm/tsm-ticket
tag: "2.4.10.2"
digest: "sha256:<recorded-ticket-digest>"
originRelease: "2.4.10.2"
tsm-ordering:
image: registry.datalite.cz/tsm/tsm-ordering
tag: "2.4.10.0"
digest: "sha256:<recorded-ordering-digest>"
originRelease: "2.4.10.0"
Use a Product Release
For a Maven extension, select the published parent appropriate to a library or service and import the Product Release BOM. Let the BOM manage product dependencies instead of assigning the Product Release number to every dependency:
<dependencyManagement>
<dependencies>
<dependency>
<groupId>cz.datalite.tsm</groupId>
<artifactId>tsm-platform-bom</artifactId>
<version>2.4.10.2</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
For a frontend extension, resolve the package versions and integrity from frontend.packages and retain the lockfile. Choosing the Product Release does not mean assigning a calculated version to every NPM package.
For installation:
- Obtain the complete release manifest, installation instructions and required access.
- Select the backend images and the application variant for the environment, using their recorded named tags.
- Verify image digests and package checksums against the delivery.
- Apply the required configuration, migration order and environment parameters. Supply secrets separately.
- Deploy and verify the resulting assembly. Publication alone is not evidence that deployment or all tests succeeded.
Move the accepted artifact set between environments without rebuilding it. A rollback selects a previous complete assembly and also considers data and configuration migration compatibility; changing image tags alone may not reverse a migration.
Recommended customer release flow
A customized installation combines a Product Release with customer backend extensions, a customer UI and customer configuration. We recommend a separate Customer Release identity and a complete customer manifest. Customers can adopt their own naming and implementation while keeping these principles.
Customer identities and development
| Identity | Example | Role |
|---|---|---|
| Integration branch | 2.4 | Ongoing customer development. |
| Customer maintenance branch | release/2026.1 | Stabilization and maintenance of one customer delivery line. |
| Final customer tag | release/2026.1.0 | First immutable delivery of that line. |
| Customer patch tag | release/2026.1.1 | Correction of the same customer delivery line. |
| Fixed product UPDATE | 2.4.10 | Product update selected when the customer line is created. |
| Product Release for one delivery | 2.4.10.2 | Exact published baseline frozen for that delivery. |
CalVer is recommended, not mandatory. A customer may use its own delivery identifiers; the maintenance branch must use that customer line, for example release/RE63, rather than an unrelated internal calendar version.
Here 2026.1.0 means year, delivery sequence and patch. A patch released the following year retains the original delivery line. The customer delivery number and technical component versions are independent of the Product Release number. In a shared UI repository, include the customer namespace in branches and tags, for example release/slovanet/2026.1 and release/slovanet/2026.1.0.
DEV can use 2.4-SNAPSHOT or a selected UPDATE snapshot according to the team. Creating release/2026.1 explicitly fixes UPDATE 2.4.10 and sets the product parent/BOM to 2.4.10-SNAPSHOT. The branch retains that UPDATE snapshot for maintenance, even after a final customer release is published.
Freeze and build a delivery
At the start of each customer release, including patches, select the latest completed Product Release within the fixed UPDATE. The release request may instead select a specific completed patch of that same UPDATE. For example, 2026.1.0 can explicitly choose 2.4.10.2.
Freeze the selected product manifest and checksum, customer source revisions and artifact version reservations once. A retry keeps these inputs even if a newer product patch appears. A new customer request selects the product again and evaluates the impact. Selecting another UPDATE requires an explicit rebaseline and a new impact plan.
Final customer sources are materialized on detached HEAD, with published product parents/BOM and exact dependencies. Final artifacts must not depend on product snapshots. The customer repository owns its build and publication; a separate UI build produces the selected customer application.
The plan decides BUILD, REUSE or explicit removal for each customer component. Reuse retains the original coordinates, image tag, digest and build lineage. Changed resolved dependencies can require a rebuild without a source change. Artifact versions are allocated within each component's namespace; a third-party extension can retain its own version family.
Complete customer manifest
The runtime inventory starts from the selected product assembly. A customer component can replace a product runtime entry or add a service. The customer manifest records the replacement and preserves the product origin. It describes the whole resulting installation, including unchanged product services.
The handover contains:
- Customer identity and previous customer baseline; exact Product Release and manifest checksum.
- Source tags and revisions, build provenance and resolved dependencies.
- Complete Maven/NPM inventory and integrity; OCI repositories, named tags, digests and origins.
- Configuration packages and migrations when included; explicit installation prerequisites and environment templates when available.
- Deployment and verification records, including explicit exceptions.
TsmCustomerRelease is a release document, not a Kubernetes CRD. The manifest contains artifact locations and instructions, while credentials are delivered separately. A downloader can retrieve and verify the exact artifacts from those locations; a delivery does not require a combined ZIP containing all binaries.
A customer may release software without a configuration or database package. The request explicitly selects configurationPolicy: NOT_INCLUDED; the manifest records configuration.status: NOT_INCLUDED, no configuration artifacts and the prerequisite to use the existing target environment configuration. This delivery can be handed over and deployed without changing that configuration or data. It does not provide installation or migration procedures for a new environment. When configuration is required (REQUIRED, also the default for requests without a policy), missing packages remain UNRESOLVED and block promotion. Included packages have verified artifact receipts and status RESOLVED.
Environments and promotion
A new delivery passes through TEST → REF → PROD with the same published artifacts. A correction of a released customer delivery passes through REF → PROD; TEST may already be stabilizing the next delivery. Each patch still freezes its product baseline and publishes a complete manifest.
Verification runs after the relevant artifacts are available, and deployment-dependent checks run against the final assembly. An explicitly accepted test exception records the author, reason and original result; it does not turn a failed test into a successful one. Missing software artifacts or unresolved required installation inputs cannot be represented as a complete delivery. A declared software-only scope does not waive verification.
The customer can install through its own deployment tooling using direct read access to the supplied registries, or mirror the artifacts without rebuilding them. Use the named image tags from the customer manifest and verify their digests. Installing or promoting the delivery does not require access to the release producer's source repositories or control application.