📘 TSM Versioning, Branching & Artifact Strategy

This document defines the rules for source control branching, Maven artifact versioning, and Docker image tagging. It specifically addresses the need to support multiple parallel platform lines (e.g. 2.3, 2.4, 3.x), multi-customer installations, microservice architecture with shared libraries and extendable core services, and stabilization phases (DEV, REF, PROD).

Overview:

Branch	Lifecycle Stage	Stability	Maven Version	Docker Tag
2.3	DEV (Daily Work)	Volatile 🚧	2.3-SNAPSHOT	:2.3
release/2.3	REF (Staging/QA)	Stable 🛡️	2.3-REL-SNAPSHOT	:2.3-latest
tag 2.3.5	PROD (Release)	Frozen ❄️	2.3.5	:2.3.5

---

1. Core Concepts

We distinguish between two main types of output from our builds:

1. Library Artifacts (The "SDK"):

   • Standard Java JARs (non-executable).
   • Used as dependencies in other microservices or customer extensions.
   • Example: tsm-commons, tsm-ordering (core logic).

2. Deployment Artifacts (The "Runtime"):

   • Fat JARs: Spring Boot executable JARs (often including specific DB drivers, e.g., Postgres).
   • Docker Images: The final runnable unit in Kubernetes.
   • Example: tsm-ordering-postgres, kip-ordering (custom).

---

2. Branching & Environment Mapping

2.1 Long-living branches

These represent version lines (each line evolves independently):

• 2.3 – active development of 2.3.x
• 2.4 – active development of 2.4.x
• 3.x – next major with breaking changes

We use three distinct "states" for our artifacts, mapped to Git branches:

State	Git Branch	Purpose	Stability
DEV	2.3	Active development of features.	Volatile (SNAPSHOT)
REF	release/2.3	Stabilization, QA, Pre-release.	Stable Snapshot
REL	Tag 2.3.5	Production release.	Immutable (Fixed)

Releases are always created from a release branch and tagged, e.g.:

• 2.3.0, 2.3.1, 2.3.5, …
• optional bugfix releases: 2.3.5.1, 2.3.5.2, …

2.2 Feature branches

Feature branches target a specific line:

feature/2.3/TSM-4954_new-report
feature/2.4/TSM-5852_payment-refactor
feature/3.x/TSM-6846_new-architecture

They merge back into their corresponding dev branch (2.3, 2.4, 3.x).

2.3 Bugfix branches

Urgent production fixes always branch from the relevant release branch:

bugfix/2.3/101-login-npe

Flow:

1. Branch from release/2.3
2. Implement fix, test
3. Merge back to release/2.3
4. Tag new patch release (e.g. 2.3.5, 2.3.5.1)
5. Merge/cherry-pick into higher lines (2.3, 2.4, 3.x) where applicable

This ensures consistency across versions while keeping each line stable.

---

3. Artifact Matrix (The "What Goes Where")

This table defines exactly what artifacts are generated in Nexus and Harbor for the 2.3 version line.

📦 Nexus Artifacts: Libraries (For Compilation/Extension)

These are plain JARs. Used when projects need to compile their own extension against TSM.

Component	Git Source	Maven Version	Purpose
tsm-commons	2.3	2.3-SNAPSHOT	Daily dev builds.
tsm-commons	release/2.3	2.3-REL-SNAPSHOT	Stabilized library for testing extensions.
tsm-commons	Tag 2.3.5	2.3.5	Fixed Release. Used in prod BOMs.
tsm-ordering	2.3	2.3-SNAPSHOT	Core logic library for dev.
tsm-ordering	release/2.3	2.3-REL-SNAPSHOT	Core logic library for QA/REF.
tsm-ordering	Tag 2.3.5	2.3.5	Fixed Release. Base for customer extension.

---

🚀 Nexus Artifacts: Fat JARs (Executables)

These are Spring Boot executables containing the embedded container and specific drivers (e.g., Postgres).

Component	Git Source	Maven Version (Classifier/Var)	Purpose
tsm-ordering	release/2.3	postgres-2.3-REL	REF Candidate. Ready for generic staging.
tsm-ordering	Tag 2.3.5	postgres-2.3.5	Core Production. Generic release for Postgres.
kip-ordering	Tag 2.3.5	postgres-2.3.5	Customer Production. Extended version (KIP) based on TSM 2.3.5.

