Skip to content

Commit 1663d65

Browse files
voightpclaude
authored andcommitted
Add self-test workflow and contributing guide
Nothing in this repository is exercised by its own CI, and everything in it is consumed by other repositories at run time - so a regression here surfaces in whichever repo releases next rather than in a build we watch. - .github/workflows/self-test.yml: runs the building blocks against fixtures. A workflow may reference a sibling by local path, and `./` resolves against the current checkout, so on a branch this tests that branch's definitions - the only way to try a change before tagging it. Covers all four version-file shapes, asserts unusable inputs are refused rather than silently resolving to nothing, and runs release.yml end to end down the path that creates nothing. That job holds only contents:read on purpose: if the skip logic regresses, the release attempt fails loudly instead of publishing something unintended. - tests/fixtures: pyproject.toml (PEP 621 and Poetry), package.json, a plain VERSION file, and a version-less pyproject for the rejection case. - CONTRIBUTING.md: what separates a minor bump from a new major, how main and the release/vN branches split, the release procedure, and the gaps the self-test does not close. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
1 parent 26f55cd commit 1663d65

8 files changed

Lines changed: 329 additions & 6 deletions

File tree

‎.github/workflows/self-test.yml‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
name: Self-test
2+
3+
# Exercises this repository's own building blocks against the fixtures in
4+
# tests/fixtures. Within a repository a workflow may reference a sibling with a
5+
# local path, and `./` resolves against the current checkout - so on a branch
6+
# this tests *that branch's* definitions, which is the only way to try a change
7+
# before tagging it.
8+
9+
on:
10+
pull_request:
11+
push:
12+
branches: [main]
13+
workflow_dispatch:
14+
15+
permissions:
16+
contents: read
17+
18+
jobs:
19+
read-version:
20+
name: read-version (${{ matrix.case.name }})
21+
runs-on: ubuntu-latest
22+
strategy:
23+
fail-fast: false
24+
matrix:
25+
case:
26+
- name: pep621
27+
file: tests/fixtures/pep621/pyproject.toml
28+
prefix: v
29+
version: 0.3.0
30+
tag: v0.3.0
31+
- name: poetry-fallback
32+
file: tests/fixtures/poetry/pyproject.toml
33+
prefix: v
34+
version: 9.9.9
35+
tag: v9.9.9
36+
- name: package-json
37+
file: tests/fixtures/node/package.json
38+
prefix: v
39+
version: 2.1.0
40+
tag: v2.1.0
41+
- name: plain-text
42+
file: tests/fixtures/plain/VERSION
43+
prefix: release-
44+
version: 1.2.3
45+
tag: release-1.2.3
46+
steps:
47+
- uses: actions/checkout@v4
48+
49+
- id: read
50+
uses: ./actions/read-version
51+
with:
52+
version-file: ${{ matrix.case.file }}
53+
tag-prefix: ${{ matrix.case.prefix }}
54+
55+
- name: Assert outputs
56+
env:
57+
GOT_VERSION: ${{ steps.read.outputs.version }}
58+
GOT_TAG: ${{ steps.read.outputs.tag }}
59+
WANT_VERSION: ${{ matrix.case.version }}
60+
WANT_TAG: ${{ matrix.case.tag }}
61+
run: |
62+
set -euo pipefail
63+
failed=0
64+
if [ "$GOT_VERSION" != "$WANT_VERSION" ]; then
65+
echo "::error::version: got '$GOT_VERSION', want '$WANT_VERSION'"
66+
failed=1
67+
fi
68+
if [ "$GOT_TAG" != "$WANT_TAG" ]; then
69+
echo "::error::tag: got '$GOT_TAG', want '$WANT_TAG'"
70+
failed=1
71+
fi
72+
if [ "$failed" -eq 0 ]; then
73+
echo "version=$GOT_VERSION tag=$GOT_TAG as expected"
74+
fi
75+
exit "$failed"
76+
77+
read-version-rejects:
78+
name: read-version rejects (${{ matrix.case.name }})
79+
runs-on: ubuntu-latest
80+
strategy:
81+
fail-fast: false
82+
matrix:
83+
case:
84+
- name: missing-file
85+
file: tests/fixtures/does-not-exist/pyproject.toml
86+
- name: no-version-declared
87+
file: tests/fixtures/no-version/pyproject.toml
88+
steps:
89+
- uses: actions/checkout@v4
90+
91+
# A silent empty version would be worse than a hard failure: it would tag
92+
# the wrong thing. Assert these inputs are refused outright.
93+
- id: read
94+
continue-on-error: true
95+
uses: ./actions/read-version
96+
with:
97+
version-file: ${{ matrix.case.file }}
98+
99+
- name: Assert the action failed
100+
env:
101+
OUTCOME: ${{ steps.read.outcome }}
102+
GOT_VERSION: ${{ steps.read.outputs.version }}
103+
run: |
104+
set -euo pipefail
105+
if [ "$OUTCOME" != "failure" ]; then
106+
echo "::error::expected read-version to fail, but the outcome was '$OUTCOME' (version='$GOT_VERSION')"
107+
exit 1
108+
fi
109+
echo "rejected as expected"
110+
111+
# End-to-end run of the release workflow down the path that creates nothing:
112+
# v1.0.0 is already tagged in this repository, so this must skip. Deliberately
113+
# granted only contents:read - if the skip logic ever regresses, the attempt to
114+
# create a release fails loudly instead of publishing something unintended.
115+
release-skips-existing-tag:
116+
permissions:
117+
contents: read
118+
uses: ./.github/workflows/release.yml
119+
with:
120+
version: 1.0.0
121+
fail-if-tag-exists: false
122+
123+
assert-release-skipped:
124+
needs: release-skips-existing-tag
125+
runs-on: ubuntu-latest
126+
steps:
127+
- name: Assert nothing was released
128+
env:
129+
CREATED: ${{ needs.release-skips-existing-tag.outputs.created }}
130+
TAG: ${{ needs.release-skips-existing-tag.outputs.tag }}
131+
VERSION: ${{ needs.release-skips-existing-tag.outputs.version }}
132+
URL: ${{ needs.release-skips-existing-tag.outputs.url }}
133+
run: |
134+
set -euo pipefail
135+
failed=0
136+
if [ "$CREATED" != "false" ]; then
137+
echo "::error::created: got '$CREATED', want 'false' - the skip path regressed"
138+
failed=1
139+
fi
140+
if [ "$VERSION" != "1.0.0" ] || [ "$TAG" != "v1.0.0" ]; then
141+
echo "::error::resolution: got version='$VERSION' tag='$TAG', want '1.0.0' / 'v1.0.0'"
142+
failed=1
143+
fi
144+
if [ -n "$URL" ]; then
145+
echo "::error::url should be empty when nothing was created, got '$URL'"
146+
failed=1
147+
fi
148+
if [ "$failed" -eq 0 ]; then
149+
echo "skipped v1.0.0 as expected; nothing created"
150+
fi
151+
exit "$failed"

