Popochiu Release Notes

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