Skip to content

Link release note issue references and archive pre-v0.230.001 notes - #1292

Merged
Paul Lizer (paullizer) merged 1 commit into
Developmentfrom
paullizer-verbose-dollop
Aug 19, 2026
Merged

Link release note issue references and archive pre-v0.230.001 notes#1292
Paul Lizer (paullizer) merged 1 commit into
Developmentfrom
paullizer-verbose-dollop

Conversation

@paullizer

Copy link
Copy Markdown
Collaborator

Why

Release notes referenced issues as bare #1289 or microsoft/simplechat#1145. The notes render on the Jekyll docs site, where kramdown does not auto-link either form, so every reference was dead text for readers.

While mapping references back to issues, a second problem surfaced: the repository default branch is main, but every PR merges into Development. GitHub only honours Fixes #NNNN on merges into the default branch, so no issue has ever auto-closed. 56 shipped issues were still sitting open.

What changed

Docs (this PR)

  • Linkified all 165 references inside (Ref: ...) blocks as absolute Markdown links. Every number was classified against the GitHub API first, so the 11 pull-request references point at /pull/ rather than /issues/.
  • Backfilled 3 entries whose shipping PR named an issue the note omitted.
  • Moved v0.229.063 and older into docs/explanation/archive_release_notes.md — 19 sections, 989 lines, down to v0.190.1. The current page drops from 4,781 to 3,797 lines (452 KB → 391 KB).
  • Linked the archive from the bottom of the release notes and from the docs sidebar under Deep reference.

Issues (already applied)

  • Closed 40 issues as completed, each with a comment naming the shipping PR, the version, and its release-note entries. Repo open issues went 261 → 221.

Attribution method

Line-level attribution uses each merged PR's own patch of release_notes.md, not the commit → PR API. That API returns every PR whose branch merely contains a commit; open long-lived branch #1228 contains 132 unrelated commits and was initially credited with work spanning 30+ versions it never touched.

Deliberate restraint

  • Scoped strictly to (Ref: ...) blocks. The notes also contain prose like **Issue #1 - DOM Manipulation Error** — a list number, not a reference. Blanket linkification would have corrupted it.
  • 4 of 7 backfill candidates rejected. Their PRs bundled two unrelated fixes and named both issues, so backfilling would have credited the wrong bullet (e.g. a Data Management scheduler guard tagged with an Analyze-contract issue).
  • 296 refs in six pre-convention mega-sections left alone (v0.250.001, v0.241.001, v0.235.003, …). They predate per-PR issue tracking and have no issue to link.
  • 11 epics and 5 partial deliveries were not closed — listed below.

Not closed, needs a human call

Issue Why
#1013 #1014 #1015 #1016 #1017 #1018 #1019 #1020 MCP roadmap tracks/phases; #1013 has 7 sub-issues
#1055 #1058 Mixed-source orchestration epic; #1055 has sub-issues #1056#1061
#1082 Generalize-workflows epic
#1233 Multi-phase epic (Phases 1–7 plus 7A–7D)
#1047, #358 v0.250.109 explicitly says Closes #1143, related #1047 and #358
#1071 PR #1152 shipped JSON/XML only; universal CSV unconfirmed
#1031 Notes state durable fan-out and automatic continuation are still unavailable

Verification

A validator reconstructs the original file from the two halves, normalizes the links back to their pre-edit spelling, and requires an exact match against HEAD:

lines compared             : 4781
differing lines            : 3 [563, 621, 1091]   <- the reviewed backfills only
content preservation       : OK
issue/pull URL segments    : OK
unlinked refs in Ref blocks: 0
ALL CHECKS PASSED

Docs-only, so no config.py version bump per repo rules.

Follow-up worth filing

The Development vs main mismatch will keep stranding issues. Either change the default branch, or add a workflow that closes referenced issues on merge into Development.

Release notes referenced issues as bare `#1289` or `#1145`.
Those render as plain text on the docs site, where kramdown does not autolink
them, so the references were unusable for readers.

- Linkify all 165 references inside `(Ref: ...)` blocks as absolute Markdown
  links. Each number was classified against the GitHub API first, so the 11
  pull request references point at `/pull/` rather than `/issues/`.
- Backfill three entries whose shipping PR named an issue the note omitted.
  Four further candidates were rejected because their PR bundled two unrelated
  fixes and naming its issue would have credited the wrong bullet.
- Move v0.229.063 and older into `archive_release_notes.md`, cutting the current
  page from 4,781 to 3,797 lines. The move is byte-faithful and verified by
  reconstructing the original file from the two halves.
- Link the archive from the bottom of the release notes and from the docs
  sidebar under Deep reference.

Scoping the rewrite to `(Ref: ...)` blocks is deliberate: the notes also contain
prose such as "**Issue #1 - DOM Manipulation Error**", which is a list number
rather than a GitHub reference.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@paullizer
Paul Lizer (paullizer) merged commit 8049fb5 into Development Aug 19, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant