♻️ 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
This commit is contained in:
Andrey Antukh 2026-11-16 09:17:27 +00:00
parent 7ef8c1cf36
commit 328e41e037
7 changed files with 27 additions and 16 deletions

View File

@ -37,7 +37,8 @@ memory; it does not repeat it.
## Commands
```bash
python3 scripts/gh.py issues "<VERSION>" --exclude "release blocker,no changelog"
python3 scripts/gh.py issues "<VERSION>" --exclude "no changelog"
python3 scripts/gh.py issues "<VERSION>" --label "release blocker" --exclude "no changelog" # closed non-bug residue to review by hand
python3 scripts/gh.py advisories --patched-version "<VERSION>"
python3 scripts/changelog.py dev-only-bugs "<VERSION>" # list bugs that never reached production
python3 scripts/changelog.py dev-only-bugs "<VERSION>" --apply # label the sure ones `no changelog`

View File

@ -8,7 +8,7 @@
- `boom <MILESTONE> [--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 `#### <issue title>` 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 <MILESTONE> [--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 <description> (<advisory URL>) (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 <MILESTONE> [--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 <MILESTONE> [--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 <MILESTONE> [--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 <MILESTONE> [--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.

View File

@ -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

View File

@ -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 "<VERSION>" --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 "<VERSION>"` 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 "<VERSION>" --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 "<VERSION>"` 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 "<VERSION>" --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 <numbers...>` (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 <PR numbers...>`. 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.

View File

@ -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", "")}

View File

@ -15,7 +15,7 @@ Subcommands:
Usage:
python3 scripts/gh.py issues <milestone-title> (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",

View File

@ -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__":