diff --git a/.github/scripts/changelog_guard.py b/.github/scripts/changelog_guard.py new file mode 100644 index 0000000..1d36be7 --- /dev/null +++ b/.github/scripts/changelog_guard.py @@ -0,0 +1,244 @@ +#!/usr/bin/env python3 +"""Changelog guard for Keep a Changelog style CHANGELOG.md files. + +MODE=pr (pull_request): exits 1 when merging the PR into the base branch would + - conflict on the changelog, + - add, remove or change a line inside a released section, meaning a `## [x]` heading other than + Unreleased that already exists on the base branch (the override label turns this into a warning; + link reference lines such as `[1.0.0]: https://...` are release bookkeeping and never count), + - add a duplicate `## [x]` heading, a second `### Name` heading in one section, or an entry that + repeats another entry under the same heading (case and spacing ignored; duplicates already on + the base branch are not blamed on the PR), + - or, together with a lower-numbered open PR into the same base branch that also edits the + changelog, conflict on it or produce one of those duplicates. The later PR is the one that fails. + Anything else inside [Unreleased], or inside a section the PR adds, is allowed: new headings, + rewording and removals included. A PR that doesn't touch the changelog is not checked. Labels are + read from the API, so a re-run sees the current ones. + +MODE=recheck (push to the base branch that touches the changelog) and MODE=peers (a PR closed without +merging; PEER is its number): re-run this workflow's latest run on each affected open PR, so the PR's +own check is the one signal and the label, a push or a re-run clears it. recheck covers every open PR +that edits the changelog; peers covers the higher-numbered ones. A failure on one PR is reported and +the loop goes on. Both modes always exit 0, because the push or close is not what's being checked. + +Env: MODE, BASE (commit or ref to merge into), BASE_BRANCH, REPO (owner/name), PR_NUMBER in pr mode, +PEER in peers mode, CHANGELOG (default CHANGELOG.md), OVERRIDE_LABEL (default changelog-override), +WORKFLOW (workflow file name, default changelog-guard.yml), GH (gh binary, default gh), HEAD_REF +(default HEAD). +""" +import difflib, json, os, re, subprocess, sys + +CL = os.environ.get("CHANGELOG", "CHANGELOG.md") +OVERRIDE = os.environ.get("OVERRIDE_LABEL", "changelog-override") +WORKFLOW = os.environ.get("WORKFLOW", "changelog-guard.yml") +GH = os.environ.get("GH", "gh") +H2 = re.compile(r"^## \[([^\]]+)\]") +H3 = re.compile(r"^### +(.+?)\s*$") +BULLET = re.compile(r"^[-*+]\s+(.*\S)") # top-level entries only +LINKREF = re.compile(r"^\[[^\]]+\]:\s") # compare links at the bottom are release bookkeeping + + +class CmdError(Exception): + pass + + +def run(*cmd, ok=(0,)): + p = subprocess.run(cmd, capture_output=True, text=True) + if p.returncode not in ok: + raise CmdError(f"{' '.join(cmd)} failed: {p.stderr.strip()}") + return p + + +def show(rev): + p = run("git", "show", f"{rev}:{CL}", ok=(0, 128)) + return p.stdout.splitlines() if p.returncode == 0 else None + + +def merge(a, b): + p = run("git", "merge-tree", "--write-tree", "--name-only", "--no-messages", a, b, ok=(0, 1)) + out = p.stdout.splitlines() + return out[0], [f for f in out[1:] if f] + + +def touches(base, head): + return run("git", "diff", "--quiet", f"{base}...{head}", "--", CL, ok=(0, 1)).returncode == 1 + + +def sections(lines): + cur, res = None, [] + for l in lines: + m = H2.match(l) + cur = m.group(1) if m else cur + res.append(cur) + return res + + +def released_of(lines): + return {s for s in sections(lines) if s and s.lower() != "unreleased"} + + +def norm(s): + return re.sub(r"\s+", " ", s).strip().lower() + + +def dup_keys(lines, released): + """Duplicate ## headings anywhere; duplicate ### headings and entries inside editable sections.""" + seen, dups, h3 = set(), set(), None + for sec, l in zip(sections(lines), lines): + if (m := H2.match(l)): + k, h3 = ("section", m.group(1)), None + elif sec in released: + continue + elif (m := H3.match(l)): + k, h3 = ("heading", sec, m.group(1)), m.group(1) + elif (m := BULLET.match(l)): + k = ("entry", sec, h3, norm(m.group(1))) + else: + continue + (dups if k in seen else seen).add(k) + return dups + + +def describe(k): + if k[0] == "section": + return f"`## [{k[1]}]` appears twice" + if k[0] == "heading": + return f"`### {k[2]}` appears twice under [{k[1]}]; put the entry under the existing heading" + return f"entry `{k[3][:80]}` appears twice under [{k[1]}]" + + +def check_base(base, head, label, allow_released): + """Diff the base branch's changelog against the merge result. Returns (errors, warnings).""" + tree, conflicts = merge(base, head) + if CL in conflicts: + return [f"{label}: {CL} conflicts with the base branch; update the branch and keep entries under [Unreleased]"], [] + old, new = show(base) or [], show(tree) + if new is None: + return [], [] + osec, nsec, released = sections(old), sections(new), released_of(old) + hits = [] + for tag, i1, i2, j1, j2 in difflib.SequenceMatcher(None, old, new, autojunk=False).get_opcodes(): + if tag == "equal": + continue + hits += [f"changes released section [{osec[i]}] at line {i + 1}: `{old[i].strip()[:100]}`" + for i in range(i1, i2) if osec[i] in released and old[i].strip() and not LINKREF.match(old[i])] + hits += [f"adds a line inside released section [{nsec[j]}]: `{new[j].strip()[:100]}`" + for j in range(j1, j2) if nsec[j] in released and new[j].strip() and not LINKREF.match(new[j])] + errs = [f"{label}: {describe(k)}" for k in sorted(dup_keys(new, released) - dup_keys(old, released), key=str)] + if allow_released: + return errs, [f"{label}: {h} (allowed by the {OVERRIDE} label)" for h in hits] + hint = f" Move it under [Unreleased], or add the {OVERRIDE} label if the edit is intended." + return errs + [f"{label}: {h}.{hint}" for h in hits], [] + + +def gh_json(path): + out = run(GH, "api", "--paginate", path).stdout + dec, i, items = json.JSONDecoder(), 0, [] + while i < len(out): # --paginate prints one JSON array per page back to back + if out[i].isspace(): + i += 1 + continue + page, i = dec.raw_decode(out, i) + items += page + return items + + +def repo(): + return os.environ["REPO"] + + +def open_prs(): + prs = gh_json(f"repos/{repo()}/pulls?state=open&base={os.environ['BASE_BRANCH']}&per_page=100") + return [(p["number"], p["head"]["sha"]) for p in prs] + + +def labels(n): + return {l["name"] for l in gh_json(f"repos/{repo()}/issues/{n}/labels?per_page=100")} + + +def fetch_pr(n): + run("git", "fetch", "-q", "--no-tags", "origin", f"+refs/pull/{n}/head:refs/remotes/pr/{n}") + return f"refs/remotes/pr/{n}" + + +def check_peers(base, head, me, prs): + errs, released = [], released_of(show(base) or []) + mine = show(head) or [] + for n, _ in sorted(p for p in prs if p[0] < me): + ref = fetch_pr(n) + tree, conflicts = merge(head, ref) + if CL in conflicts: + errs.append(f"#{me}: {CL} conflicts with open #{n}; update this branch after #{n} merges") + continue + both = dup_keys(mine, released) | dup_keys(show(ref) or [], released) + errs += [f"#{me}: together with open #{n}, {describe(k)}; update this branch after #{n} merges" + for k in sorted(dup_keys(show(tree) or [], released) - both, key=str)] + return errs + + +def rerun(n, sha): + """Re-run this workflow's latest pull_request run on the PR's head commit. Returns a warning or None.""" + runs = json.loads(run(GH, "api", f"repos/{repo()}/actions/workflows/{WORKFLOW}/runs" + f"?event=pull_request&head_sha={sha}&per_page=1").stdout)["workflow_runs"] + if not runs: + return f"#{n}: no {WORKFLOW} run on {sha[:7]} to re-run; push to the PR to check it" + r = runs[0] + if r["status"] != "completed": + print(f"#{n}: run {r['id']} is still going and checks out the current base branch") + return None + run(GH, "api", "-X", "POST", f"repos/{repo()}/actions/runs/{r['id']}/rerun") + print(f"#{n}: re-ran {WORKFLOW} run {r['id']}") + return None + + +def report(errs, warns): + for w in warns: + print(f"::warning title=changelog-guard::{w}") + for e in errs: + print(f"::error title=changelog-guard::{e}") + if (summary := os.environ.get("GITHUB_STEP_SUMMARY")): + with open(summary, "a") as f: + f.write("### changelog-guard\n\n" + ("\n".join(f"- {x}" for x in errs + warns) or "No changelog problems.") + "\n") + + +def pr_mode(base): + head, me = os.environ.get("HEAD_REF", "HEAD"), int(os.environ["PR_NUMBER"]) + if show(base) is None or not touches(base, head): + return print(f"{CL} not changed by #{me}, nothing to check") + errs, warns = check_base(base, head, f"#{me}", OVERRIDE in labels(me)) + errs += check_peers(base, head, me, open_prs()) + report(errs, warns) + sys.exit(1 if errs else 0) + + +def rerun_mode(base, mode): + """Re-run the guard on affected open PRs. Never fails: the problems belong to the PRs.""" + warns = [] + try: + prs = open_prs() + if mode == "peers": + prs = [p for p in prs if p[0] > int(os.environ["PEER"])] + except (CmdError, KeyError, ValueError) as e: + return report([], [f"could not list open PRs: {e}"]) + for n, sha in sorted(prs): + try: + if touches(base, fetch_pr(n)) and (w := rerun(n, sha)): + warns.append(w) + except (CmdError, KeyError, ValueError) as e: + warns.append(f"#{n}: could not re-run the check: {e}") + report([], warns) + + +def main(): + base, mode = os.environ["BASE"], os.environ.get("MODE", "pr") + if mode == "pr": + try: + pr_mode(base) + except CmdError as e: + sys.exit(f"changelog-guard could not run: {e}") + else: + rerun_mode(base, mode) + + +if __name__ == "__main__": + main() diff --git a/.github/scripts/changelog_guard_mutate.py b/.github/scripts/changelog_guard_mutate.py new file mode 100644 index 0000000..3b2b0ce --- /dev/null +++ b/.github/scripts/changelog_guard_mutate.py @@ -0,0 +1,58 @@ +#!/usr/bin/env python3 +"""Delete each rule the guard's docstring lists, one at a time, and check a self-test case fails.""" +import shutil, subprocess, sys, tempfile +from pathlib import Path + +SRC = Path(__file__).resolve().parent +M = [ + ("base conflict", " if CL in conflicts:\n return [f\"{label}: {CL} conflicts with the base branch", " if False:\n return [f\"{label}: {CL} conflicts with the base branch"), + ("released: changed/removed line", "for i in range(i1, i2) if osec[i] in released", "for i in range(i1, i2) if False"), + ("released: added line", "for j in range(j1, j2) if nsec[j] in released", "for j in range(j1, j2) if False"), + ("LINKREF exclusion, old side", "and not LINKREF.match(old[i])]", "]"), + ("LINKREF exclusion, new side", "and not LINKREF.match(new[j])]", "]"), + ("Unreleased is not released", 'if s and s.lower() != "unreleased"}', "if s}"), + ("override label", " if allow_released:\n", " if False:\n"), + ("duplicate ## heading", 'k, h3 = ("section", m.group(1)), None', "continue"), + ("duplicate ### heading", 'k, h3 = ("heading", sec, m.group(1)), m.group(1)', "h3 = m.group(1)\n continue"), + ("duplicate entry", 'k = ("entry", sec, h3, norm(m.group(1)))', "continue"), + ("norm lowercasing", '.strip().lower()', ".strip()"), + ("norm whitespace", 're.sub(r"\\s+", " ", s)', "s"), + ("base-duplicate subtraction", "dup_keys(new, released) - dup_keys(old, released)", "dup_keys(new, released)"), + ("peer: only lower-numbered", "for p in prs if p[0] < me)", "for p in prs if p[0] != me)"), + ("peer conflict", " if CL in conflicts:\n errs.append", " if False:\n errs.append"), + ("peer duplicates", "for k in sorted(dup_keys(show(tree) or [], released) - both, key=str)]", "for k in []]"), + ("peer duplicate subtraction", "dup_keys(show(tree) or [], released) - both", "dup_keys(show(tree) or [], released)"), + ("pagination", " page, i = dec.raw_decode(out, i)\n items += page", " items += json.loads(out[i:])\n break"), + ("three-dot diff range", 'f"{base}...{head}"', 'f"{base}..{head}"'), + ("base filter on PR listing", "&base={os.environ['BASE_BRANCH']}", ""), + ("labels read from the API", "OVERRIDE in labels(me)", "False"), + ("pr skips untouched changelog", "if show(base) is None or not touches(base, head):", "if show(base) is None:"), + ("recheck skips PRs not touching the changelog", "if touches(base, fetch_pr(n)) and", "if fetch_pr(n) and"), + ("recheck keeps going past a failure", " except (CmdError, KeyError, ValueError) as e:\n warns.append", " except ZeroDivisionError as e:\n warns.append"), + ("recheck exits 0 when listing fails", " except (CmdError, KeyError, ValueError) as e:\n return report", " except ZeroDivisionError as e:\n return report"), + ("rerun skips runs still going", 'if r["status"] != "completed":', "if False:"), + ("rerun reports a PR with no run", " if not runs:\n return f", " if not runs:\n return None\n return f"), + ("peers: only higher-numbered", "prs = [p for p in prs if p[0] > int(os.environ[\"PEER\"])]", "pass"), + ("pr exits 1 on errors", "sys.exit(1 if errs else 0)", "sys.exit(0)"), +] + + +def main(): + src = (SRC / "changelog_guard.py").read_text() + survived = [] + for name, old, new in M: + if src.count(old) != 1: + sys.exit(f"mutant '{name}': pattern found {src.count(old)} times") + with tempfile.TemporaryDirectory() as d: + shutil.copy(SRC / "changelog_guard_test.py", d) + Path(d, "changelog_guard.py").write_text(src.replace(old, new)) + p = subprocess.run([sys.executable, "-I", "changelog_guard_test.py"], cwd=d, capture_output=True, text=True) + killed = p.returncode != 0 + print(f"{'killed ' if killed else 'SURVIVED'} {name}") + survived += [] if killed else [name] + print(f"{len(M) - len(survived)} of {len(M)} mutants killed") + sys.exit(1 if survived else 0) + + +if __name__ == "__main__": + main() diff --git a/.github/scripts/changelog_guard_test.py b/.github/scripts/changelog_guard_test.py new file mode 100644 index 0000000..7ef5b9f --- /dev/null +++ b/.github/scripts/changelog_guard_test.py @@ -0,0 +1,280 @@ +#!/usr/bin/env python3 +"""Fixture tests for changelog_guard.py. + +Each case builds a throwaway origin repo with refs/pull/N/head refs and a stub `gh` that serves the +open-PR listing (split over two pages and filtered by base branch, like the API), each PR's labels and +its latest workflow run, and records re-run requests. The guard then runs end to end: merge-tree, the +PR listing, the refs/pull fetch and the re-run call all run for real against the fixture. +""" +import json, os, subprocess, sys, tempfile, textwrap, unittest +from pathlib import Path +from urllib.parse import parse_qs, urlsplit + +GUARD = Path(__file__).with_name("changelog_guard.py").resolve() +BASE_CL = """\ +# Changelog + +## [Unreleased] + +### Added +- Existing feature + +### Fixed +- Existing fix + +## [1.0.0] - 2026-01-01 + +### Added +- First release + +[Unreleased]: https://example.com/compare/v1.0.0...HEAD +[1.0.0]: https://example.com/releases/v1.0.0 +""" +STUB = r'''#!/usr/bin/env python3 +import json, os, sys +from urllib.parse import parse_qs, urlsplit +args = sys.argv[1:] +state = json.load(open(os.environ["STUB_STATE"])) +path = [a for a in args if a.startswith("repos/")][0] +u = urlsplit(path) +q = {k: v[0] for k, v in parse_qs(u.query).items()} +parts = u.path.split("/") +if "-X" in args: + with open(os.environ["STUB_LOG"], "a") as f: + f.write(u.path + "\n") + print("{}") +elif parts[3] == "pulls": + prs = [{"number": p["number"], "head": {"sha": p["sha"]}} for p in state["prs"] + if p["state"] == q["state"] and p["base"] == q["base"]] + half = len(prs) // 2 + print(json.dumps(prs[:half]) + "\n" + json.dumps(prs[half:])) # two pages, like gh api --paginate +elif parts[3] == "issues": + p = [p for p in state["prs"] if p["number"] == int(parts[4])][0] + print(json.dumps([{"name": l} for l in p["labels"]])) +elif parts[3] == "actions": + runs = [{"id": 1000 + p["number"], "status": p.get("run", "completed")} for p in state["prs"] + if p["sha"] == q["head_sha"] and p.get("run", "completed") != "none"] + print(json.dumps({"workflow_runs": runs[:1]})) +else: + sys.exit(f"unexpected call {args}") +''' + + +def sh(cwd, *cmd): + return subprocess.run(cmd, cwd=cwd, check=True, capture_output=True, text=True).stdout.strip() + + +class Fixture: + def __init__(self, tmp, base_cl=BASE_CL): + self.root = Path(tmp) + self.origin, self.work = self.root / "origin.git", self.root / "work" + sh(self.root, "git", "init", "-q", "--bare", "-b", "main", str(self.origin)) + sh(self.root, "git", "clone", "-q", str(self.origin), str(self.work)) + for k, v in (("user.name", "t"), ("user.email", "t@example.com"), ("commit.gpgsign", "false")): + sh(self.work, "git", "config", k, v) + self.commit("main", base_cl, "base", new=True) + self.prs, self.log, self.state = [], self.root / "calls.log", self.root / "state.json" + stub = self.root / "gh" + stub.write_text(STUB) + stub.chmod(0o755) + self.gh = str(stub) + + def commit(self, branch, text, msg, new=False, start="main", path="CHANGELOG.md"): + if not new: + sh(self.work, "git", "checkout", "-q", "-B", branch, f"origin/{start}") + (self.work / path).write_text(textwrap.dedent(text)) + sh(self.work, "git", "add", "-A") + sh(self.work, "git", "commit", "-q", "-m", msg) + sh(self.work, "git", "push", "-q", "origin", f"HEAD:refs/heads/{branch}") + return sh(self.work, "git", "rev-parse", "HEAD") + + def pr(self, n, text, labels=(), base="main", path="CHANGELOG.md", push_ref=True, run="completed"): + sha = self.commit(f"pr{n}", text, f"pr {n}", start=base, path=path) + if push_ref: + sh(self.work, "git", "push", "-q", "origin", f"HEAD:refs/pull/{n}/head") + self.prs.append({"number": n, "sha": sha, "labels": list(labels), "base": base, "state": "open", "run": run}) + return sha + + def get(self, n): + return [p for p in self.prs if p["number"] == n][0] + + def run(self, mode, n=None, **extra): + self.state.write_text(json.dumps({"prs": self.prs})) + sh(self.work, "git", "fetch", "-q", "origin") + env = dict(os.environ, MODE=mode, BASE="origin/main", BASE_BRANCH="main", REPO="o/r", GH=self.gh, + STUB_STATE=str(self.state), STUB_LOG=str(self.log)) + env.update(extra) + env.pop("GITHUB_STEP_SUMMARY", None) + if n is not None: + env.update(PR_NUMBER=str(n), HEAD_REF=f"origin/pr{n}") + return subprocess.run([sys.executable, str(GUARD)], cwd=self.work, env=env, capture_output=True, text=True) + + def reruns(self): + if not self.log.exists(): + return set() + return {int(l.split("/")[-2]) - 1000 for l in self.log.read_text().splitlines() if l.endswith("/rerun")} + + +def add_unreleased(entry, heading="### Fixed", base=BASE_CL): + return base.replace(f"{heading}\n", f"{heading}\n{entry}\n", 1) + + +class GuardTest(unittest.TestCase): + base_cl = BASE_CL + + def setUp(self): + self._tmp = tempfile.TemporaryDirectory() + self.f = Fixture(self._tmp.name, self.base_cl) + + def tearDown(self): + self._tmp.cleanup() + + def assertPass(self, p): + self.assertEqual(p.returncode, 0, p.stdout + p.stderr) + + def assertFail(self, p, needle): + self.assertEqual(p.returncode, 1, p.stdout + p.stderr) + self.assertIn(needle, p.stdout) + + # Allowed edits + def test_entry_under_unreleased_passes(self): + self.f.pr(1, add_unreleased("- New fix")) + self.assertPass(self.f.run("pr", 1)) + + def test_rewording_in_unreleased_passes(self): + self.f.pr(1, BASE_CL.replace("- Existing fix\n", "- Existing fix, reworded\n")) + self.assertPass(self.f.run("pr", 1)) + + def test_removal_in_unreleased_passes(self): + self.f.pr(1, BASE_CL.replace("- Existing fix\n", "")) + self.assertPass(self.f.run("pr", 1)) + + def test_new_heading_passes(self): + self.f.pr(1, BASE_CL.replace("- Existing fix\n", "- Existing fix\n\n### Security\n- New\n")) + self.assertPass(self.f.run("pr", 1)) + + def test_release_pr_updating_link_references_passes(self): + released = (BASE_CL.replace("## [Unreleased]\n", "## [Unreleased]\n\n## [1.1.0] - 2026-02-01\n", 1) + .replace("compare/v1.0.0...HEAD", "compare/v1.1.0...HEAD") + .replace("[1.0.0]: ", "[1.1.0]: https://example.com/releases/v1.1.0\n[1.0.0]: ")) + self.f.pr(1, released) + self.assertPass(self.f.run("pr", 1)) + + def test_untouched_changelog_skips_even_after_base_moved(self): + self.f.pr(1, "x", path="x.txt") + self.f.commit("main", add_unreleased("- Landed meanwhile"), "main moves") + p = self.f.run("pr", 1) + self.assertPass(p) + self.assertIn("nothing to check", p.stdout) + + def test_duplicates_already_on_base_are_not_blamed(self): + dup = BASE_CL.replace("- Existing fix\n", "- Existing fix\n- Existing fix\n") + self.f.commit("main", dup, "base has a duplicate") + self.f.pr(1, add_unreleased("- New fix", base=dup)) + self.f.pr(2, add_unreleased("- Other", heading="### Added", base=dup)) + self.assertPass(self.f.run("pr", 1)) + self.assertPass(self.f.run("pr", 2)) + + # Rejected edits + def test_released_edit_fails_and_label_overrides(self): + self.f.pr(1, BASE_CL.replace("- First release", "- First release, reworded")) + self.assertFail(self.f.run("pr", 1), "changes released section [1.0.0]") + self.f.get(1)["labels"] = ["other", "changelog-override"] + p = self.f.run("pr", 1) + self.assertPass(p) + self.assertIn("::warning", p.stdout) + + def test_line_added_to_released_section_fails(self): + self.f.pr(1, BASE_CL.replace("- First release\n", "- First release\n- Late addition\n")) + self.assertFail(self.f.run("pr", 1), "adds a line inside released section [1.0.0]") + + def test_conflict_with_base_fails(self): + self.f.pr(1, BASE_CL.replace("- Existing fix", "- Fix A")) + self.f.commit("main", BASE_CL.replace("- Existing fix", "- Fix B"), "main edits the same line") + self.assertFail(self.f.run("pr", 1), "conflicts with the base branch") + + def test_duplicate_heading_fails(self): + self.f.pr(1, BASE_CL.replace("- Existing fix\n", "- Existing fix\n\n### Fixed\n- Another\n")) + self.assertFail(self.f.run("pr", 1), "`### Fixed` appears twice") + + def test_duplicate_version_heading_fails(self): + self.f.pr(1, BASE_CL.replace("## [Unreleased]\n", "## [Unreleased]\n\n## [1.0.0] - 2026-02-01\n", 1)) + self.assertFail(self.f.run("pr", 1), "`## [1.0.0]` appears twice") + + def test_duplicate_entry_fails_ignoring_case(self): + self.f.pr(1, add_unreleased("- existing FIX")) + self.assertFail(self.f.run("pr", 1), "appears twice under [Unreleased]") + + # Peers + def test_later_colliding_pr_fails_earlier_passes(self): + self.f.pr(1, add_unreleased("- Fix A")) + self.f.pr(2, add_unreleased("- Fix B")) + self.f.pr(3, "x", path="x.txt") # a third PR keeps both listing pages non-empty + self.assertPass(self.f.run("pr", 1)) + self.assertFail(self.f.run("pr", 2), "conflicts with open #1") + + def test_peers_that_merge_cleanly_into_a_duplicate_heading_fail(self): + self.f.pr(1, BASE_CL.replace("### Fixed\n", "### Security\n- A\n\n### Fixed\n")) + self.f.pr(2, BASE_CL.replace("- Existing fix\n", "- Existing fix\n\n### Security\n- B\n")) + self.assertPass(self.f.run("pr", 1)) + self.assertFail(self.f.run("pr", 2), "together with open #1, `### Security` appears twice") + + def test_peer_into_another_base_branch_is_ignored(self): + sh(self.f.work, "git", "push", "-q", "origin", "origin/main:refs/heads/release") + self.f.pr(1, add_unreleased("- Fix A"), base="release") + self.f.pr(2, add_unreleased("- Fix B")) + self.assertPass(self.f.run("pr", 2)) + + # Every failure clears through its remedy, with the PR's own check as the one signal + def test_release_push_reruns_affected_pr_then_label_clears_it(self): + self.f.pr(1, add_unreleased("- Pending fix")) + self.f.pr(2, "x", path="x.txt") + self.assertPass(self.f.run("pr", 1)) + released = BASE_CL.replace("## [Unreleased]\n", "## [Unreleased]\n\n## [1.1.0] - 2026-02-01\n", 1) + self.f.commit("main", released, "Release 1.1.0") + self.assertPass(self.f.run("recheck")) + self.assertEqual(self.f.reruns(), {1}) # #2 doesn't touch the changelog + self.assertFail(self.f.run("pr", 1), "released section [1.1.0]") # the re-run goes red + self.f.get(1)["labels"] = ["changelog-override"] + self.assertPass(self.f.run("pr", 1)) # the labeled run is green on the same check + + def test_closing_a_peer_reruns_later_prs_and_clears_them(self): + self.f.pr(1, add_unreleased("- Fix A")) + self.f.pr(2, add_unreleased("- Fix B")) + self.f.pr(3, add_unreleased("- Fix C")) + self.assertFail(self.f.run("pr", 2), "conflicts with open #1") + self.f.get(1)["state"] = "closed" + self.assertPass(self.f.run("peers", PEER="1")) + self.assertEqual(self.f.reruns(), {2, 3}) + self.assertPass(self.f.run("pr", 2)) + + def test_closing_a_peer_leaves_lower_numbered_prs_alone(self): + self.f.pr(1, add_unreleased("- Fix A")) + self.f.pr(2, add_unreleased("- Fix B", heading="### Added")) + self.f.pr(3, BASE_CL.replace("# Changelog\n", "# Changelog\n\nIntro.\n")) + self.f.get(2)["state"] = "closed" + self.assertPass(self.f.run("peers", PEER="2")) + self.assertEqual(self.f.reruns(), {3}) + + # Recheck never fails and never stops at the first PR + def test_recheck_survives_a_failed_fetch_and_a_missing_run(self): + self.f.pr(1, add_unreleased("- Fix A")) + self.f.pr(2, add_unreleased("- Fix B", heading="### Added"), push_ref=False) # fetch fails + self.f.pr(3, BASE_CL.replace("# Changelog\n", "# Changelog\n\nIntro.\n")) + self.f.pr(4, BASE_CL.replace("- First release", "- First"), run="none") + self.f.pr(5, BASE_CL.replace("[1.0.0]: ", "[1.0.0]: "), run="in_progress") + p = self.f.run("recheck") + self.assertPass(p) + self.assertEqual(self.f.reruns(), {1, 3}) + self.assertIn("#2: could not re-run", p.stdout) + self.assertIn("#4: no changelog-guard.yml run", p.stdout) + + def test_recheck_exits_zero_when_listing_fails(self): + self.f.pr(1, add_unreleased("- Fix A")) + p = self.f.run("recheck", GH="/bin/false") + self.assertPass(p) + self.assertIn("could not list open PRs", p.stdout) + + +if __name__ == "__main__": + unittest.main(verbosity=2) diff --git a/.github/workflows/changelog-guard.yml b/.github/workflows/changelog-guard.yml new file mode 100644 index 0000000..b58e237 --- /dev/null +++ b/.github/workflows/changelog-guard.yml @@ -0,0 +1,66 @@ +name: Changelog guard + +on: + pull_request: + types: [opened, synchronize, reopened, labeled, unlabeled, closed] + push: + branches: [main, master] + paths: [CHANGELOG.md] + +permissions: {} + +concurrency: + group: changelog-guard-${{ github.event.pull_request.number || github.ref }}${{ github.event.action == 'closed' && '-closed' || '' }} + cancel-in-progress: true + +jobs: + pr: + name: Check CHANGELOG.md + if: github.event_name == 'pull_request' && github.event.action != 'closed' + runs-on: ubuntu-latest + permissions: + contents: read + pull-requests: read # list open PRs and this PR's labels + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + fetch-depth: 0 + persist-credentials: false + ref: ${{ github.event.pull_request.head.sha }} + - name: Self-test + run: python3 .github/scripts/changelog_guard_test.py + - name: Run changelog guard + env: + GH_TOKEN: ${{ github.token }} + REPO: ${{ github.repository }} + MODE: pr + BASE: origin/${{ github.base_ref }} + BASE_BRANCH: ${{ github.base_ref }} + PR_NUMBER: ${{ github.event.pull_request.number }} + run: python3 .github/scripts/changelog_guard.py + + recheck: + name: Recheck open PRs + if: >- + (github.event_name == 'push' && github.ref_name == github.event.repository.default_branch) || + (github.event.action == 'closed' && !github.event.pull_request.merged) + runs-on: ubuntu-latest + permissions: + contents: read + pull-requests: read # list open PRs + actions: write # re-run each affected PR's own changelog check + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + fetch-depth: 0 + persist-credentials: false + ref: ${{ github.event.repository.default_branch }} + - name: Re-run the check on affected open PRs + env: + GH_TOKEN: ${{ github.token }} + REPO: ${{ github.repository }} + MODE: ${{ github.event_name == 'push' && 'recheck' || 'peers' }} + BASE: ${{ github.event_name == 'push' && github.sha || format('origin/{0}', github.event.pull_request.base.ref) }} + BASE_BRANCH: ${{ github.event_name == 'push' && github.ref_name || github.event.pull_request.base.ref }} + PEER: ${{ github.event.pull_request.number }} + run: python3 .github/scripts/changelog_guard.py