From f8bde3d1ff9d22e2a1784068e0dbb8b2a048d5ff Mon Sep 17 00:00:00 2001 From: Jimisola Laursen Date: Mon, 24 Aug 2026 01:48:23 +0200 Subject: [PATCH] docs(readme): document how this repo is versioned Every repo in the org now pins to a tag here rather than @main (#25), which makes two things load-bearing that were nowhere written down: that consumers pin @ # rather than @, and that merging to main releases nothing until someone tags. The second already bit: 1.0.0 was tagged before #99 merged, so the consumers pinned to it are still on the old VS Code publish path. A tag that lags main means fixes reach nobody and Renovate has nothing to propose. Signed-off-by: Jimisola Laursen --- README.md | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/README.md b/README.md index 874e3ce..a96f599 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,45 @@ This repository contains organisation-wide community health files and governance Files placed here are automatically used by GitHub as defaults for all repositories in the organisation that do not provide their own. +## Versioning + +This repository is consumed by every other repo in the organisation, so a change here +reaches all of them. **It is versioned with tags, and consumers pin to a commit SHA rather +than to `main`.** + +```yaml +uses: reqstool/.github/.github/workflows/common-release-prepare.yml@ # 1.0.0 +``` + +The SHA is what actually resolves; the `# ` comment is what makes it readable and +is what Renovate keys off. A bare `@1.0.0` would not do — a tag is mutable, so CodeQL's +`actions/unpinned-tag` flags it, and it would reintroduce exactly the problem pinning solves. +Tags carry no `v` prefix, matching every other repo in the organisation. + +Renovate keeps these current: `.github/renovate.json5` digest-pins everything outside +`actions/*` and `github/*`, so a new tag here opens a bump PR in each consumer with the +digest and the comment rewritten together. + +### Cutting a new version + +**Merging to `main` does not release anything.** Consumers stay on whatever tag they pin +until a new one exists, so a fix merged here and never tagged reaches nobody — and Renovate +has nothing to propose. Tag after merging a change consumers need: + +```bash +git tag 1.1.0 && git push origin 1.1.0 +``` + +Then let Renovate raise the bumps rather than editing consumers by hand. + +Use ordinary semver judgement about what the change means *to a consumer*: a new input or +workflow is a minor, a fixed workflow is a patch, and removing or renaming a workflow, an +action, or a required input is a major — that last one breaks every caller that names it. + +This is deliberately not the flow in [`RELEASING.md`](RELEASING.md). That describes how the +*other* repos publish to PyPI, npm, Maven Central and the marketplaces. Nothing here is +published to a registry, so a tag is the whole release. + ## Contents | File / Directory | Purpose |