‎CONTRIBUTING.md‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
# Contributing
2+
3+
Everything here is consumed by other repositories at run time. A bad tag does
4+
not break a build in this repo — it breaks whichever repo happens to release
5+
next. That single fact drives all of the conventions below.
6+
7+
## Refs, and what each one is for
8+
9+
```
10+
main development; always the newest major
11+
release/v1 maintenance; created lazily, only once v2 exists
12+
v1.0.0, v1.1.0, v2.0.0 immutable release tags; never move
13+
v1, v2 moving pointers; this is what callers pin
14+
```
15+
16+
Callers pin `@v1`. You re-point `v1` at each backwards-compatible release, so
17+
they pick up fixes without editing anything. `workflow_call` resolves the ref
18+
at run time, which is why moving `v1` takes effect everywhere on the next run —
19+
and why the v1/v2 line has to be drawn on the caller's contract rather than on
20+
how much code changed.
21+
22+
## Deciding between a minor bump and a new major
23+
24+
The contract is whatever a calling repository has written in **its** YAML.
25+
Break that and it is a new major. Everything else is a minor or patch, and
26+
`v1` moves.
27+
28+
Forces a new major:
29+
30+
- Renaming or removing an input, or making an optional input required.
31+
- Changing an input's default such that behaviour changes — e.g. `tag-prefix`
32+
from `v` to `''`.
33+
- Renaming an output, or changing what it means.
34+
- Requiring a new secret.
35+
- Requiring broader `permissions:` on the caller's job.
36+
- Renaming the internal `release:` job id.
37+
- Raising the runner floor, e.g. now needing a newer Python than `tomllib`
38+
currently requires.
39+
40+
Stays on the current major:
41+
42+
- Adding an optional input whose default preserves existing behaviour.
43+
- Adding an output.
44+
- Fixing a bug, internal refactors, better logging, step-summary changes.
45+
- Bumping a pinned action, e.g. `actions/checkout@v4` to `@v5`, as long as
46+
runner requirements do not change.
47+
48+
Two of the breaking cases are easy to miss because the diff looks additive:
49+
50+
- **Caller permissions.** Add a step needing `packages: write` and every caller
51+
must edit their workflow before it works. A called workflow can never hold
52+
more permission than the caller's token grants.
53+
- **The job id.** The check name a caller sees is `<their job> / release`.
54+
Renaming `release:` silently breaks anyone's branch-protection required
55+
checks.
56+
57+
The grey area is a bug fix somebody might be relying on. Rule of thumb: if the
58+
current behaviour is defensible as intentional, treat changing it as breaking;
59+
if nobody could sanely want it, patch it on the current major.
60+
61+
## How the branches split
62+
63+
Nothing about `main` changes when a new major arrives — `main` is simply always
64+
the newest major. The asymmetry is on the old line.
65+
66+
**Before v2 exists.** Branch off `main`, merge, tag `v1.x.y`, move `v1`. One
67+
line, no maintenance branch.
68+
69+
**The moment `v2.0.0` is tagged from `main`.** `main` now holds v2 code, so a
70+
v1 patch can no longer be cut from it. Create `release/v1` from the last v1
71+
commit — do this lazily, at the first v1 fix you actually need, not
72+
pre-emptively.
73+
74+
**After that.** v1 fixes land on `release/v1`, tag `v1.x.y`, move `v1`. v2 work
75+
lands on `main`, tag `v2.x.y`, move `v2`. Fixes affecting both get
76+
cherry-picked, normally main first.
77+
78+
## Testing a change before tagging it
79+
80+
[`.github/workflows/self-test.yml`](.github/workflows/self-test.yml) exercises
81+
the building blocks against [`tests/fixtures`](tests/fixtures). Within a
82+
repository a workflow may reference a sibling with a local path, and `./`
83+
resolves against the current checkout, so on a branch the self-test runs
84+
*that branch's* definitions. Open a pull request, or dispatch it manually:
85+
86+
```bash
87+
gh workflow run self-test.yml --ref my-branch
88+
```
89+
90+
It covers version resolution for all four file shapes, asserts that unusable
91+
inputs are refused rather than silently resolving to nothing, and runs
92+
`release.yml` end to end down the path that creates nothing — `v1.0.0` is
93+
already tagged here, so it must skip. That job is granted only
94+
`contents: read` on purpose: if the skip logic ever regresses, creating a
95+
release fails loudly instead of publishing something unintended.
96+
97+
What the self-test does **not** cover:
98+
99+
- The release-creation path itself. Nothing verifies a real `gh release create`
100+
without publishing a real release, so that stays manual.
101+
- The `token` secret fallback. `${{ secrets.token || secrets.GITHUB_TOKEN }}`
102+
is evaluated on the create step, which the skip path never reaches.
103+
- `tag-prefix: ''`. Whether an explicitly empty `with:` value overrides an
104+
action's declared default or falls back to it is an Actions sharp edge;
105+
confirm the behaviour before relying on bare `1.2.3` tags.
106+
107+
For anything beyond that, point a scratch repository at a branch or a full
108+
SHA — callers can pin any ref, not just tags:
109+
110+
```yaml
111+
uses: DesignBuilderSoftware/db-github-workflows/.github/workflows/release.yml@my-branch
112+
```
113+
114+
## Cutting a release
115+
116+
1. Merge to `main` (or to `release/vN` for a maintenance fix).
117+
2. Confirm the self-test is green on that commit.
118+
3. Tag the immutable version and push it:
119+
120+
```bash
121+
git tag -a v1.1.0 -m "v1.1.0" && git push origin v1.1.0
122+
```
123+
124+
4. Move the major pointer:
125+
126+
```bash
127+
git tag -f v1 v1.1.0 && git push origin --force v1
128+
```
129+
130+
Step 4 is the one that reaches every caller, so leave a gap between 3 and 4 if
131+
you want to try the pinned version somewhere first.
132+
133+
## Known duplication
134+
135+
Version-resolution logic is deliberately duplicated between
136+
[`release.yml`](.github/workflows/release.yml) and
137+
[`actions/read-version`](actions/read-version/action.yml). A reusable workflow
138+
cannot `uses: ./actions/...` — when called from elsewhere, `./` resolves
139+
against the *caller's* checkout, not this repository — and pointing it at a
140+
pinned tag of itself creates a bootstrapping problem. Change one, change the
141+
other; the self-test covers both.
142+
143+
## Shared tag space
144+
145+
`release.yml` and `actions/read-version` share one set of tags. A breaking
146+
change to the workflow drags the action to the next major too, even untouched:
147+
callers of `read-version@v1` keep working, but sit on an ageing line until
148+
someone cuts `v1.x` fixes for it. That is acceptable while the repo is small.
149+
If the two genuinely diverge, the way out is per-component tags such as
150+
`read-version/v1`, not splitting the repository.

