Skip to content

VERSIONING.md

Latest commit

 

History

History
260 lines (178 loc) · 10.6 KB

VERSIONING.md

File metadata and controls

260 lines (178 loc) · 10.6 KB
Raw

ThemisDB — Versioning Policy

Status: Active
Applies to: All ThemisDB editions (MINIMAL, COMMUNITY, ENTERPRISE, MILITARY, HYPERSCALER)

This document defines the versioning scheme, release cadence, and support lifecycle for ThemisDB.

Table of Contents

  1. Version Format
  2. Version Identifiers in the Repository
  3. Release Types
  4. Release Cadence
  5. Supported Versions & End-of-Life
  6. Edition Versioning
  7. Changelog Requirements
  8. Deprecation Policy
  9. Breaking Changes
  10. Pre-release Identifiers

1. Version Format

ThemisDB follows Semantic Versioning 2.0.0:

MAJOR.MINOR.PATCH[-PRE_RELEASE]

Examples:
  2.6.0
  2.6.0-rc1
  2.7.0-alpha1
  2.7.0-beta1
Segment Incremented when
MAJOR Incompatible API or wire-protocol changes
MINOR New backward-compatible functionality
PATCH Backward-compatible bug fixes and security patches
PRE_RELEASE Pre-release qualifier (see §10)

Rule: PATCH resets to 0 on a MINOR bump; MINOR resets to 0 on a MAJOR bump.

2. Version Identifiers in the Repository

The canonical version is stored in two places that must always be kept in sync:

File Format Example
VERSION Plain text, one line <major>.<minor>.<patch>[-pre]
CHANGELOG.md Keep a Changelog header ## [<major>.<minor>.<patch>] - YYYY-MM-DD

Additionally, the CMake build system reads the version at configure time via the VERSION file and from CMakeLists.txt project() call. Keep these consistent.

The RELEASE_TYPE file contains the current release type string (e.g., stable, rc, beta). For GA governance claims, VERSION/RELEASE_TYPE must be interpreted together with the active promotion evidence state (including Section 9 sign-off in docs/governance/GA_PROMOTION_SIGN_OFF.md).

2.1 Pull Request Version Targeting

Every PR must declare a target version at merge time. This maps the PR to a GitHub milestone and enables:

  • Release scope tracking: milestone aggregates all PRs targeting a release
  • Changelog generation: PR titles/numbers are recorded in CHANGELOG.md
  • Roadmap alignment: PR scope is validated against planned features in ROADMAP.md

PR Version Selection:

PR Type Target Version Example
New feature Next planned MINOR v2.5.0-alpha1 for feature work on develop
Bug fix (current RC/stable) Current release or patch v<current-rc> or v<current-stable-patch>
Bug fix (general) Next MINOR v2.5.0-alpha1
Documentation Feature version Same as documented feature
Security patch Current stable first v<current-stable> then backport to v<current-stable-patch>
Infrastructure / Refactoring Next MINOR or backlog v2.5.0-alpha1 or [Unreleased]

See docs/governance/PR_VERSION_TARGETING.md for detailed selection criteria and release manager workflow.

3. Release Types

Type Description Example tag
Alpha Early preview; API may change significantly v2.5.0-alpha1
Beta Feature-complete; API stabilising v2.5.0-beta1
Release Candidate (RC) Feature-frozen; only bug fixes vX.Y.Z-rcN
Stable General availability (GA) vX.Y.Z
Patch / Hotfix Critical fixes on a stable release vX.Y.(Z+1)

Releases progress through the type sequence: alpha → beta → rc → stable.
Critical security fixes may bypass the pre-release sequence and be released directly as a patch.

RELEASE_TYPE values are normalized to: alpha, beta, rc, stable.

Canonical suffixes:

RELEASE_TYPE Canonical suffix Legacy suffixes (historical entries only)
alpha -alphaN -alpha
beta -betaN -beta.N
rc -rcN -rc.N, -rc
stable (none) n/a

3.1 Stable / GA Promotion Evidence

A stable / GA tag may only be cut after the release-policy gates in RELEASE_STRATEGY.md are satisfied on develop.

Required evidence bundle:

  • Wave 7 PASS on the current baseline
  • green release_critical CI on develop
  • no new CRITICAL findings in server, llm, and sharding
  • required sanitizer, recovery, chaos/fault-injection, penetration-test, SLA, and runbook artefacts
  • synchronized release/governance documentation (ROADMAP.md, FUTURE_ENHANCEMENTS.md, CHANGELOG.md, branch/release/versioning docs)
  • completed GA hardening execution batches (A-D) with boundary evidence updates in planning/status documents

