From 328e41e03789e5de4b2794519abc30728d853f9e Mon Sep 17 00:00:00 2001 From: Andrey Antukh Date: Mon, 16 Nov 2026 09:17:27 +0000 Subject: [PATCH] :recycle: Stop excluding release blocker from the changelog flow The `release blocker` label marks work that blocks the release; it is not a signal about whether users will notice a change. Drop it from the changelog exclusions and keep only `no changelog`. Closed bugs carrying `release blocker` are analyzed by `dev-only-bugs` like any other bug: a bug found while testing an unreleased feature never reached production, so the tool is the right filter for them. Closed non-bug issues with the label are surfaced by a manual review step in the flow: `gh.py issues --label "release blocker"` lists them and the user decides between `no changelog` and keeping the entry. Update the memories, the update-changelog skill and the tests to match. AI-assisted-by: inkling-2-small-free --- .agents/skills/update-changelog/SKILL.md | 3 ++- .serena/memories/scripts/changelog.md | 4 ++-- .serena/memories/scripts/gh.md | 2 +- .serena/memories/workflow/updating-changelog.md | 9 +++++---- scripts/changelog.py | 7 ++++--- scripts/gh.py | 4 ++-- scripts/test_changelog.py | 14 +++++++++++--- 7 files changed, 27 insertions(+), 16 deletions(-) diff --git a/.agents/skills/update-changelog/SKILL.md b/.agents/skills/update-changelog/SKILL.md index 87c493e7c4..0c5ca79f23 100644 --- a/.agents/skills/update-changelog/SKILL.md +++ b/.agents/skills/update-changelog/SKILL.md @@ -37,7 +37,8 @@ memory; it does not repeat it. ## Commands ```bash -python3 scripts/gh.py issues "" --exclude "release blocker,no changelog" +python3 scripts/gh.py issues "" --exclude "no changelog" +python3 scripts/gh.py issues "" --label "release blocker" --exclude "no changelog" # closed non-bug residue to review by hand python3 scripts/gh.py advisories --patched-version "" python3 scripts/changelog.py dev-only-bugs "" # list bugs that never reached production python3 scripts/changelog.py dev-only-bugs "" --apply # label the sure ones `no changelog` diff --git a/.serena/memories/scripts/changelog.md b/.serena/memories/scripts/changelog.md index 6785692d82..b6cf2115a8 100644 --- a/.serena/memories/scripts/changelog.md +++ b/.serena/memories/scripts/changelog.md @@ -8,7 +8,7 @@ - `boom [--changes CHANGES.md --write]` — generate `### :boom: Breaking changes & Deprecations` from the closed, non-excluded milestone issues labelled `breaking change`, sorted by issue number. Each issue becomes a `#### ` block: content = body of the issue's last `## Breaking change note` comment (whole markdown, headings demoted to `#####` outside code fences; fallback = heading plus refs with a stderr warning), refs = issue link plus merged closing PRs on their own line, with `(by @author)` for `community contribution`. `--write` replaces only that subsection of the version (inserts it after the version header when missing, keeps the heading when there are no entries; idempotent). Print-only by default. Uses `gh.py comments`. - `security [--changes CHANGES.md --write]` — generate `### :lock: Security fixes` from the advisories whose `patched_versions` include the version (via `gh.py advisories --patched-version`), sorted by GHSA id. Entry: `- Fix () (PR: [#N](...))`; description = `Fix` + advisory summary, first word decapitalized unless it starts with an acronym; PRs = merged milestone PRs labelled `pr pt` whose body contains the GHSA id, comma-separated, and no PR is legal. Warns on stderr when a `pr pt` PR references an advisory with no matching `patched_versions`. `--write` replaces only that subsection, placed after `:rocket:` (or `:boom:`, or the version header when neither exists); empty entries remove the subsection; idempotent. Print-only by default. - `cross-ref [--changes CHANGES.md]` — fetch milestone PRs with `--state all` once, report merged PRs missing from the version section plus CLOSED (unmerged) warnings. PR links inside `:lock:` entries count as referenced; advisory URLs never appear here by design. -- `dev-only-bugs [--apply]` — list closed milestone bugs that never reached production, without `no changelog`. Sure: parent issue is a `Feature`/`Enhancement` of the same milestone; `--apply` adds `no changelog` to these only. Candidates (never labelled automatically): parent is an epic of the milestone, `regression` label, or the "Affected versions" / "Environment" body field names only hourly, develop, staging, PRE or this milestone (`only_unreleased_envs`; any production hint or other version keeps the bug in). Reads `body` and `parent` from one batched `gh.py issue` lookup. +- `dev-only-bugs [--apply]` — list closed milestone bugs that never reached production, without `no changelog` (bugs carrying `release blocker` are analyzed too). Sure: parent issue is a `Feature`/`Enhancement` of the same milestone; `--apply` adds `no changelog` to these only. Candidates (never labelled automatically): parent is an epic of the milestone, `regression` label, or the "Affected versions" / "Environment" body field names only hourly, develop, staging, PRE or this milestone (`only_unreleased_envs`; any production hint or other version keeps the bug in). Reads `body` and `parent` from one batched `gh.py issue` lookup. - `report [--changes CHANGES.md --output CHANGES-ISSUES.md]` — overwrite the anomaly report: A/B milestone mismatches, E `:boom:` entry without the label, F `:rocket:` sync, G `:boom:` sync, plus the C/D `:rocket:` gaps and the `dev-only-bugs` lists (warnings). `:boom:`/`:rocket:` rule violations are fixed by regenerating or relabelling, not by editing entries in place. ## Conventions @@ -19,4 +19,4 @@ - PR/issue reference parsing covers standard `[#N](.../pull/N)` / `[#N](.../issues/N)` links plus legacy `PR:[N]` / `[Github #N]` forms. - Shared parsing helpers (`extract_version_section`, `extract_subsection`, `collect_changelog_prs/issues`) live at module top so future subcommands reuse them instead of duplicating regexes. - Report anomaly types: A/B milestone mismatches, E `:boom:` entry whose issue lacks the `breaking change` label (counted, entries preserved — human labels the issue or moves the entry), G `breaking change` issue missing from `:boom:` (counted, same contract as F); C/D are `:rocket:` gaps (warnings, never counted). -- `issue_excluded` (closed, non-Task, non-Rejected, no `release blocker`/`no changelog` label) is module-level and shared by `report` and `boom` so the exclusions cannot drift. +- `issue_excluded` (closed, non-Task, non-Rejected, no `no changelog` label) is module-level and shared by `report` and `boom` so the exclusions cannot drift. diff --git a/.serena/memories/scripts/gh.md b/.serena/memories/scripts/gh.md index 6b546e578c..d9775f3d82 100644 --- a/.serena/memories/scripts/gh.md +++ b/.serena/memories/scripts/gh.md @@ -40,7 +40,7 @@ python3 scripts/gh.py issues "2.16.0" --label "bug" python3 scripts/gh.py issues "2.16.0" --label "bug,regression" # Exclude by label -python3 scripts/gh.py issues "2.16.0" --exclude "release blocker,no changelog" +python3 scripts/gh.py issues "2.16.0" --exclude "no changelog" # Show only issues NOT yet in CHANGES.md python3 scripts/gh.py issues "2.16.0" --compare CHANGES.md diff --git a/.serena/memories/workflow/updating-changelog.md b/.serena/memories/workflow/updating-changelog.md index 6cf4134d1a..909b821006 100644 --- a/.serena/memories/workflow/updating-changelog.md +++ b/.serena/memories/workflow/updating-changelog.md @@ -28,7 +28,7 @@ Editing `CHANGES.md` happens only on explicit request or as part of the release - **Security fixes come from advisories**: an advisory whose `patched_versions` include the version becomes a `:lock:` entry (section 7). `triage`, `draft` and `published` are all valid states; the advisory may still be unpublished when the changelog is written. A security fix may also carry a regular bug issue; both entries are legal and independent (the issue lives in `:bug:` as any other bug). - **Two labels override the Issue Type**: `breaking change` → an entry only under `:boom:`, never in its regular section; `release highlight` → an extra entry under `:rocket:` on top of its regular entry. - **Only closed issues**. An open issue in the milestone is not generated, even if someone added a provisional entry by hand before the merge. -- **Excluded issues**: `no changelog`, `release blocker`, `Task` issue type, `Rejected` project status. +- **Excluded issues**: `no changelog`, `Task` issue type, `Rejected` project status. `release blocker` is a workflow label (the issue blocks the release), not a changelog exclusion: bugs carrying it are analyzed by `dev-only-bugs` (section 8, step 3), and closed non-bug issues carrying it are reviewed by hand (section 8, step 3). - **Bugs that never reached production** stay out: a bug found and fixed while building a feature of the same, unreleased version never affected users. The team rarely labels them, so the flow finds them with `dev-only-bugs` and labels them `no changelog` (section 8, step 3). - **Excluded PRs**: a PR with `release blocker` or `no issue required` does not bring an entry of its own. - **An issue with no milestone** belongs to another (probably private) project: it is neither changelog candidate nor anomaly. @@ -159,10 +159,11 @@ Generated from the advisories that declare the version in `patched_versions`; ne ## 8. Flow 1. **Confirm the version** (a semver string such as `2.19.0`) with the user when it is not obvious. -2. **Fetch the milestone issues**: `python3 scripts/gh.py issues "" --exclude "release blocker,no changelog"` (closed by default; add `--state all` only to inspect open issues). `gh.py` already drops `Task` and `Rejected`; pass `--include-tasks` / `--include-rejected` only to inspect them. To find what is missing from an existing section, add `--compare CHANGES.md`. -3. **Keep out bugs that never reached production**: `python3 scripts/changelog.py dev-only-bugs ""` lists them; add `--apply` to label the sure ones `no changelog` on GitHub, then re-fetch step 2. The label puts the decision on the issue, so it survives a regeneration. +2. **Fetch the milestone issues**: `python3 scripts/gh.py issues "" --exclude "no changelog"` (closed by default; add `--state all` only to inspect open issues). `gh.py` already drops `Task` and `Rejected`; pass `--include-tasks` / `--include-rejected` only to inspect them. To find what is missing from an existing section, add `--compare CHANGES.md`. +3. **Keep out bugs that never reached production**: `python3 scripts/changelog.py dev-only-bugs ""` lists them; add `--apply` to label the sure ones `no changelog` on GitHub, then re-fetch step 2. The label puts the decision on the issue, so it survives a regeneration. Bugs carrying `release blocker` are analyzed like any other bug. - **Sure**: a bug whose parent issue is a `Feature` or `Enhancement` of the same milestone. `--apply` labels these. - **Candidates**: a bug whose parent is an epic of the same milestone, that carries the `regression` label, or whose "Affected versions" / "Environment" field names only hourly, develop, staging, PRE or a version of this milestone. `regression` also marks regressions users hit in production, and the field says where the bug was seen, not since when it exists, so never label these yourself: show them to the user, who labels the ones they confirm. The anomaly report lists them too (section 10). + - **Closed non-bug issues carrying `release blocker`** have no automatic check: `python3 scripts/gh.py issues "" --label "release blocker" --exclude "no changelog"` lists them (closed, non-Task). Show them to the user: the internal ones get the `no changelog` label, the rest keep their entry. 4. **Fetch PR details when needed**: `python3 scripts/gh.py prs ` (also `--milestone`). Use it for the PR author, labels and merge state. 5. **Categorize** by Issue Type and the two labels (section 2), and **build the descriptions** (section 4). 6. **Verify PR merge status** before writing: `python3 scripts/changelog.py check-merged `. Only merged PRs go in the changelog; if a closing PR was closed unmerged, look for the PR that superseded it. @@ -179,7 +180,7 @@ Re-fetch the milestone (do not trust cached data) and fix these in `CHANGES.md` 1. **Duplicate across versions** → remove it from the current section; the earlier version wins for backports. The same holds after merging a patch branch into `staging`: the fix keeps its released patch entry and leaves the newer, unreleased section (the merge conflict in `CHANGES.md` is resolved by keeping both sections, newest first, minus the duplicate). 2. **Stale milestone assignment** (the issue moved out of this milestone) → remove the entry. -3. **Newly applied exclusion labels** (`no changelog`, `release blocker`) → remove the entry. +3. **Newly applied exclusion labels** (`no changelog`) → remove the entry. (`release blocker` is not an exclusion label; it never removes an entry by itself.) 4. **Issue no longer closed, deleted, or now `Rejected`** → remove the entry. 5. **Unmerged or moved PR reference** → fix the reference or remove the entry. A PR merged in a different milestone is an anomaly (section 10); do not remove it silently. 6. **Issue Type changed** → to `Task`: remove the entry; to another type: move the entry to that type's section. diff --git a/scripts/changelog.py b/scripts/changelog.py index e09cfa1218..9937f003f6 100644 --- a/scripts/changelog.py +++ b/scripts/changelog.py @@ -45,7 +45,7 @@ GH_PY = Path(__file__).resolve().parent / "gh.py" BOOM_HEADING = "### :boom: Breaking changes & Deprecations" SECURITY_HEADING = "### :lock: Security fixes" BREAKING_LABEL = "breaking change" -EXCLUDED_LABELS = {"release blocker", "no changelog"} +EXCLUDED_LABELS = {"no changelog"} # PR label carried by the security fixes that reference their advisory in the # PR body, and the GHSA id pattern used to find that reference. @@ -658,14 +658,15 @@ def find_dev_only_bugs(milestone: str, issues: list[dict]) -> tuple[list[dict], """Split the milestone's changelog bugs that never reached production. ``issues`` come from ``gh.py issue`` (they carry ``body`` and - ``parent``). Returns ``(auto, suggested)``: ``auto`` bugs are + ``parent``). Bugs labelled ``release blocker`` are analyzed like any + other bug. Returns ``(auto, suggested)``: ``auto`` bugs are sub-issues of a Feature or Enhancement of this milestone and get the `no changelog` label; ``suggested`` ones need a human to confirm.""" auto, suggested = [], [] for issue in issues: if issue.get("issue_type") != "Bug" or issue.get("state") != "CLOSED": continue - if {"no changelog", "release blocker"} & set(issue.get("labels", [])): + if "no changelog" in set(issue.get("labels", [])): continue parent = issue.get("parent") or {} entry = {"issue": issue["number"], "issue_title": issue.get("title", "")} diff --git a/scripts/gh.py b/scripts/gh.py index 30c12e58f2..a94c5be8fb 100755 --- a/scripts/gh.py +++ b/scripts/gh.py @@ -15,7 +15,7 @@ Subcommands: Usage: python3 scripts/gh.py issues (default: state=closed) python3 scripts/gh.py issues "2.16.0" --state all - python3 scripts/gh.py issues "2.16.0" --exclude "release blocker,no changelog" + python3 scripts/gh.py issues "2.16.0" --exclude "no changelog" python3 scripts/gh.py issues "2.16.0" --label "bug" (include only issues with label) python3 scripts/gh.py issues "2.16.0" --label "bug,regression" --exclude "no changelog" python3 scripts/gh.py issues "2.16.0" --compare CHANGES.md @@ -1092,7 +1092,7 @@ def main() -> None: ) p_issues.add_argument( "--exclude", "--exclude-labels", - help="Comma-separated labels to exclude, e.g. 'release blocker,no changelog'" + help="Comma-separated labels to exclude, e.g. 'no changelog'" ) p_issues.add_argument( "--label", "--labels", diff --git a/scripts/test_changelog.py b/scripts/test_changelog.py index 8eb0311c9f..0ad4181eca 100644 --- a/scripts/test_changelog.py +++ b/scripts/test_changelog.py @@ -131,9 +131,14 @@ class IssueExcludedTests(unittest.TestCase): self.assertTrue(ch.issue_excluded(self.issue(state="OPEN"))) self.assertTrue(ch.issue_excluded(self.issue(issue_type="Task"))) self.assertTrue(ch.issue_excluded(self.issue(project_status="Rejected"))) - self.assertTrue(ch.issue_excluded(self.issue(labels=["release blocker"]))) self.assertTrue(ch.issue_excluded(self.issue(labels=["no changelog"]))) + def test_keeps_a_release_blocker_issue(self): + # `release blocker` marks work that blocks the release; it is not a + # changelog exclusion. Bugs go through dev-only-bugs, anything else is + # a human call in the pre-flight. + self.assertFalse(ch.issue_excluded(self.issue(labels=["release blocker"]))) + class RenderBoomEntryTests(unittest.TestCase): def test_entry_is_a_heading_plus_note_plus_references(self): @@ -707,10 +712,13 @@ class FindDevOnlyBugsTests(unittest.TestCase): {**bug(8, parent={"number": 10, "issue_type": "Feature", "milestone": "2.19.0"}), "issue_type": "Enhancement"}, bug(9, body="### Affected versions\n\n2.18.2\n", labels=["regression"]), + bug(10, parent={"number": 10, "issue_type": "Feature", "milestone": "2.19.0"}, + labels=["release blocker"]), + bug(11, body="### Affected versions\n\nhourly\n", labels=["release blocker"]), ] auto, suggested = ch.find_dev_only_bugs("2.19.0", issues) - self.assertEqual([e["issue"] for e in auto], [1, 2]) - self.assertEqual([e["issue"] for e in suggested], [3, 5, 9]) + self.assertEqual([e["issue"] for e in auto], [1, 2, 10]) + self.assertEqual([e["issue"] for e in suggested], [3, 5, 9, 11]) if __name__ == "__main__":