Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 40 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
16 changes: 13 additions & 3 deletions docs/ci-cd.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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

Expand Down
4 changes: 2 additions & 2 deletions scripts/next-version.sh
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
# Rules (conventional commits, scanning commits in <last-tag>..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)
#
Expand All @@ -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

Expand Down
78 changes: 78 additions & 0 deletions tests/test_next_version.py
Original file line number Diff line number Diff line change
@@ -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"}
Loading