Current batch tracking is maintained in ROADMAP.md, NEXT_PHASE_IMPLEMENTATION_PLAN.md, and ai_working/NEXT_PHASE_STATUS.md. Technical gates for Batch D (D-1..D-10) have passed. The final human governance sign-off (Section 9 of docs/governance/GA_PROMOTION_SIGN_OFF.md, gate D-11) is still pending and is the only remaining GA promotion blocker.

4. Release Cadence

Release type Approximate cadence
Stable MINOR Every 6–8 weeks
Stable PATCH / Hotfix As needed (P0 within 48 h, P1 within 1 week)
Release Candidate 1–2 weeks before a stable release

Release dates are tracked in CHANGELOG.md and announced via GitHub Releases.

5. Supported Versions & End-of-Life

Version line Status Security updates End-of-Life
2.4.x ✅ Active / Current prerelease line ✅ Yes TBD
2.3.x and earlier ⚠️ Historical lines — verify per release notes before promising support Case-by-case See CHANGELOG.md

Maintenance means security patches and critical bug fixes only; no new features.
Unsupported means no patches of any kind are provided.

6. Edition Versioning

6.1 Private Plugin Version Compatibility

Private plugins use their own SemVer in addition to the core repository version.

Rules:

  • plugin MAJOR: plugin ABI/API break or incompatible core-compatibility contract change
  • plugin MINOR: new backward-compatible capability
  • plugin PATCH: backward-compatible fix or hardening
  • the superproject release contract is the combination of a plugin-named private submodule pin + manifest compatibility fields, not a floating branch name
  • private plugin manifests should declare min_themisdb_version, optional max_themisdb_version, and optional compatible_core_abi
  • edition-restricted plugins must also declare allowed_editions and license_feature so runtime and packaging gates can stay fail-closed

All five editions share the same MAJOR.MINOR.PATCH base version. Edition-specific builds are distinguished by branch and release naming convention:

Edition Git branch Docker tag pattern Git tag pattern
COMMUNITY community themisdb/themisdb:<version>-community-binary-x64 and ...-arm v<version>
ENTERPRISE enterprise <private-registry>/themisdb-enterprise:<version>-enterprise-binary-x64 and ...-arm enterprise-v<version>
MILITARY military (private registry) military-v<version>
HYPERSCALER hyperscaler <oem-registry>/themisdb-hyperscaler:<version>-hyperscaler-binary-x64 and ...-arm hyperscaler-v<version>
MINIMAL minimal themisdb/themisdb-minimal:<version>-minimal-binary-x64 and ...-arm minimal-v<version>

Release assets on GitHub follow the same canonical basename:

themisdb-{version}-{edition}-{sourcecode|binary}-{arm|x86|x64}

See RELEASE_STRATEGY.md for branch rules, CI gates, and the edition feature matrix.

7. Changelog Requirements

Every release must include a corresponding entry in CHANGELOG.md following the Keep a Changelog convention:

## [MAJOR.MINOR.PATCH] - YYYY-MM-DD

### Added
- ...

### Changed
- ...

### Deprecated
- ...

### Removed
- ...

### Fixed
- ...

### Security
- ...

The [Unreleased] section accumulates changes in progress and is renamed to the version number at release time.

8. Deprecation Policy

  1. A feature is marked deprecated in the CHANGELOG under ### Deprecated.
  2. A deprecation notice is added to the API documentation and (where applicable) a compiler/runtime warning is emitted.
  3. The deprecated feature is removed no earlier than the next MAJOR release (minimum one MINOR release notice period).
  4. Deprecations are never introduced in PATCH releases.

9. Breaking Changes

Breaking changes (API, ABI, wire-protocol, configuration schema) require a MAJOR version bump.

Before introducing a breaking change:

  • Open a GitHub issue labelled breaking-change and link it from the CHANGELOG.
  • Provide a migration guide in docs/migration/ and reference it from the CHANGELOG.
  • Where feasible, provide an automated migration tool or script.

Wire Protocol: The ThemisDB Wire Protocol version is independently versioned (V1, V2, …). New protocol versions are introduced with MINOR version bumps and old versions remain supported for at least one full MAJOR cycle.

10. Pre-release Identifiers

Identifier Meaning
-alphaN Unstable preview (N = 1, 2, …)
-betaN Feature-complete, stabilising
-rcN Release candidate, feature-frozen

Legacy forms -alpha, -beta.N, -rc.N, and -rc may still appear in historical release tags/changelog entries, but new releases should use the canonical -alphaN / -betaN / -rcN format.

Pre-release versions are never considered "stable" for production use. Docker tags for pre-releases carry the full qualifier (e.g., themisdb/themisdb:1.9.0-rc1-community-binary-x64) and the latest tag is only updated on stable releases.

Related Documents

Zuletzt geprueft (Root-Sync): 2026-07-28 (Phase 6 in progress)