Skip to content

VERSIONING.md

Latest commit

 

History

History
196 lines (133 loc) · 6.63 KB

VERSIONING.md

File metadata and controls

196 lines (133 loc) · 6.63 KB

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:
  1.8.0
  1.8.1-rc1
  2.0.0-alpha1
  2.0.0-beta2
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 1.8.2rc
CHANGELOG.md Keep a Changelog header ## [1.8.2-rc1] - 2026-04-xx

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).

3. Release Types

Type Description Example tag
Alpha Early preview; API may change significantly v1.9.0-alpha1
Beta Feature-complete; API stabilising v1.9.0-beta1
Release Candidate (RC) Feature-frozen; only bug fixes v1.9.0-rc1
Stable General availability (GA) v1.9.0
Patch / Hotfix Critical fixes on a stable release v1.8.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.

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
1.8.x ✅ Active / Current ✅ Yes TBD
1.7.x 🔧 Maintenance ✅ Yes 2026-12-31
1.6.x and earlier ❌ Unsupported ❌ No Reached EOL
0.9.x 🔧 Maintenance (legacy) ✅ Yes 2026-12-31
< 0.9 ❌ Unsupported ❌ No 2024-01-01

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

6. Edition Versioning

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 main themisdb/themisdb:1.8.0-community-binary-x64 and ...-arm v1.8.0
ENTERPRISE enterprise <private-registry>/themisdb-enterprise:1.8.0-enterprise-binary-x64 and ...-arm enterprise-v1.8.0
MILITARY enterprise (private registry) military-v1.8.0
HYPERSCALER hyperscaler <oem-registry>/themisdb-hyperscaler:1.8.0-hyperscaler-binary-x64 and ...-arm hyperscaler-v1.8.0
MINIMAL main themisdb/themisdb-minimal:1.8.0-minimal-binary-x64 and ...-arm v1.8.0-minimal

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

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