Releases and changelog
Releases and changelog
Section titled “Releases and changelog”Ship meaningful release notes that a future you (or a new developer) can read without spelunking Git history. Tie public-facing “what changed” to Roadmap statuses—especially Shipped—when the work was tracked there.
When to use
Section titled “When to use”- Tagging / publishing a GitHub Release for a repo.
- Summarizing what went out for users or operators after a milestone.
Release notes content
Section titled “Release notes content”Each release should answer:
- What shipped — user-visible or operator-visible changes (bullet list).
- Where to read more — link to sylva-docs sections when applicable (
/user/…,/dev/…,/roadmap/…). - Breaking / migration — explicit callouts if behavior or config changed.
- Repos — if the milestone touched multiple repositories, say which artifacts or deployables changed.
Avoid raw commit dumps as the only body; commits stay in Git for forensic detail.
Roadmap alignment
Section titled “Roadmap alignment”When roadmap items move to Shipped, ensure the summary field (or linked doc) contains enough text to seed release notes (Triage workflow). You do not duplicate the whole roadmap in the Release—you point to it.
GitHub Release mechanics
Section titled “GitHub Release mechanics”Use whatever fits your flow:
- GitHub UI: Releases → Draft → attach tag, paste notes.
ghCLI: e.g.gh release create <tag> --title "…" --notes-file …
Keep tags semver-aligned where the repo already uses semver; follow existing conventions per repository.
Cursor skill
Section titled “Cursor skill”Use sylva-release-notes when preparing or polishing text for a release so notes stay consistent with this page.