|
| 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. |
0 commit comments