diff --git a/.claude/skills/release/SKILL.md b/.claude/skills/release/SKILL.md index cc27bb7..157d3c1 100644 --- a/.claude/skills/release/SKILL.md +++ b/.claude/skills/release/SKILL.md @@ -5,8 +5,9 @@ description: Cut and ship a Series of Tubes release (patch or minor) from main v # Releasing Series of Tubes -Bumping `version` in `package.json` on `main` is the release button. The -`auto-release.yml` workflow tests, tags `v`, publishes a GitHub release with +Bumping `version` in `package.json` on `main` is the release button. CI tests the push +as usual; when it passes, `auto-release.yml` (which runs after every CI on `main`) sees +the new version, tags `v` on the commit CI tested, publishes a GitHub release with that version's CHANGELOG section as notes, and dispatches `release.yml`, which builds `_site/` (`npm run build`: the page assembled from `src/` plus `site/`) and deploys it to GitHub Pages (https://seriesoftub.es). GitHub Pages is the only host, ever: see the @@ -65,8 +66,8 @@ gh api repos/fjaeckel/seriesoftubes/releases/latest --jq '.tag_name+" "+.publish ## Steps -1. Don't run the test suite, the game or benchmarks before a release: CI and the - auto-release workflow test it, and the Performance workflow benchmarks it. Just +1. Don't run the test suite, the game or benchmarks before a release: CI tests the + version bump (a red CI releases nothing), and the Performance workflow benchmarks it. Just check that the latest CI run on `main` is green (`gh run list --repo fjaeckel/seriesoftubes --limit 4`). 2. In `CHANGELOG.md`, move the bullets from `## [Unreleased]` into a new section right below it: `## [x.y.z] — YYYY-MM-DD` (em dash, today's date). Keep an empty @@ -81,7 +82,7 @@ gh api repos/fjaeckel/seriesoftubes/releases/latest --jq '.tag_name+" "+.publish --author="Frederic Jung " -m "Short summary (x.y.z)" git push origin main ``` -6. Watch the workflows until both finish: +6. Watch the workflows until all three finish (CI, then Auto-release, then Release to GitHub Pages): ```bash gh run list --repo fjaeckel/seriesoftubes --limit 4 gh run watch --repo fjaeckel/seriesoftubes diff --git a/.github/workflows/auto-release.yml b/.github/workflows/auto-release.yml index bf254e9..6332c25 100644 --- a/.github/workflows/auto-release.yml +++ b/.github/workflows/auto-release.yml @@ -5,10 +5,15 @@ name: Auto-release # as notes, and starts the deploy. Releases created with the workflow token do # not fire the "released" event, so the deploy is started explicitly, from the # tag, which keeps the github-pages environment's v* tag rule happy. +# +# It runs when CI finishes on main, so a release never repeats the push's tests: +# CI green on the commit that bumped the version is the go. A red CI releases +# nothing. Started by hand, it has no CI result to go by, so it tests first. on: - push: + workflow_run: + workflows: [CI] + types: [completed] branches: [main] - paths: [package.json] workflow_dispatch: permissions: @@ -21,6 +26,10 @@ concurrency: jobs: check: + # After CI: only a green run of a push to main (not a PR's run, not a release's own call). + if: >- + github.event_name == 'workflow_dispatch' || + (github.event.workflow_run.conclusion == 'success' && github.event.workflow_run.event == 'push') runs-on: ubuntu-latest env: GH_TOKEN: ${{ github.token }} @@ -29,9 +38,12 @@ jobs: ver: ${{ steps.v.outputs.ver }} tag: ${{ steps.v.outputs.tag }} pre: ${{ steps.v.outputs.pre }} + # The commit CI tested (main may have moved on since); by hand, main as it is now. + sha: ${{ github.event.workflow_run.head_sha || github.sha }} steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: + ref: ${{ github.event.workflow_run.head_sha || github.sha }} fetch-depth: 0 - name: Work out the version and whether it is new @@ -58,23 +70,30 @@ jobs: case "$ver" in *-*) echo "pre=true" >> "$GITHUB_OUTPUT";; *) echo "pre=false" >> "$GITHUB_OUTPUT";; esac echo "skip=false" >> "$GITHUB_OUTPUT" - # The same tests as every push, split over several runners (ci.yml), before anything is tagged. + # Only when started by hand: after a push, CI has already tested this commit. tests: needs: check - if: needs.check.outputs.skip == 'false' + if: needs.check.outputs.skip == 'false' && github.event_name == 'workflow_dispatch' uses: ./.github/workflows/ci.yml + with: + ref: ${{ needs.check.outputs.sha }} release: needs: [check, tests] - if: needs.check.outputs.skip == 'false' + if: >- + always() && needs.check.result == 'success' && needs.check.outputs.skip == 'false' && + (needs.tests.result == 'success' || needs.tests.result == 'skipped') runs-on: ubuntu-latest env: GH_TOKEN: ${{ github.token }} TAG: ${{ needs.check.outputs.tag }} VER: ${{ needs.check.outputs.ver }} PRE: ${{ needs.check.outputs.pre }} + SHA: ${{ needs.check.outputs.sha }} steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + ref: ${{ needs.check.outputs.sha }} - name: Publish the release run: | @@ -82,11 +101,11 @@ jobs: awk -v v="$VER" 'index($0,"## ["v"]")==1{f=1;next} /^## \[/{f=0} f' CHANGELOG.md | sed -e '/./,$!d' > notes.md pre=(); [ "$PRE" = "true" ] && pre=(--prerelease) gh release create "$TAG" --repo "$GITHUB_REPOSITORY" \ - --target "$GITHUB_SHA" --title "$VER" --notes-file notes.md "${pre[@]}" + --target "$SHA" --title "$VER" --notes-file notes.md "${pre[@]}" - name: Deploy it - # Pre-releases are for testing and never go live. The tag was just tested above, so the deploy does not - # test it again (tested=true). + # Pre-releases are for testing and never go live. CI (or the tests above) already passed on this commit, + # so the deploy does not test it again (tested=true). if: env.PRE == 'false' run: gh workflow run release.yml --repo "$GITHUB_REPOSITORY" --ref "$TAG" -f tag="$TAG" -f tested=true diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 2d10c00..1e7d386 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -83,7 +83,7 @@ Development runs on `npm run dev` (assembles the development page on every reque | `tests/harness.js` | Loads the assembled page in jsdom with a seeded `Math.random` and a fake canvas: the players' page, or the development page with `{agent: true}`. The page's scripts run straight in the window (jsdom's parser is slow on 2 MB of script) | | `scripts/test.js`, `tests/durations.json` | Runs the tests, every file in its own process; splits them into parts of equal time for CI (`--plan`, `--shard`) by each file's seconds, which CI refreshes after every run on `main` | | `.github/workflows/ci.yml` | Tests (split over 6 runners), build and translations on every push and PR; the releases call it too, so the tests run one way everywhere | -| `.github/workflows/auto-release.yml` | On a `package.json` version bump on `main`: test (ci.yml), tag, GitHub release from the CHANGELOG, start the deploy (already tested, so it does not test again) | +| `.github/workflows/auto-release.yml` | After every green CI on `main`: if `package.json` has a new version, tag the commit CI tested, publish the GitHub release from the CHANGELOG, start the deploy (`tested=true`, so it does not test again) | | `.github/workflows/release.yml` | Builds and deploys to GitHub Pages, the only workflow that can | | `.github/workflows/weekly-puzzle.yml` | Sunday 03:37 UTC: makes the week's puzzle, commits it to `main` (data only, no release) and starts `release.yml` for the live release tag with `weekly=true` | | `scripts/weekly-puzzle.js`, `site/puzzles/weekly/` | The weekly puzzle generator and its output, one `.json` per week plus `index.json` (see below) |