diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index b37648c..ca8d548 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -79,6 +79,46 @@ jobs: exit 1 fi + # Release versions are computed from commit subjects (scripts/next-version.sh), + # so a PR commit without a conventional prefix would silently ship without a + # version bump. Reject those, and show what merging this PR would release. + commits: + if: github.event_name == 'pull_request' + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + - name: Conventional commit subjects + env: + BASE: ${{ github.event.pull_request.base.sha }} + HEAD_SHA: ${{ github.event.pull_request.head.sha }} + run: | + bad=$(git log --format='%h %s' "$BASE..$HEAD_SHA" | grep -vE \ + -e '^[0-9a-f]+ (feat|fix|perf|refactor|docs|test|tests|chore|ci|build|style|revert|merge)(\([^)]+\))?!?: .+' \ + -e '^[0-9a-f]+ (Merge|Revert) ' || true) + if [ -n "$bad" ]; then + echo "::error::Commit subjects must start with a conventional type (feat:, fix:, docs:, ...):" + echo "$bad" + echo "Rename with: git rebase -i $BASE (reword), then force-push the branch." + exit 1 + fi + - name: Release preview + run: | + # The PR checkout is GitHub's test merge into the base branch, so this + # is exactly the version the release job will compute after merging. + git fetch --tags --force + eval "$(bash scripts/next-version.sh)" + last=$(git describe --tags --abbrev=0 --match 'v[0-9]*' 2>/dev/null || echo none) + if [ "$BUMP" = "none" ]; then + msg="Merging this PR releases **no new version** (last: \`$last\`) — only \`:latest\` is refreshed." + else + msg="Merging this PR releases **$VERSION** (\`$BUMP\` bump from \`$last\`)." + fi + echo "$msg" + echo "### Release preview" >> "$GITHUB_STEP_SUMMARY" + echo "$msg" >> "$GITHUB_STEP_SUMMARY" + lint: runs-on: ubuntu-latest steps: diff --git a/docs/ci-cd.md b/docs/ci-cd.md index c92a13e..99e8c18 100644 --- a/docs/ci-cd.md +++ b/docs/ci-cd.md @@ -15,6 +15,10 @@ date-boundary tests depend on): databases, or local artifacts are tracked; if any tracked file matches `.gitignore` (i.e. was force-added); or if a commit message carries an AI co-author trailer. +- **commits** (PRs only) — fails if any commit in the PR lacks a conventional + prefix (`feat:`, `fix:`, `docs:` …; see below), because an unprefixed commit + would silently ship without a version bump. It also writes a **release + preview** to the run summary: the exact version merging the PR will release. - **lint** — `ruff check app/ tests/ scripts/` (config in `pyproject.toml`). - **audit** — `pip-audit` against `requirements.lock`. Marked `continue-on-error`, so a brand-new upstream CVE shows up without blocking an @@ -66,10 +70,16 @@ regenerate and commit both locks: |------------------------------------------|-------|----------------| | `feat!:` / `type!:` / `BREAKING CHANGE` | major | v1.4.2 → v2.0.0 | | `feat: ...` | minor | v1.4.2 → v1.5.0 | -| `fix: ...` | patch | v1.4.2 → v1.4.3 | +| `fix:` / `perf:` / `revert:` / `Revert "…"` | patch | v1.4.2 → v1.4.3 | | only `docs/chore/refactor/test/...` | none | no new release; `:latest` still refreshed | | no tags yet | — | bootstraps **v1.0.0** | +The highest bump in the range wins (one `feat:` among ten `fix:` commits is a +minor release). Allowed prefixes, with an optional `(scope)` and `!`: `feat`, +`fix`, `perf`, `revert`, `refactor`, `docs`, `test`, `chore`, `ci`, `build`, +`style`, `merge`; git's own `Merge …` / `Revert "…"` subjects are accepted too. +The rules are pinned by `tests/test_next_version.py`. + So: keep using `feat:` / `fix:` / `feat!:` commit prefixes and versions bump themselves. ## Docker tags @@ -109,8 +119,8 @@ For GHCR, after the first release publishes the package: credentials, or keep it private and `docker login ghcr.io` on the Unraid host with a classic PAT that has `read:packages`. -Branch protection on `main` requires a pull request and the `hygiene`, `lint`, -`test`, `browser`, and `build-smoke` checks; admins can still bypass in an emergency. +Branch protection on `main` requires a pull request and the `hygiene`, `commits`, +`lint`, `test`, `browser`, and `build-smoke` checks; admins can still bypass in an emergency. ## Manual release fallback diff --git a/scripts/next-version.sh b/scripts/next-version.sh index 5e128f3..907ac84 100755 --- a/scripts/next-version.sh +++ b/scripts/next-version.sh @@ -8,7 +8,7 @@ # Rules (conventional commits, scanning commits in ..HEAD): # - "feat!:" / "type!:" / a "BREAKING CHANGE" footer -> major # - "feat:" -> minor -# - "fix:" -> patch +# - "fix:" / "perf:" / "revert:" / a git `Revert "..."` -> patch # - anything else only -> none (no new release; keep last tag) # - no tags yet -> bootstrap v1.0.0 (initial) # @@ -33,7 +33,7 @@ if printf '%s\n' "$subjects" | grep -qE '^[a-z]+(\([^)]+\))?!:' \ bump=major elif printf '%s\n' "$subjects" | grep -qE '^feat(\([^)]+\))?:'; then bump=minor -elif printf '%s\n' "$subjects" | grep -qE '^fix(\([^)]+\))?:'; then +elif printf '%s\n' "$subjects" | grep -qE '^(fix|perf|revert)(\([^)]+\))?:|^Revert "'; then bump=patch fi diff --git a/tests/test_next_version.py b/tests/test_next_version.py new file mode 100644 index 0000000..7e228be --- /dev/null +++ b/tests/test_next_version.py @@ -0,0 +1,78 @@ +"""scripts/next-version.sh decides every release number, so pin its bump rules.""" +import subprocess +from pathlib import Path + +import pytest + +SCRIPT = Path(__file__).resolve().parent.parent / "scripts" / "next-version.sh" + + +def _git(repo, *args): + subprocess.run(["git", *args], cwd=repo, check=True, capture_output=True, + env={"GIT_AUTHOR_NAME": "t", "GIT_AUTHOR_EMAIL": "t@example.com", + "GIT_COMMITTER_NAME": "t", "GIT_COMMITTER_EMAIL": "t@example.com", + "PATH": "/usr/bin:/bin:/usr/local/bin"}) + + +def _commit(repo, message): + _git(repo, "commit", "-q", "--allow-empty", "-m", message) + + +def _next(repo): + out = subprocess.run(["bash", str(SCRIPT)], cwd=repo, check=True, capture_output=True, text=True).stdout + return dict(line.split("=", 1) for line in out.split()) + + +@pytest.fixture +def repo(tmp_path): + _git(tmp_path, "init", "-q") + _commit(tmp_path, "chore: start") + return tmp_path + + +@pytest.fixture +def tagged(repo): + _git(repo, "tag", "v1.4.2") + return repo + + +@pytest.mark.unit +def test_no_tags_bootstraps_v1(repo): + assert _next(repo) == {"VERSION": "v1.0.0", "BUMP": "initial"} + + +@pytest.mark.unit +@pytest.mark.parametrize("message, version, bump", [ + ("feat!: drop the legacy API", "v2.0.0", "major"), + ("refactor(db)!: new schema", "v2.0.0", "major"), + ("feat: thing\n\nBREAKING CHANGE: config renamed", "v2.0.0", "major"), + ("feat: add route planner", "v1.5.0", "minor"), + ("feat(testers): add Ondilo", "v1.5.0", "minor"), + ("fix: off-by-one", "v1.4.3", "patch"), + ("fix(deps): bump pypdf", "v1.4.3", "patch"), + ("perf: faster today page", "v1.4.3", "patch"), + ("revert: undo the planner", "v1.4.3", "patch"), + ('Revert "feat: add route planner"', "v1.4.3", "patch"), + ("docs: readme", "v1.4.2", "none"), + ("chore: tidy", "v1.4.2", "none"), + ("ci: tweak", "v1.4.2", "none"), + ("merge: branch", "v1.4.2", "none"), +]) +def test_bump_rules(tagged, message, version, bump): + _commit(tagged, message) + assert _next(tagged) == {"VERSION": version, "BUMP": bump} + + +@pytest.mark.unit +def test_highest_bump_in_range_wins(tagged): + for message in ("fix: a", "docs: b", "feat: c", "fix: d"): + _commit(tagged, message) + assert _next(tagged) == {"VERSION": "v1.5.0", "BUMP": "minor"} + + +@pytest.mark.unit +def test_only_commits_since_last_tag_count(tagged): + _commit(tagged, "feat: shipped already") + _git(tagged, "tag", "v1.5.0") + _commit(tagged, "fix: new") + assert _next(tagged) == {"VERSION": "v1.5.1", "BUMP": "patch"}