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
58 changes: 38 additions & 20 deletions .github/scripts/changelog_guard.py
Original file line number Diff line number Diff line change
Expand Up @@ -10,27 +10,32 @@
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.
changelog, conflict on it or produce one of those duplicates. The later PR is the one that fails,
and its check re-runs by itself whenever that peer changes (see MODE=peers).
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.
MODE=recheck (a push to the base branch that touches the changelog) and MODE=peers (a PR is pushed,
reopened, retargeted, merged or closed; PEER is its number and BASE_BRANCH the branch it targeted):
re-run the latest completed JOB job on each affected open PR, so the PR's own check is the one signal
and the label, a push, or the peer's change clears it. recheck covers every open PR that edits the
changelog; peers covers the higher-numbered ones. A run whose job is still queued or running is left
alone, since it reads the current state when it starts. A failure on one PR is reported and the loop
goes on. Both modes always exit 0, because the push or the peer 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
WORKFLOW (workflow file name, default changelog-guard.yml), JOB (the PR check's job name, default
Check CHANGELOG.md), 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")
JOB = os.environ.get("JOB", "Check CHANGELOG.md")
GH = os.environ.get("GH", "gh")
H2 = re.compile(r"^## \[([^\]]+)\]")
H3 = re.compile(r"^### +(.+?)\s*$")
Expand Down Expand Up @@ -166,29 +171,42 @@ def check_peers(base, head, me, prs):
mine = show(head) or []
for n, _ in sorted(p for p in prs if p[0] < me):
ref = fetch_pr(n)
if not touches(base, ref):
continue
again = f"this check re-runs by itself when #{n} is pushed, retargeted, merged or closed"
tree, conflicts = merge(head, ref)
if CL in conflicts:
errs.append(f"#{me}: {CL} conflicts with open #{n}; update this branch after #{n} merges")
errs.append(f"#{me}: {CL} conflicts with open #{n}; {again}")
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"
errs += [f"#{me}: together with open #{n}, {describe(k)}; {again}"
for k in sorted(dup_keys(show(tree) or [], released) - both, key=str)]
return errs


def api(path):
return json.loads(run(GH, "api", path).stdout)


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")
"""Re-run the PR's newest JOB job on its head commit (only that job, so its own peer re-runs don't
cascade). Runs where the job was skipped, such as a title edit, are passed over. Returns a warning
or None."""
runs = api(f"repos/{repo()}/actions/workflows/{WORKFLOW}/runs"
f"?event=pull_request&head_sha={sha}&per_page=20")["workflow_runs"]
for r in runs: # newest first
jobs = [j for j in api(f"repos/{repo()}/actions/runs/{r['id']}/jobs?per_page=100")["jobs"]
if j["name"] == JOB and j["conclusion"] != "skipped"]
if not jobs:
continue
j = jobs[0]
if j["status"] != "completed":
print(f"#{n}: job {j['id']} is still {j['status']} and reads the current state when it runs")
return None
run(GH, "api", "-X", "POST", f"repos/{repo()}/actions/jobs/{j['id']}/rerun")
print(f"#{n}: re-ran job {j['id']}")
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
return f"#{n}: no {JOB} job on {sha[:7]} to re-run; push to the PR to check it"


