popochiu-release-notes

Popochiu Release Notes

Draft release notes for a new version of Popochiu by fetching "Done" issues from the GitHub project, grouping them by priority into sections, crediting contributors, and writing the first draft directly to the target file so the user can iterate on it in the editor.

Context

• Repo: carenalgas/popochiu
• GitHub Project: https://github.com/orgs/carenalgas/projects/1/
• Draft output location: release-notes/vX.X.X.md
• Uses the gh CLI for all GitHub data. See references/github_project.md for the exact queries.

---

Workflow

Step 1 — Get the version number

Extract the target version from the user's prompt (e.g. "write release notes for v2.0.4" → v2.0.4). If not provided, ask for it before proceeding.

---

Step 2 — Fetch "Done" issues from the GitHub project

Use gh project item-list instead of hand-written GraphQL. It is easier to read, less error-prone, and already flattens the custom project fields into predictable JSON keys like status, priority, labels, and content.

Important: gh project item-list defaults to 30 items. Always pass an explicit limit large enough for the full board, e.g. --limit 500.

Run the command described in references/github_project.md to get all project items whose Status field is "Done".

For each issue, collect:

• Issue number, title, URL
• Priority custom field value: one of bugfixing, polishing, maturity, nice-to-have
• Labels (look for documentation)
• Body (scan for breaking-change language: "breaking", "migration required", "upgrade steps", "you must", etc.)

---

Step 3 — Find linked PRs and external contributors

For each issue, check for merged PRs that reference it:

gh api "repos/carenalgas/popochiu/issues/{number}/timeline" \
  --jq '[.[] | select(.event == "cross-referenced") |
         select(.source.issue.pull_request != null) |
         {pr: .source.issue.number, author: .source.issue.user.login}] | unique'

Consider a contributor external (worth crediting) when their GitHub login does not appear in the list of core-team members: carenalgas, stickgrinder, matjam, quovernight. When in doubt, omit the credit — it's better to miss one than to misattribute.

---

Step 4 — Map issues to sections

Override rules (applied before the table above):

• Issue has a documentation label, or title/body clearly describes a docs change → Documentation section (prose paragraph, not bullet list)
• Issue body contains breaking-change language → flag for Final Notes and summarise what users need to do before/after upgrading

If an issue's priority is missing or ambiguous, make a best-effort call and note it at the end of the draft so the user can sanity-check.

Before drafting, do a quick count by section so truncation bugs are obvious:

• Count Bugfixing issues that will become Fixes
• Count Polishing, Maturity, and Nice-to-Have issues that will become Improvements
• Count documentation-labeled issues that will be absorbed into Documentation

Report these counts in the summary below the draft.

---

Step 5 — Write the draft

Use this structure (omit sections that have no entries):

# Popochiu vX.X.X

[Intro paragraph]

## Fixes

- [Entry description](issue_url).
- [Entry description](issue_url) — Thanks to [@username](https://github.com/username).

## Improvements

- [Entry description](issue_url).

## Documentation

[Short prose paragraph summarising the documentation work.]

## Final Notes

[Upgrade instructions or important caveats for users.]

Entry format:

• Link text is a natural-language description of the fix/improvement, derived from the issue title. Shorten or rephrase if the title is long or technical.
• Contributor credit goes inline at the end of the bullet, only for external contributors: — Thanks to [@username](https://github.com/username).
• If multiple external contributors worked on the same issue, list them all.

Writing the intro paragraph: Write 2–4 sentences in the Popochiu team's voice: first-person plural ("we"), warm, enthusiastic, occasionally playful. Look at the mix of issues to pick a theme:

• Mostly bugfixes → small-but-solid maintenance release ("Another round of polish…")
• Big new features → celebrate them prominently
• Mixed → highlight the most noteworthy items

Calibrate enthusiasm to release size. A two-fix patch doesn't need an exclamation parade; a major feature drop can afford more fanfare. Study the existing notes in release-notes/ for tone reference if needed.

For the Documentation section, write prose (2–4 sentences) instead of bullets, as seen in v2.0.3. Describe what changed and why it matters to users/contributors.

For Final Notes, be clear and practical: what must the user do, in what order, and what can go wrong. Mirror the upgrade-instruction style in v2.0.0.

---

Step 6 — Write the draft file and report back

Write the complete draft directly to release-notes/vX.X.X.md.

If the file already exists, update it in place instead of asking the user to copy and paste the text manually.

Then tell the user the file has been written and add a short summary note:

• Total issues included and how they were distributed across sections
• Any issues you couldn't categorise confidently (so the user can verify)
• Any issues where no contributor could be determined

The default workflow is now editor-first: write the initial draft to the file, then iterate with the user in the editor.