From 652b0b7fc9cf88b8163e8f1ac442fe7fe03a81c6 Mon Sep 17 00:00:00 2001 From: Kurt Overmier Date: Sat, 23 May 2026 05:04:08 -0500 Subject: [PATCH] docs(ci): add VERSIONING.md documenting unified workspace versioning invariant Closes #122. Co-Authored-By: Claude Sonnet 4.6 --- .github/VERSIONING.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 .github/VERSIONING.md diff --git a/.github/VERSIONING.md b/.github/VERSIONING.md new file mode 100644 index 0000000..6a48190 --- /dev/null +++ b/.github/VERSIONING.md @@ -0,0 +1,21 @@ +# Versioning Invariant + +Charter uses **unified workspace versioning**: every package under `packages/*/package.json` carries the same version as the release tag. + +## Invariant + +For any release tag `vX.Y.Z`: + +``` +packages/*/package.json → "version": "X.Y.Z" +``` + +All twelve packages ship together at the same version. There is no per-package version drift. + +## Enforcement + +`.github/workflows/release.yml` — `publish-npm` job, "Verify tag and workspace versions" step — enforces this at release time. It loops over every `packages/*/package.json` and fails the build if any version does not match the tag. + +## Migration note + +If Charter ever adopts independent per-package versioning, the enforcement step must be reworked before the first diverging release. Each package would need its own expected version source (e.g. the package's own `package.json` rather than the global tag). See [#122](https://github.com/Stackbilt-dev/charter/issues/122) for the original discussion.