def report(errs, warns):
Expand Down
66 changes: 46 additions & 20 deletions .github/scripts/changelog_guard_mutate.py
Original file line number Diff line number Diff line change
@@ -1,39 +1,65 @@
#!/usr/bin/env python3
"""Delete each rule the guard's docstring lists, one at a time, and check a self-test case fails."""
"""Mutate each clause of the guard's docstring, each regex and each API filter, one at a time, and
check that a self-test case fails for every mutant."""
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"),
# Docstring, pr mode: each rule
("conflict with the base fails", " 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 or 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])]", "]"),
("released: blank lines don't count", "if osec[i] in released and old[i].strip() and", "if osec[i] in released and"),
("released: blank lines don't count, new side", "if nsec[j] in released and new[j].strip() and", "if nsec[j] in released and"),
("released means already on the base", "released = sections(old), sections(new), released_of(old)", "released = sections(old), sections(new), released_of(new)"),
("Unreleased is not released", 'if s and s.lower() != "unreleased"}', "if s}"),
("override label", " if allow_released:\n", " if False:\n"),
("override label only covers released edits", " return errs, [f\"{label}: {h} (allowed", " return [], [f\"{label}: {h} (allowed"),
("override label makes them warnings", "(allowed by the {OVERRIDE} label)\" for h in hits]", "(allowed by the {OVERRIDE} label)\" for h in []]"),
("link references never count, old side", "and not LINKREF.match(old[i])]", "]"),
("link references never count, new side", "and not LINKREF.match(new[j])]", "]"),
("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 ### heading in one section", '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)"),
("entry duplicates are per heading", 'k = ("entry", sec, h3, norm(m.group(1)))', 'k = ("entry", sec, None, norm(m.group(1)))'),
("case ignored", '.strip().lower()', ".strip()"),
("spacing ignored", 're.sub(r"\\s+", " ", s)', "s"),
("duplicates already on the base aren't blamed", "dup_keys(new, released) - dup_keys(old, released)", "dup_keys(new, released)"),
("untouched changelog is not checked", "if show(base) is None or not touches(base, head):", "if show(base) is None:"),
("labels read from the API", "OVERRIDE in labels(me)", "False"),
("errors are ::error", 'print(f"::error title=changelog-guard::{e}")', 'print(f"::warning title=changelog-guard::{e}")'),
("pr exits 1 on errors", "sys.exit(1 if errs else 0)", "sys.exit(0)"),
# Docstring, peers
("peer: only lower-numbered", "for p in prs if p[0] < me)", "for p in prs if p[0] != me)"),
("peer: only PRs that edit the changelog", " if not touches(base, ref):\n continue\n", ""),
("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)"),
("peer duplicates the PRs bring alone aren't blamed", "dup_keys(show(tree) or [], released) - both", "dup_keys(show(tree) or [], released)"),
("peer message says the check re-runs by itself", 'again = f"this check re-runs by itself when #{n} is pushed, retargeted, merged or closed"', 'again = f"update this branch after #{n} merges"'),
# Docstring, recheck and peers modes
("recheck covers only PRs that edit the changelog", "if touches(base, fetch_pr(n)) and", "if fetch_pr(n) and"),
("peers covers only higher-numbered PRs", "prs = [p for p in prs if p[0] > int(os.environ[\"PEER\"])]", "pass"),
("a queued or running job is left alone", ' if j["status"] != "completed":\n', ' if j["status"] == "in_progress":\n'),
("only the check job is re-run", 'if j["name"] == JOB and', "if"),
("runs that skipped the check are passed over", ' and j["conclusion"] != "skipped"]', "]"),
("older runs are looked at when the newest skipped", " if not jobs:\n continue\n", " if not jobs:\n break\n"),
("re-run the job, not the whole run", 'f"repos/{repo()}/actions/jobs/{j[\'id\']}/rerun"', 'f"repos/{repo()}/actions/runs/{r[\'id\']}/rerun"'),
("a PR with no check job gets a warning", ' return f"#{n}: no {JOB} job on', ' return None\n return f"#{n}: no {JOB} job on'),
("a failure on one PR doesn't stop the loop", " except (CmdError, KeyError, ValueError) as e:\n warns.append", " except ZeroDivisionError as e:\n warns.append"),
("modes exit 0 when listing fails", " except (CmdError, KeyError, ValueError) as e:\n return report", " except ZeroDivisionError as e:\n return report"),
# Regexes
("H3 strips trailing space", 'H3 = re.compile(r"^### +(.+?)\\s*$")', 'H3 = re.compile(r"^### +(.+)$")'),
("BULLET is top-level only", 'BULLET = re.compile(r"^[-*+]\\s+(.*\\S)")', 'BULLET = re.compile(r"^\\s*[-*+]\\s+(.*\\S)")'),
("LINKREF matches link references", 'LINKREF = re.compile(r"^\\[[^\\]]+\\]:\\s")', 'LINKREF = re.compile(r"^\\[[^\\]]+\\]:\\s{2}")'),
("H2 keys on the bracketed version only", 'H2 = re.compile(r"^## \\[([^\\]]+)\\]")', 'H2 = re.compile(r"^## (.+)")'),
# API filters and paging
("open PRs only", "pulls?state=open&base=", "pulls?state=all&base="),
("PRs into the same base only", "&base={os.environ['BASE_BRANCH']}", ""),
("pull_request runs only", "?event=pull_request&head_sha=", "?head_sha="),
("runs on the PR's head commit only", "&head_sha={sha}&per_page=20", "&per_page=20"),
("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)"),
]


Expand Down
Loading
Loading