Skip to content

docs(ci): add VERSIONING.md documenting unified workspace versioning invariant #177

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
stackbilt-admin merged 1 commit into from
May 23, 2026
Merged

docs(ci): add VERSIONING.md documenting unified workspace versioning invariant #177

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions .github/VERSIONING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Loading