| name | user-changelog |
| description | Weekly end-user release notes from Git commits — German prose in docs/user-changelog.md, not a technical changelog. Reads commit subjects and bodies; diffs only when needed. SHA boundaries in section headings avoid duplicate work. Use for user changelog, weekly user summary, end-user release notes, or Nutzer-Zusammenfassung. |
| disable-model-invocation | true |
User changelog (end-user release notes)
Weekly workflow: summarize changes since the last run as plain German bullet points — only what end users can see, do, or notice. Not a technical changelog.
If there are pending changes when done (e.g. docs/user-changelog.md), use finish-work to run bun run check and draft the English commit message before committing.
File
docs/user-changelog.md in the project (structure reference; adjust path per project once).
Each run prepends a new section at the top. SHA boundaries live in the heading — no separate state file.
Checklist
- [ ] Step 1: Resolve last SHA boundary
- [ ] Step 2: Build commit list (from → to)
- [ ] Step 3: Triage commits from subject/body (diff only if needed)
- [ ] Step 4: Write user-facing bullets in German
- [ ] Step 5: Prepend new section to docs/user-changelog.md
- [ ] Step 6: Commit/push only when the user explicitly asks
Step 1: Last SHA boundary
Read docs/user-changelog.md (project path). The top heading is fixed — parsing is straightforward; no script required.
## Zusammenfassung von `abc1234` bis `def5678` (2025-06-30)
- Start this run:
def5678 (bis from the latest section)
- End:
HEAD — omit in git log (<FROM>..); use git rev-parse --short HEAD for the new heading’s bis SHA
To resolve FROM before git log (optional — same result as reading the file):
FROM=$(grep -m1 '^## Zusammenfassung von' docs/user-changelog.md 2>/dev/null \
| sed -E 's/.*bis `([^`]+)`.*/\1/')
First run (FROM empty — file missing, empty, or no heading): ask the user — e.g. since tag v1.2.0, last 2 weeks, or an explicit SHA. Do not guess.
Step 2: Commit list
FROM.. with no right side means through HEAD (same as FROM..HEAD).
Use --reverse (oldest first): work landed in that order, follow-up commits for the same feature usually come later, and merging several commits into one bullet is easier when reading forward in time. Write bullets in the same order.
git log "${FROM}".. --no-merges --reverse \
--format='%h%n%s%n%b%n---'
Skip merge commits. Usually omit Dependabot, CI-only, format, and lint commits unless the message clearly describes user-visible impact.
Step 3: Relevance — title first, diff rarely
Per commit:
- Read subject + body — usually enough; translate to German in Step 4. Open the diff only when the message is unclear.
- Include when end users can see, do, or understand something differently (UI, maps, export, login, noticeable performance, new capability, visible bugfix).
- Omit: refactors, tests, types, deps, internal APIs, migrations with no visible effect, developer-only docs.
- Diff only when the commit message is unclear or contradictory — then
git show <sha> --stat or targeted UI paths, not the full patch.
Merge multiple commits into one bullet when they describe the same visible change.
Step 4: Wording (German, end-user)
Write bullets in German:
- Active voice, short, no jargon (no “refactor”, “loader”, “PR”, package names).
- Area prefix when it helps scanning — e.g. Karte:, Export:, Anmeldung:. In a monorepo, one shared
docs/user-changelog.md; use the prefix for the package or surface (e.g. Processing: for processing/, Karte: for the app map UI).
- Fixes: describe the user-visible problem, not the broken code.
- No issue/PR numbers, author names, or SHAs inside bullets.
Good and bad examples: examples.md.
Step 5: New section
Prepend to docs/user-changelog.md (newest period first). Use this German template:
## Zusammenfassung von `def5678` bis `f0a1b2c` (2025-07-07)
- **Karte:** Beim Zoomen bleibt die gewählte Region sichtbar.
- **Export:** GeoJSON-Download enthält wieder alle Eigenschaften.
- Behoben: Nach dem Abmelden wurde die Karte nicht aktualisiert.
- Date = run date (not per-commit dates).
- Short SHAs in backticks in the heading.
- Blank line after the heading, then bullets.
Step 6: Commit
Only when the user explicitly asks to commit — follow finish-work for bun run check and the commit message:
git add docs/user-changelog.md
git commit -m "$(cat <<'EOF'
Docs: Update changelog notes
Summary def5678..f0a1b2c
EOF
)"
Changelog file content stays German; the commit subject/body for this doc update stays English.
Notes
- No duplicates: do not repeat topics already covered in earlier sections, even if new commits touch the same files.
- Empty week: still add a section with:
Keine nutzerrelevanten Änderungen in diesem Zeitraum. — update boundaries so the next run starts correctly.
- Monorepos: one changelog file for the repo — include all packages in
git log. Disambiguate with area prefixes (Processing:, Karte:, …), not separate files per package.
- Archive: if the file grows too long, move older sections to
docs/archive/user-changelog-YYYY.md — the top section and its bis SHA remain the anchor for the next run.
Related
