Skip to main content

Versioning Strategy

1. Introduction​

This document describes the overall approach for managing versions, branches, and configuration transfers within the tSM system. It ensures that core developments, customer-specific implementations, and configuration changes are handled in a systematic, transparent, and controlled manner across development, testing, and production environments.

2. CORE Versioning Strategy​

2.1 Branching Model​

  • 2.2 (Stable):

    • Represents the current stable version used for customer projects.
    • Produces registry.datalite.cz/tsm/tsm-microservice:2.2 docker images.
    • Uses Maven version 2.2.X-SNAPSHOT. X denotes the minor version.

  • main/2.2 (Production):

    • Contains the version deployed to customers.
    • Produces registry.datalite.cz/tsm/tsm-microservice:2.2-main docker images.
    • Uses Maven version 2.2.X-MAIN-SNAPSHOT, reflecting the stable version it was created from.

  • devel/2.2:

    • A dedicated branch for testing and integrating new core features. This branch is used for active development.
    • Produces registry.datalite.cz/tsm/tsm-microservice:2.2-devel docker images.
    • Its Maven version is set to 2.2.X-DEVELOP-SNAPSHOT to denote its development state.

  • feature/TSM-XXX:

    • Feature branches for new functionalities.
    • Merged into devel when features are complete.
    • Usually no direct deployment from these branches, testing is done in devel.

  • bugfix/TSM-XXX:

    • Branches for urgent fixes.
    • Merged directly into stable branch to address immediate issues.

2.2 Maven Versioning​

  • Semantic Versioning:

    • The core uses standard semantic versioning (e.g., 2.2.3).
    • The SNAPSHOT suffix is maven required to be able to update existing version in microsevice architecture with common versioning.

  • Suffix Conventions:

    • no suffix: Indicates the stable branch (2.2) that can be deployed once validated.
    • DEVEL: Used in the active development branch (devel/2.2).
    • MAIN: Used in the production branch (main/2.2), reflecting the version deployed to customers.

3. Versioning of Individual tSM Implementations​

  • Customer-Specific Customizations:

    • Each customer implementation (e.g., CETIN, Nordic) maintains its own versioning, separate from the core.
    • Custom modules reference the core version but carry an additional custom version (e.g., 27.0-SNAPSHOT for CETIN).
    • This allows parallel evolution of the core and the customizations without interference.

  • Build & Deployment Tags:

    • Docker images and other artifacts are tagged to reflect both the core version and the customer-specific customizations.
    • Example: registry.datalite.cz/tsm/tsm-change-management:cetin-2.2 indicates the CETIN customization on the 2.2 branch.

4. Configuration Transfer Process​

4.1 Primary Configuration Repository​

  • TSM-REF, tenant REF-DATA:
    • Holds the primary database for configurations
    • Acts as the single source of truth for baseline system configurations.
    • New projects are created as a copy of this project

4.2 Transfer Procedures​

  • Flyway Scripts for Critical Changes:

    • Insertion of New System Configurations:
      • New configuration entries must be added via a Flyway script using an INSERT command.
    • Modification of Existing Configurations:
      • For updates to system or already-set configurations, a targeted UPDATE script is used.
      • This script will update only the existing values, preserving any intentional customer modifications.

  • Backup/Restore during Feature Merge:

    • When merging features from devel/2.2 into the stable branch, corresponding configuration changes must be transferred to the TSM-REF using a backup/restore process.
    • This ensures that any configuration updates are synchronized with the code changes.

  • Optional Configurations / Default Changes:

    • Changes to optional configurations or defaults (which might be intentionally customized by the customer) cannot be managed solely via Flyway.
    • Instead, an export of these changes is performed via the backup/restore process, accompanied by a detailed change log.
    • The target project can then run the restore and review the differences before applying them.

5. Detailed Process Flow​

5.1 Process Flow Overview​

  1. Feature Development:

    • Developers work on feature branches (e.g., feature/TSM-8946).
    • Upon completion, features are merged into devel/2.2 (version set to 2.2.2-DEVELOP-SNAPSHOT).

  2. Configuration Transfer:

    • Simultaneously with code merge, configuration changes are transferred from the REF-DATA project via backup/restore.
    • If issues arise, Flyway scripts (INSERT or UPDATE) are applied to adjust configurations accordingly.

  3. Testing and Validation:

    • The devel/2.2 branch is thoroughly tested, including both new features and the updated configurations.

  4. Promotion to Stable (2.2):

    • Once validated, changes from devel/2.2 are merged into the stable branch (2.2), which uses Maven version 2.2.2-SNAPSHOT.
    • For selective changes, cherry-picking is employed.

  5. Deployment to Production (main/2.2):

    • The stable branch is then promoted to main/2.2, with Maven version 2.2.2-MAIN-SNAPSHOT.
    • A final configuration backup/restore ensures production environments are up-to-date.

5.2 Flow Diagram​

Below is an illustrative flow diagram of the process:

6. Summary​

  • Core Versioning:

    • Utilizes semantic versioning with specific suffixes to distinguish between development (DEVELOP-SNAPSHOT), stable (SNAPSHOT), and production (MAIN-SNAPSHOT) states.
    • Branching is organized to isolate feature development, stabilization, and production deployments.

  • Customer Implementations:

    • Customizations for each customer (e.g., CETIN) are versioned separately while referencing the core version.
    • This ensures that core and custom developments proceed in parallel without conflict.

  • Configuration Transfer:

    • Primary configurations are maintained in the TSM-REF/REF-DATA project.
    • A combination of backup/restore and Flyway scripts is used to ensure that configuration changes are transferred reliably.
    • Optional configuration changes are exported with detailed change logs for manual review.

  • Process Flow:

    • The entire workflow—from feature development to production deployment—is clearly defined and supported by a detailed diagram.
    • This approach minimizes risks by ensuring controlled transitions between environments.

This consolidated documentation provides a comprehensive view of the tSM system’s versioning, branching, and configuration transfer processes, ensuring clarity and consistency across all stages of development and deployment.