Skip to content

versioning.md

Latest commit

 

History

History
95 lines (61 loc) · 5.66 KB

versioning.md

File metadata and controls

95 lines (61 loc) · 5.66 KB

Versioning

All TMHSDigital developer tool repos use Semantic Versioning with fully automated version management.

Source of Truth

The only source of truth for the current version is the version field in .cursor-plugin/plugin.json.

Do not store version numbers anywhere else (except the README badge, which is auto-synced by CI).

How Versions Change

Versions are bumped automatically by the release.yml workflow on every qualifying push to main.

push to main
  -> release.yml runs
    -> reads current version from plugin.json
    -> scans commits since last tag
    -> determines bump type (major/minor/patch)
    -> computes new version
    -> updates plugin.json + README badge
    -> commits [skip ci]
    -> creates git tag vX.Y.Z
    -> creates GitHub Release

Bump Rules

Commit pattern Bump Example
feat!: or BREAKING CHANGE major (X.0.0) feat!: remove deprecated API
feat: or feat(scope): minor (x.Y.0) feat: add new skill
Anything else patch (x.y.Z) fix: handle null in lookup

Patch releases and themed roadmap rows

Patch releases (x.y.Z) do NOT get a row in ROADMAP.md's themed-release table. The roadmap table tracks human-curated milestones with a theme line per row (e.g., v0.12.0 - Niche, Scout, and Extras); inventing a theme for a mechanical patch bump would dilute the table's signal. Patch releases are surfaced in CHANGELOG.md (one stub section per release) and in the **Current:** vX.Y.Z line at the top of ROADMAP.md, both of which are auto-maintained by the release-doc-sync composite action documented in release-doc-sync.md.

Minor and major releases SHOULD get a roadmap row, with the theme set during the planning of that release. The release-doc-sync action does not invent or move table rows for any bump type; humans curate the table and the action keeps the surrounding doc surface (CHANGELOG stub, current-version line, CLAUDE.md **Version:** line) in sync after the auto-bump runs.

What NOT to Do

  • Do not manually edit the version in plugin.json. The release workflow will overwrite it.
  • Do not manually create git tags. The release workflow creates them.
  • Do not manually edit the version badge in README.md. The release workflow updates it.
  • Do not manually edit the GitHub repo About section. The release workflow syncs it.

Skipping Releases

Pushes that only change these paths do not trigger the release workflow:

  • .github/**
  • docs/**
  • *.md
  • LICENSE
  • mkdocs.yml

This prevents docs-only commits from creating empty releases.

Pre-1.0 Development

During initial development (0.x.y), the same rules apply but with the understanding that the API is unstable. Once the plugin reaches feature completeness and has been validated, tag v1.0.0 manually (or via a feat: commit when ready) to signal stability.

Release Notes

The release workflow auto-generates release notes grouped by commit type:

  • Features (feat:)
  • Bug Fixes (fix:)
  • Other Changes (everything else)

CHANGELOG.md is maintained manually for curated, human-readable release history. It is not auto-generated.

Two version files in the meta-repo

The meta-repo root contains two separate version files that serve distinct purposes and move independently.

VERSION - meta-repo release version

Tracks the release history of the meta-repo itself (registry additions, scaffold changes, doc updates, new CI workflows). Bumped by release.yml on every qualifying push to main using the same conventional-commit rules as tool repos. Registry additions (feat:) force a MINOR bump here. This number appears in GitHub Releases and the release changelog but has no direct meaning to tool repos.

STANDARDS_VERSION - ecosystem standards surface version

Tracks the version of the standards that tool repos are expected to comply with. Tool repos embed this value in their <!-- standards-version: X.Y.Z --> markers in CLAUDE.md, AGENTS.md, and ROADMAP.md. The drift checker compares each tool repo's embedded marker against this file, not against VERSION.

STANDARDS_VERSION moves only when the standards surface actually changes in a way that requires tool repos to update:

  • MAJOR (e.g., 1.x.y to 2.0.0) - an incompatible change to the standards themselves. New required elements, removed fields, or restructured file conventions that existing tool repos will fail to validate against without re-alignment.
  • MINOR (e.g., 1.6.x to 1.7.0) - standards changed in a way that tool repos need to re-align with. Typical triggers: new required elements in agent files, changed frontmatter schemas, new required standards references, restructured validation rules, or new checks in the drift checker that introduce findings for existing tool-repo content. A fleet-wide re-stamp session is typically scheduled after a MINOR bump.
  • PATCH (e.g., 1.7.0 to 1.7.1) - clarifications or additions that do not change the standards surface. Tool repos with a PATCH-behind marker are reported as info by the drift checker - visible in verbose runs but not blocking CI.

Registry-only changes, scaffold improvements, docs additions, and other meta-repo work that does not change what tool repos are required to contain do not bump STANDARDS_VERSION, even if they bump VERSION.

The drift checker enforces this mapping via the same-major-minor signal policy (see standards/drift-checker.config.json). Tool repos whose standards-version marker differs from STANDARDS_VERSION in MAJOR or MINOR are reported as error; PATCH differences are info; tool values ahead of meta are warn.