From 1fe326b8c8ff92ef035b03af60f33008be42fe68 Mon Sep 17 00:00:00 2001 From: Richard Schuster Date: Mon, 19 Oct 2026 15:27:57 -0700 Subject: [PATCH] feat: stack-neutral CI gating, one required check, warm-cache option Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_016fLMCisgJaBzKzRDsUoyUq --- .github/workflows-optional/warm-cache.yml | 39 ++++++++++++ .github/workflows/ci.yml | 78 ++++++++++++++++++++--- .gitignore | 3 + CHANGELOG.md | 9 +++ CLAUDE.md | 11 ++-- CONTRIBUTING.md | 7 +- README.md | 25 +++++--- docs/handoffs/HANDOFF_TEMPLATE.md | 2 + scripts/bootstrap-repo-settings.sh | 10 +-- 9 files changed, 156 insertions(+), 28 deletions(-) create mode 100644 .github/workflows-optional/warm-cache.yml diff --git a/.github/workflows-optional/warm-cache.yml b/.github/workflows-optional/warm-cache.yml new file mode 100644 index 0000000..67ee926 --- /dev/null +++ b/.github/workflows-optional/warm-cache.yml @@ -0,0 +1,39 @@ +name: Warm cache + +# OPT-IN. Move this file into .github/workflows/ to use it. +# +# GitHub lets a PR read caches saved on main but not caches saved by another +# PR, and CI only runs on PRs. This job saves a cache from main, so the PR +# runs in ci.yml find it. Use it when a job downloads something slow or large +# on every run (dependencies, a browser, a toolchain). +# +# Fill in the two placeholders. The cache path and key must match the +# actions/cache step in ci.yml exactly, or the PRs never hit this cache. +on: + push: + branches: [main] + paths: [LOCKFILE] + schedule: + # Caches unused for 7 days are dropped; refresh twice a week. + - cron: '17 4 * * 1,4' + workflow_dispatch: + +permissions: + contents: read + +jobs: + warm: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + + - name: Cache + id: cache + uses: actions/cache@v6 + with: + path: PATH_TO_CACHE + key: cache-${{ runner.os }}-${{ hashFiles('LOCKFILE') }} + + - name: Fill the cache + if: steps.cache.outputs.cache-hit != 'true' + run: YOUR_COMMAND_THAT_DOWNLOADS_INTO_PATH_TO_CACHE diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index f06a7fc..bb45870 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1,12 +1,12 @@ name: CI -# push to main is kept so a fresh repo gets a first run. If you adopt the -# solo-maintainer auto-merge workflows (README.md), drop the push trigger: with -# "require branches to be up to date" every PR is tested against current main -# before it merges, so a second run after the merge tests the same code again. +# PRs only: with strict branch protection every PR is tested against current +# main before it merges, so a run on push to main would test the same code +# again. If you do not use strict protection, add this back under `on:` so a +# fresh repo gets a first run: +# push: +# branches: [main] on: - push: - branches: [main] pull_request: branches: [main] @@ -15,11 +15,69 @@ concurrency: group: ci-${{ github.ref }} cancel-in-progress: true -# Stack-neutral repo hygiene checks only. Add your project's own -# format/lint/typecheck/test/build job(s) alongside this once the stack is -# chosen; that is a separate job so this one keeps working with no stack at -# all. +# Layout: +# - changes: says whether the PR touches anything besides docs and Markdown. +# - repo-hygiene: stack-neutral checks, always runs. +# - your own jobs: add them with the `needs`/`if` lines of the example below, +# so a docs-only PR skips them and clears in seconds. +# - checks: the one required status check. It passes when every job it needs +# passed or was skipped. Branch protection names only this job, so adding or +# renaming a stack job never means touching the protection rules. jobs: + changes: + runs-on: ubuntu-latest + permissions: + pull-requests: read + outputs: + code: ${{ steps.diff.outputs.code }} + steps: + - id: diff + env: + GH_TOKEN: ${{ github.token }} + PR: ${{ github.event.pull_request.number }} + run: | + files=$(gh api "repos/${GITHUB_REPOSITORY}/pulls/${PR}/files" --paginate --jq '.[].filename') + if printf '%s\n' "$files" | grep -qvE '^docs/|\.md$'; then + echo "code=true" >> "$GITHUB_OUTPUT" + else + echo "code=false" >> "$GITHUB_OUTPUT" + fi + + # Example stack job, to copy once the stack is chosen. Add its name to the + # `needs` list of `checks` below. + # + # build: + # needs: changes + # if: needs.changes.outputs.code == 'true' + # runs-on: ubuntu-latest + # steps: + # - uses: actions/checkout@v7 + # # Setup, install, then format/lint/typecheck/test/build for your stack. + # # + # # Caching a slow-to-fetch dependency or tool: restore it with + # # actions/cache and a key from your lockfile. A PR can read caches + # # saved on main but not caches saved by another PR, so also add + # # workflows-optional/warm-cache.yml with the same key. + # - uses: actions/cache@v6 + # with: + # path: PATH_TO_CACHE + # key: cache-${{ runner.os }}-${{ hashFiles('LOCKFILE') }} + # - run: YOUR_BUILD_AND_TEST_COMMAND + + checks: + needs: [changes, repo-hygiene] + if: always() + runs-on: ubuntu-latest + steps: + - name: All jobs passed or were skipped + env: + RESULTS: ${{ join(needs.*.result, ' ') }} + run: | + echo "results: $RESULTS" + case "$RESULTS" in + *failure*|*cancelled*) exit 1 ;; + esac + repo-hygiene: runs-on: ubuntu-latest steps: diff --git a/.gitignore b/.gitignore index 433ca89..872904f 100644 --- a/.gitignore +++ b/.gitignore @@ -10,6 +10,9 @@ node_modules/ dist/ coverage/ *.tsbuildinfo +__pycache__/ +playwright-report/ +test-results/ # Logs and temp *.log diff --git a/CHANGELOG.md b/CHANGELOG.md index 8902b72..ac84417 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,15 @@ All notable changes to this project are documented here. The format is based on ### Added +- CI: `changes` job so docs-only PRs skip stack jobs, a single required + `checks` job, a commented cache example, and an opt-in `warm-cache.yml`. +- Hints in `CLAUDE.md`, `CONTRIBUTING.md`, `.gitignore` and the handoff + template. - Initial project harness: issue and PR templates, contribution and security policies, docs structure (design, decisions, handoffs), and Claude Code working rules. + +### Changed + +- `ci.yml` runs on pull requests only; `bootstrap-repo-settings.sh` gates on + `checks` by default. diff --git a/CLAUDE.md b/CLAUDE.md index 85db51e..deb370c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -35,14 +35,17 @@ under `src/core/` so it is unit-testable"). Link to the relevant ADR(s) in ## Commands {{The everyday commands: run, test, lint/typecheck, build. One line each, and -mark which ones are gates (non-zero exit blocks a merge). Fill in once the -stack is chosen; `CONTRIBUTING.md` Setup should match.}} +mark which ones are gates (non-zero exit blocks a merge). Say how long the +slow ones take and which ones CI skips, so nobody runs a 20 minute suite by +accident. Fill in once the stack is chosen; `CONTRIBUTING.md` Setup should +match.}} ## Repo structure {{Optional: a short map of top-level directories, only if it adds real -orientation beyond exploring the tree. Keep it brief and expect it to drift; -when in doubt, explore the tree rather than trusting this section.}} +orientation beyond exploring the tree. State layering rules here too, such as "`core/` never imports from `ui/`". +Keep it brief and expect it to drift; when in doubt, explore the tree rather +than trusting this section.}} ## Working rules diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d795b29..6ab2abf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,7 +12,12 @@ The workflow is: ## Setup -TODO: setup and local-run instructions once the stack is chosen. +TODO: setup and local-run instructions once the stack is chosen. A good shape: + +- Prerequisites (tool and version). +- A short block that installs, runs, and checks. Make its last line the + command CI runs, and say so. +- Pointers to `CLAUDE.md` for anything stack-specific or slow. ## Conventions diff --git a/README.md b/README.md index e4c09f6..a1c6f35 100644 --- a/README.md +++ b/README.md @@ -25,16 +25,16 @@ and Claude Code working rules (`CLAUDE.md`, `.claude/settings.json`). `.github/workflows/ci.yml`, alongside the existing stack-neutral `repo-hygiene` job (markdown lint, no-em-dash check, docs-structure check, workflow lint). Do not replace that job; add another one next to - it. + it, copying the commented example, and add its name to the `needs` list + of the `checks` job. The `changes` job lets a docs-only PR skip it. - Add a `package-ecosystem` entry to `.github/dependabot.yml` for your package manager (see the commented example there). 7. Run `scripts/bootstrap-repo-settings.sh` once (requires the GitHub CLI, authenticated with admin access on the new repo) to set branch protection on `main`, enable auto-merge, and create the starter label set. Templates do not carry repo settings over, only files, so this step is manual. - Pass your CI job names as extra arguments (for example - `scripts/bootstrap-repo-settings.sh owner/repo repo-hygiene build`) once - you have added your stack's job; the default gates on `repo-hygiene` only. + It gates on the single `checks` job of `ci.yml`, which collects all the + others, so adding a stack job later needs no change to branch protection. Note this only lets a PR *request* auto-merge; someone still has to click it. For a solo-maintainer repo, see "Solo-maintainer auto-merge" below. 8. Add your first ADR to `docs/decisions/` (see `docs/decisions/README.md` @@ -60,9 +60,17 @@ One-time setup: create a fine-grained personal access token for this repo only (Contents, Pull requests and Workflows: read/write) and store it as the `AUTO_MERGE_TOKEN` secret. `GITHUB_TOKEN` cannot be used because GitHub starts no workflows for pushes or merges made with it, so the PR's checks would never -run on the updated branch. Rotate the PAT before it expires. Then drop the -`push` trigger from `ci.yml`: with strict protection every PR is tested against -current `main` before it merges. +run on the updated branch. Rotate the PAT before it expires. `ci.yml` already +runs on PRs only: with strict protection every PR is tested against current +`main` before it merges. + +## Cache warming (optional) + +`.github/workflows-optional/warm-cache.yml` saves a cache from `main`, because +a PR can read caches saved on `main` but not caches saved by another PR. Use it +if a CI job downloads something slow on every run. Move it into +`.github/workflows/`, fill in the two placeholders, and use the same path and +key in the `actions/cache` step of your CI job. ## What's included @@ -75,7 +83,8 @@ current `main` before it merges. - `docs/handoffs/`: session handoff template for continuity between work sessions. - `.github/`: issue forms, PR template, Dependabot config, a stack-neutral CI - workflow, and optional solo-maintainer auto-merge workflows. + workflow (docs-only PRs skip stack jobs, one required `checks` status), and + optional solo-maintainer auto-merge and cache-warming workflows. - `CONTRIBUTING.md`, `SECURITY.md`, `CHANGELOG.md`, `LICENSE`. - `scripts/bootstrap-repo-settings.sh`: one-time repo settings setup (branch protection, auto-merge, labels) that a template cannot carry over on its diff --git a/docs/handoffs/HANDOFF_TEMPLATE.md b/docs/handoffs/HANDOFF_TEMPLATE.md index ccd918b..53d87fa 100644 --- a/docs/handoffs/HANDOFF_TEMPLATE.md +++ b/docs/handoffs/HANDOFF_TEMPLATE.md @@ -1,5 +1,7 @@ # Session Handoff: YYYY-MM-DD + + ## Summary One short paragraph: what this session was about and where things stand. diff --git a/scripts/bootstrap-repo-settings.sh b/scripts/bootstrap-repo-settings.sh index 221243c..da1813a 100755 --- a/scripts/bootstrap-repo-settings.sh +++ b/scripts/bootstrap-repo-settings.sh @@ -8,17 +8,17 @@ # # Usage: scripts/bootstrap-repo-settings.sh [owner/repo [check ...]] # If owner/repo is omitted, it is inferred from the current git remote. -# Each check is the name of a CI job that must pass before a PR can merge; -# the default is "repo-hygiene". Once you add your stack's own job (README.md -# step 6), re-run with both, e.g.: -# scripts/bootstrap-repo-settings.sh owner/repo repo-hygiene build +# Each check is the name of a CI job that must pass before a PR can merge. +# The default is "checks", the job in ci.yml that gathers all the others, so +# adding a stack job needs no re-run; list other names only if you want +# protection on them directly. set -euo pipefail REPO="${1:-$(gh repo view --json nameWithOwner --jq .nameWithOwner)}" shift || true CHECKS=("$@") -[ ${#CHECKS[@]} -gt 0 ] || CHECKS=(repo-hygiene) +[ ${#CHECKS[@]} -gt 0 ] || CHECKS=(checks) CONTEXTS=$(printf '"%s",' "${CHECKS[@]}") CONTEXTS="[${CONTEXTS%,}]" echo "Bootstrapping settings for $REPO"