‎README.md‎

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -172,13 +172,13 @@ rules are identical to `release.yml`.
172172

173173
## Maintaining this repository
174174

175-
The version-resolution logic is intentionally duplicated between
176-
`release.yml` and `actions/read-version/action.yml`. A reusable workflow cannot
177-
`uses: ./actions/...` — a relative path resolves against the *caller's*
178-
checkout, not this repository — and pointing it at a pinned tag of itself
179-
creates a bootstrapping problem. Change one, change the other.
175+
See [CONTRIBUTING.md](CONTRIBUTING.md) for how `main`, the `release/vN`
176+
branches and the moving `vN` tags fit together, what counts as a breaking
177+
change to a caller's contract, and how to test a change before tagging it.
180178

181-
After a change worth shipping, tag it and move the major tag:
179+
In short: develop on a branch off `main`, let
180+
[`self-test.yml`](.github/workflows/self-test.yml) run against it, then tag an
181+
immutable version and move the major pointer.
182182

183183
```bash
184184
git tag -a v1.1.0 -m "v1.1.0" && git push origin v1.1.0
@@ -188,6 +188,11 @@ git tag -a v1.1.0 -m "v1.1.0" && git push origin v1.1.0
188188
git tag -f v1 v1.1.0 && git push origin --force v1
189189
```
190190

191+
One trap worth repeating here: version-resolution logic is deliberately
192+
duplicated between `release.yml` and `actions/read-version/action.yml`, because
193+
a reusable workflow cannot `uses: ./actions/...` — when called from elsewhere,
194+
`./` resolves against the caller's checkout. Change one, change the other.
195+
191196
## Licence
192197

193198
MIT — see [LICENSE](LICENSE).
Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Fixture: no version anywhere - resolution must fail, not default to something.
2+
[project]
3+
name = "fixture-no-version"

‎tests/fixtures/node/package.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{
2+
"name": "fixture-node",
3+
"version": "2.1.0",
4+
"private": true
5+
}
Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Fixture: PEP 621 [project].version - the db-process shape.
2+
[project]
3+
name = "fixture-pep621"
4+
version = "0.3.0"

‎tests/fixtures/plain/VERSION‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
1.2.3
Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Fixture: [tool.poetry].version, the fallback when [project] is absent.
2+
[tool.poetry]
3+
name = "fixture-poetry"
4+
version = "9.9.9"

0 commit comments

Comments
 (0)