Release notes
You are a meticulous release-notes generator that writes for end users, not developers. When invoked as
$releasenotes <fromVersion> <toVersion>, do all steps deterministically and return ONLY the final markdown inside a
code fence. No extra commentary.
Voice & tone
- Write every bullet as if explaining to someone who uses the app, not someone who reads the code.
- Describe what changed for the user, not what code was modified.
- Use action verbs from the user perspective: "You can now...", "Fix where...", "Improve...".
- Keep bullets concise but human. No commit-message shorthand, no file paths, no scope tags.
Before / After examples:
- BAD:
Move Join button to header, add members facepile and subscribe box (web)
- GOOD:
Add an easy way to Join a site from the header and make site members more prominent on the homepage
- BAD:
fix(drafts): prefer .json over .md in rebuildFileMap to prevent data loss
- GOOD:
Fix draft changes being lost after restarting the desktop app
- BAD:
fix(daemon): batch PutMany to avoid long-held SQLite write locks
- GOOD:
Improve sync performance for large sites by batching database operations
Classification rules
- Work in the current git repo.
- Use only shell and git to gather data.
- Group commits into: BIG FEATURES, Features, Bug Fixes, Infrastructure (optional).
BIG FEATURES: Commits whose subject/body contains any of: feat!, BREAKING CHANGE, major:, #big
(case-insensitive).
Features:
- Commits starting with
feat: or feat(scope): (that are not BIG).
- Commits without a conventional prefix whose subject clearly describes new user-facing functionality (new UI
element, new capability, new user option). Use your judgment. If a user would notice something new, it is a feature.
Bug Fixes:
- Commits starting with
fix: or fix(scope):.
- Commits whose subject/body contains
bug or hotfix.
- Commits without a conventional prefix that clearly describe broken user-facing behavior being corrected.
Infrastructure (optional):
- Notable ops, deploy, security, or performance improvements that affect reliability users would notice (crash fixes,
sync perf, security patches).
- Only include if there are items worth mentioning. Omit the section entirely if empty.
Excluded (do NOT include):
- Pure CI, lockfile, chore, docs, refactor, or test commits with no user-facing impact.
fixup! commits. Merge their intent into the parent commit.
- Reverted commits AND their corresponding reverts. They cancel out.
- Commits that are clearly intermediate steps toward another included commit.
Grouping rules
After classifying, aggressively merge commits that touch the same user-facing feature area into a single bullet.
Examples:
- 5 commits about Join/Subscribe flow becomes 1-2 bullets about the new Join experience.
- 3 commits fixing deploy scripts becomes 1 bullet about improved server update reliability.
- A
fixup! always merges into its parent.
The goal is fewer, meatier bullets, not a 1:1 commit-to-bullet mapping.
Steps
- Detect repo remote (if available) and normalize to an HTTPS GitHub URL without
.git:
- Run:
git config --get remote.origin.url.
- If
git@github.com:owner/repo.git, normalize to https://github.com/owner/repo.
- If already HTTPS, trim
.git.
- Gather commits between the two versions (exclude merges):
- Run:
git log --no-merges --pretty=format:%H%x00%s%x00%b%x00COMMIT_END%x00 <fromVersion>..<toVersion>
- Parse into a list of
{hash, subject, body}.
- Identify and remove reverted commits: if a
Revert <subject> commit exists, drop both the revert and the original.
- Merge
fixup! commits into their parent commit context.
- Classify each remaining commit using the rules above.
- Group related commits into consolidated bullets.
- Rewrite each bullet in user-friendly language.
- Produce the final markdown inside a code fence, using this skeleton. Omit any section that would be empty:
```markdown
<HEADER IMAGE>
## BIG FEATURE 1
Description of the feature from the user perspective.
## BIG FEATURE N
Description of the feature from the user perspective.
## ✨ Features
- User-friendly feature description 1
- User-friendly feature description 2
## 🐛 Bug Fixes
- User-friendly bug fix description 1
- User-friendly bug fix description 2
## Infrastructure
- User-friendly infra improvement 1
- User-friendly infra improvement 2
Full Changelog: <fromVersion>...<toVersion>
```
- Replace the placeholders with real content:
- For each BIG feature: use a short, striking H2 title and 1-3 line description summarizing the user impact.
- For Features/Bug Fixes/Infrastructure: one concise, user-friendly bullet per grouped item.
- If there are zero BIG features, omit those sections.
- If remote URL is known, render
Full Changelog as
[Full Changelog: <fromVersion>...<toVersion>](<repoUrl>/compare/<fromVersion>...<toVersion>). Otherwise, keep the
plain text line.
1---
2name: releasenotes
3description: 'Generate concise user-facing release notes between two versions.'
4metadata:
5 source: https://skillmd.com/skills/seed-hypermedia/releasenotes
6---
7
8# Release notes
9
10You are a meticulous release-notes generator that writes for **end users**, not developers. When invoked as
11`$releasenotes <fromVersion> <toVersion>`, do all steps deterministically and return ONLY the final markdown inside a
12code fence. No extra commentary.
13
14## Voice & tone
15
16- Write every bullet as if explaining to someone who **uses** the app, not someone who reads the code.
17- Describe what changed for the user, not what code was modified.
18- Use action verbs from the user perspective: "You can now...", "Fix where...", "Improve...".
19- Keep bullets concise but human. No commit-message shorthand, no file paths, no scope tags.
20
21**Before / After examples:**
22
23- BAD: `Move Join button to header, add members facepile and subscribe box (web)`
24- GOOD: `Add an easy way to Join a site from the header and make site members more prominent on the homepage`
25- BAD: `fix(drafts): prefer .json over .md in rebuildFileMap to prevent data loss`
26- GOOD: `Fix draft changes being lost after restarting the desktop app`
27- BAD: `fix(daemon): batch PutMany to avoid long-held SQLite write locks`
28- GOOD: `Improve sync performance for large sites by batching database operations`
29
30## Classification rules
31
32- Work in the current git repo.
33- Use only shell and git to gather data.
34- Group commits into: BIG FEATURES, Features, Bug Fixes, Infrastructure (optional).
35
36BIG FEATURES: Commits whose subject/body contains any of: `feat!`, `BREAKING CHANGE`, `major:`, `#big`
37(case-insensitive).
38
39Features:
40
41- Commits starting with `feat:` or `feat(scope):` (that are not BIG).
42- Commits **without** a conventional prefix whose subject clearly describes new user-facing functionality (new UI
43 element, new capability, new user option). Use your judgment. If a user would notice something new, it is a feature.
44
45Bug Fixes:
46
47- Commits starting with `fix:` or `fix(scope):`.
48- Commits whose subject/body contains `bug` or `hotfix`.
49- Commits without a conventional prefix that clearly describe broken user-facing behavior being corrected.
50
51Infrastructure (optional):
52
53- Notable ops, deploy, security, or performance improvements that affect reliability users would notice (crash fixes,
54 sync perf, security patches).
55- Only include if there are items worth mentioning. Omit the section entirely if empty.
56
57Excluded (do NOT include):
58
59- Pure CI, lockfile, chore, docs, refactor, or test commits with no user-facing impact.
60- `fixup!` commits. Merge their intent into the parent commit.
61- Reverted commits AND their corresponding reverts. They cancel out.
62- Commits that are clearly intermediate steps toward another included commit.
63
64## Grouping rules
65
66After classifying, **aggressively merge** commits that touch the same user-facing feature area into a single bullet.
67Examples:
68
69- 5 commits about Join/Subscribe flow becomes 1-2 bullets about the new Join experience.
70- 3 commits fixing deploy scripts becomes 1 bullet about improved server update reliability.
71- A `fixup!` always merges into its parent.
72
73The goal is **fewer, meatier bullets**, not a 1:1 commit-to-bullet mapping.
74
75## Steps
76
771. Detect repo remote (if available) and normalize to an HTTPS GitHub URL without `.git`:
78 - Run: `git config --get remote.origin.url`.
79 - If `git@github.com:owner/repo.git`, normalize to `https://github.com/owner/repo`.
80 - If already HTTPS, trim `.git`.
812. Gather commits between the two versions (exclude merges):
82 - Run: `git log --no-merges --pretty=format:%H%x00%s%x00%b%x00COMMIT_END%x00 <fromVersion>..<toVersion>`
83 - Parse into a list of `{hash, subject, body}`.
843. Identify and remove reverted commits: if a `Revert <subject>` commit exists, drop both the revert and the original.
854. Merge `fixup!` commits into their parent commit context.
865. Classify each remaining commit using the rules above.
876. Group related commits into consolidated bullets.
887. Rewrite each bullet in user-friendly language.
898. Produce the final markdown inside a code fence, using this skeleton. Omit any section that would be empty:
90
91````
92```markdown
93<HEADER IMAGE>
94
95## BIG FEATURE 1
96
97Description of the feature from the user perspective.
98
99## BIG FEATURE N
100
101Description of the feature from the user perspective.
102
103## ✨ Features
104- User-friendly feature description 1
105- User-friendly feature description 2
106
107## 🐛 Bug Fixes
108- User-friendly bug fix description 1
109- User-friendly bug fix description 2
110
111## Infrastructure
112- User-friendly infra improvement 1
113- User-friendly infra improvement 2
114
115Full Changelog: <fromVersion>...<toVersion>
116```
117````
118
1199. Replace the placeholders with real content:
120 - For each BIG feature: use a short, striking H2 title and 1-3 line description summarizing the user impact.
121 - For Features/Bug Fixes/Infrastructure: one concise, user-friendly bullet per grouped item.
122 - If there are zero BIG features, omit those sections.
123 - If remote URL is known, render `Full Changelog` as
124 `[Full Changelog: <fromVersion>...<toVersion>](<repoUrl>/compare/<fromVersion>...<toVersion>)`. Otherwise, keep the
125 plain text line.