WORK-643
ID:WORK-643Status:done

A command drafts a release note from the milestone

Handwritten notes tend to stop after a few releases unless writing one is close to free. This command writes everything but the opening sentences.

Priority:mediumComplexity:simpleMilestone:v0.41.1Source:SPEC-176
claude/site-changelog-readability-k4p902 View source

Criteria completion

Criteria completion: 5 of 6 (83%) checked; history from Oct 15 to Oct 150%25%50%75%100%Oct 15Oct 15

Relationships

Implements 1
Related 3
Branches 1
claude/site-changelog-readability-k4p902 current done
main done
History 6
  1. 2153967
    Content editedby bjornolofandersson
  2. df590cc
    Content editedby bjornolofandersson
  3. a18d721
    • ☑ `npm run release-notes:draft -- <version>` writes `releases/notes/v<version>.md`, and refuses to overwrite an existing file
    • ☑ The draft contains a placeholder for the opening, prefilled with the milestone's title and first paragraph when the milestone exists
    • ☑ The background line has drawer refs to the milestone, to the distinct `source` specs of its work and bug items, and to its bugs
    • ☑ Links are taken from `milestone="vX.Y.Z"` on work and bug items, not from `released-in`
    • ☑ `RELEASING.md` has a step to draft and finish the note before merging the release PR
    by bjornolofandersson
  4. 711f598
    Content editedby bjornolofandersson
  5. 321d355
    Created (ready)by bjornolofandersson
  6. f1b561c
    Content editedby Claude
    plan: renumber SPEC-160 and WORK-639..642 after merging main

Acceptance Criteria

  • npm run release-notes:draft -- <version> writes releases/notes/v<version>.md, and refuses to overwrite an existing file
  • The draft contains a placeholder for the opening, prefilled with the milestone's title and first paragraph when the milestone exists
  • The draft contains an action-needed {% hint type="warning" %} block marked for deletion with a TODO: line, and a test fails while any TODO: line remains in a note (refrakt content has no comment syntax, BUG-012)
  • The background line has drawer refs to the milestone, to the distinct source specs of its work and bug items, and to its bugs
  • Links are taken from milestone="vX.Y.Z" on work and bug items, not from released-in
  • RELEASING.md has a step to draft and finish the note before merging the release PR

Approach

Reuse the milestone and ID readers from WORK-641 and WORK-642 rather than parsing the plan a third time. Order the background refs so the milestone comes first, then specs, then bugs, each group in ID order.

Blocked by

  • WORK-641

References

  • SPEC-176 D5.

Resolution

Completed: 2026-10-15

Branch: claude/site-changelog-readability-k4p902 PR: refrakt-md/refrakt#704

What was done

  • scripts/draft-release-note.mjs + npm run release-notes:draft -- <version>: writes releases/notes/v<version>.md, refuses to overwrite. Prefills the milestone opening, an action-needed hint, and drawer refs (milestone, distinct SPEC sources, bugs; by milestone=, not released-in).
  • draftMarkerFindings + a repository test fail while a note has a TODO: line.
  • RELEASING.md: a 'Writing the release note' section and a checklist item.

Notes

  • The criterion asked for a commented-out hint, but refrakt content has no comment syntax (BUG-012), so placeholders are TODO: lines guarded by a test. The criterion and SPEC-176 D5 were reworded to match.
  • The note belongs on main: the changesets action reruns version-packages on every push to main, which regenerates the changelog.