tweak-release-notes

# Tweak release notes (ISC BIND 9) Refine the auto-generated release notes for a new BIND 9 version into the project's reviewed style, after checking that the generated content is correct and complete. **Notes only** — the changelog is never hand-edited. ## Golden rule **Recent tags are the source of truth.** This process evolves; when any convention below is unclear or seems to conflict with what you see, mirror the most recent released `doc/notes/notes-9.*.rst` files. Consistency — in git style and in release-note style, content, and markup — is the whole goal. Stick to existing conventions unless the maintainer asks otherwise. ## Prerequisites - **`gitlab` (python-gitlab CLI)** — issue reads use anonymous access: `gitlab --server-url https://gitlab.isc.org --skip-login -o json project-issue get --project-id isc-projects/bind9 --iid <N>`. No token needed for public issues. - **`meson`/`sphinx-build`** — the docs build gate runs directly, no wrapper: `meson setup build && meson compile -C build arm` (add `-Ddoc=enabled` to setup if it doesn't auto-detect `sphinx-build`). - The generated `doc/changelog/changelog-<ver>.rst` and `doc/notes/notes-<ver>.rst` already exist (committed by "Generate changelog" and "Prepare release notes"). ## Workflow Work top to bottom. Details for every step: **[REFERENCE.md](REFERENCE.md)**. Helper scripts (pure-local git/text + JSON parsing) are in `scripts/`. The whole workflow operates on a single release branch/checkout — one `<ver>` at a time. **Where the work pauses:** the flags produced by steps 3 and 4 need maintainer decisions, but do not block on them — carry on with steps 5–7 for everything unflagged and present the flags together with the result. Edits that follow from flag decisions land afterwards as fixups. 1. **Scope the cycle.** Range = the most recent `Set up version for BIND 9.X.Y` commit `..HEAD`. List merges + their `action:audience` tags: `python3 scripts/cycle_merges.py`. (Action/audience taxonomy: REFERENCE.md.) 2. **Audit audience→notes mapping (light checkmark).** This is script- generated and rarely wrong: confirm notes-entry count == usr/pkg merge count and nothing usr/pkg is missing. Don't over-invest here. 3. **Substance review — the main event.** For every merge, judge whether the `action` (sec/new/rem/chg/fix) AND `audience` (usr/pkg/dev/…) match what the change actually does — not the diff's size. Read the MR/issue when in doubt. **Flag mismatches for the maintainer; do not silently re-tag.** Use the triage heuristics in REFERENCE.md. When the maintainer agrees a note should move section (e.g. a crash mis-tagged `chg` → belongs in Bug Fixes, or a `sec` with no CVE → Bug Fixes minus attribution — examples of past maintainer decisions, not standing rules; always flag first), reflect it **in the notes only**. The changelog is never edited — it is generated from the git log of the already-merged (frozen) MRs — so notes and changelog simply differ for this release, which is expected. 4. **Issue close-status check.** Derive the full covered-issue set (`python3 scripts/issue_refs.py <ver>`), fetch each via gitlab CLI, then `python3 scripts/summarize_issues.py <dir>`. Every covered issue should be **closed**. For any that isn't, reason: *omission* (closed via a non-main / private-fork branch so auto-close never fired → suggest the maintainer close it) vs *ongoing* (MR only referenced it, no `Closes` → leave open). Flag, don't fix silently. 5. **Refine the notes (style + markup).** Rewrite into prior-art style: add Sphinx roles to everything linkable, render the rest per prior art, fix typos, normalize phrasing, place/section entries correctly. Full rules and the markup decision table: REFERENCE.md. **When unsure, grep recent notes.** 6. **Verify the docs build.** A required gate after any notes change. Use the meson compile; the gate treats Sphinx warnings as errors, so every role target must resolve. 7. **Commit.** `Tweak and reword release notes` (verbatim subject, no body) + `Assisted-by` trailer; follow-ups as `--fixup`; finish with the standard DROP-revert of the changelog. Exact conventions: REFERENCE.md.