> Note on Naming: The version suffix (e.g., postgres-2.3.5) denotes that this artifact is built specifically for the PostgreSQL profile/driver.

---

🐳 Docker Images (Harbor)

The final runtime units deployed to Kubernetes.

Image Name	Source	Tag	Environment
tsm/tsm-ordering	2.3	2.3	DEV (Rolling update)
tsm/tsm-ordering	release/2.3	2.3-latest	REF (Stabilization / Latest RC)
tsm/tsm-ordering	Tag 2.3.5	2.3.5	PROD (Immutable)
kip/kip-ordering	Tag 2.3.5*	2.3.5	PROD (Customer Specific)

*> Built from the customer repository, consuming tsm-ordering:2.3.5 library.

---

4. The Extension Workflow (Core vs. Custom)

This section explains how tsm-ordering (Core) and kip-ordering (Customer project KIP) coexist.

A. The Core Library (tsm-ordering)

We build tsm-ordering as a Library first. This jar contains all services, entities, and logic, but no SpringApplication.run() entry point (disabled by customized spring profile).

1. Input: git checkout release/2.3
2. Output: tsm-ordering-2.3-REL-SNAPSHOT.jar (Nexus)

B. The Core Executable

We wrap the library into a runnable server for clients who don't need Java customization.

1. Input: tsm-ordering library + Postgres Driver + Default Config.
2. Output: tsm-ordering:postgres-2.3-REL (Fat JAR) -> Docker tsm/tsm-ordering:2.3-latest.

C. The Customer Extension (kip-ordering)

The customer needs custom logic. They have their own repo.

1. Dependency: They depend on tsm-ordering:2.3.5 (a fixed library).
2. Code: They override specific Beans or add new Controllers.
3. Output: kip-ordering:postgres-2.3.5 (Fat JAR) -> Docker kip/kip-ordering:2.3.5.

---

5. Release Process Summary

Scenario: Stabilizing Version 2.3.5

1. Code Freeze: Developers stop merging to release/2.3.
2. Build REF: CI builds tsm-ordering:2.3-REL-SNAPSHOT (Lib) and tsm-ordering:postgres-2.3-REL (Fat JAR).
3. Deploy to REF: Docker image 2.3-latest is deployed to REF environment.
4. Verification: QA approves the build.
5. Tagging: Release Manager creates tag 2.3.5.
6. Build REL:
   • Maven builds tsm-ordering:2.3.5 (Lib).
   • Maven builds tsm-ordering:postgres-2.3.5 (Fat JAR).
   • Docker builds tsm/tsm-ordering:2.3.5.
7. Customer Build:
   • Customer repo triggers build.
   • Pulls tsm-ordering:2.3.5 (Lib).
   • Produces kip-ordering:postgres-2.3.5.

---

6. Visual Overview

7. BOM Reference

🧩 tsm-platform BOM

Artifact (example naming):

cz.datalite.tsm:tsm-platform-bom

The BOM follows exactly the same branching and release model as the platform itself.

🔁 BOM version mapping

For version line 2.3:

Git location	Purpose	BOM version
branch 2.3	main development	2.3-SNAPSHOT
branch release/2.3	stabilization / pre-release	2.3-REL-SNAPSHOT
tag 2.3.5	concrete released platform	2.3.5

Inside the BOM for 2.3.5:

• most artifacts will be 2.3.5
• some may be patched versions, e.g. 2.3.5.1, 2.3.5.2 (the BOM is the single source of truth which actual artifact versions belong to platform version 2.3.5)

💡 Example BOM usage in a service

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>cz.datalite.tsm</groupId>
            <artifactId>tsm-platform-bom</artifactId>
            <version>2.3-SNAPSHOT</version> <!-- or 2.3-REL-SNAPSHOT / 2.3.5 -->
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>cz.datalite.tsm</groupId>
        <artifactId>tsm-commons</artifactId>
    </dependency>
    <dependency>
        <groupId>cz.datalite.tsm</groupId>
        <artifactId>tsm-commons-kafka</artifactId>
    </dependency>
    <dependency>
        <groupId>cz.datalite.tsm</groupId>
        <artifactId>tsm-client-core</artifactId>
    </dependency>
</dependencies>

No versions on individual dependencies – everything comes from the BOM.

---