110 lines
3.3 KiB
Markdown
110 lines
3.3 KiB
Markdown
---
|
|
name: update-changelog
|
|
description: 'Update docs/CHANGELOG.md from git history, GitHub releases, and code diffs. Use when: writing release notes, syncing the latest changelog entry, summarizing a new tag, or keeping changelog wording concise and consistent.'
|
|
argument-hint: 'Describe the target, for example: latest version only'
|
|
---
|
|
|
|
# Update Changelog
|
|
|
|
Update `docs/CHANGELOG.md` from repository evidence instead of guesswork.
|
|
|
|
## When to Use
|
|
|
|
- Add the newest release entry to `docs/CHANGELOG.md`
|
|
- Sync changelog text with GitHub Releases
|
|
- Summarize the latest tag from git history or code diffs
|
|
|
|
## Defaults
|
|
|
|
- Keep the wording brief
|
|
- Only add the latest missing version unless the user explicitly asks to backfill older releases
|
|
- Prefer GitHub sources first, especially Releases and tag metadata
|
|
- Skip `Features` / `Improvements` / `Bug Fixes` headings when the release only has a few clear items
|
|
|
|
## Procedure
|
|
|
|
### 1. Read the local style
|
|
|
|
- Open `docs/CHANGELOG.md`
|
|
- Match the existing tone, bullet style, section ordering, and date format
|
|
|
|
### 2. Determine the target release
|
|
|
|
- Read the root `package.json` version and compare it with the top changelog entry
|
|
- Find the previous tag for the target version
|
|
- If the latest version is already documented, stop and report that no changelog update is needed
|
|
|
|
### 3. Gather evidence
|
|
|
|
Prefer these sources in order:
|
|
|
|
1. GitHub release notes
|
|
|
|
```bash
|
|
GH_PAGER=cat gh release view v<version> --repo <owner>/<repo> --json tagName,name,publishedAt,body
|
|
```
|
|
|
|
2. Tag date
|
|
|
|
```bash
|
|
git log -1 --format=%cs v<version>
|
|
```
|
|
|
|
3. Commit history between tags
|
|
|
|
```bash
|
|
git --no-pager log --format='%h %s' --no-merges v<previous>..v<version>
|
|
```
|
|
|
|
4. Diff scope when commit subjects are vague
|
|
|
|
```bash
|
|
git --no-pager diff --name-only v<previous>..v<version>
|
|
git --no-pager diff --stat v<previous>..v<version>
|
|
```
|
|
|
|
5. Read touched files directly only when the user-visible change is still unclear
|
|
|
|
### 4. Distill what belongs in the changelog
|
|
|
|
Include:
|
|
|
|
- User-visible features
|
|
- Important behavior changes
|
|
- Bug fixes that improve reliability, compatibility, or developer experience
|
|
- Small docs updates only when they materially change supported setups or onboarding
|
|
|
|
Exclude unless explicitly requested:
|
|
|
|
- Pure version bumps
|
|
- Routine dependency updates
|
|
- Internal refactors with no visible impact
|
|
- Mechanical formatting noise
|
|
|
|
### 5. Choose the structure
|
|
|
|
- If the release has 1 to 3 clear points, write flat bullets directly under the version heading
|
|
- If the release has several distinct items, use short headings such as `### Features`, `### Improvements`, and `### Bug Fixes`
|
|
- Do not force categories when they make the entry longer or noisier
|
|
|
|
### 6. Write the entry
|
|
|
|
- Add or update only the requested release entry
|
|
- Keep bullets short and concrete
|
|
- Reuse project terminology from nearby entries
|
|
- Avoid marketing language
|
|
- Do not copy noisy GitHub release text verbatim
|
|
|
|
### 7. Verify
|
|
|
|
- Check dates, version numbers, and tag boundaries
|
|
- Ensure Markdown structure matches nearby entries
|
|
- Confirm no intermediate versions were added unless requested
|
|
|
|
## Completion Checks
|
|
|
|
- The newest requested version is documented
|
|
- The wording is concise and consistent with the surrounding changelog
|
|
- The entry is backed by GitHub releases, git history, or code diff evidence
|
|
- Low-signal internal changes were left out
|