Fähigkeit zum Erstellen von Changelogs mit Conventional Commits

--- name: conventional-commits-changelog-builder description: Verwandelt ein Git-Log im Conventional-Commits-Format in einen einsatzbereiten Keep-a-Changelog-Release-Abschnitt - Added, Changed, Deprecated, Removed, Fixed, Security - mit Scopes, Issue- und Commit-Links sowie einem Block für Breaking Changes. Markiert Breaking Changes ohne Migrationshinweise, nicht konforme und Fixup-Commits, Reverts und Duplikate und schlägt die nächste SemVer-Version vor. Enthält einen Offline-Stdlib-Python-Builder mit --self-test. --- # Conventional Commits Changelog Builder Du hilfst Maintainern, die Commits seit dem letzten Tag in einen Changelog-Eintrag zu verwandeln, den Menschen tatsächlich lesen können. Das manuelle Schreiben bedeutet, durch ein Log zu scrollen, zu raten, welche Commits wichtig sind, und den einen Breaking Change zu vergessen, der in einem Footer versteckt ist. Das blinde Generieren kopiert jeden Tippfehler, WIP-Commit und revertierte Feature in die Veröffentlichung. Du parse die Commits, ordnest sie den Keep-a-Changelog-Abschnitten zu, listest genau auf, was weggelassen wurde und warum, und sagst, welche Version die Veröffentlichung bekommen sollte. ## Dateien in dieser Skill - `scripts/changelog_build.py` - liest `git log` (Standardformat), `git log --oneline` oder einen `%x1f`/`%x1e`-Records-Export; parst `type(scope)!: description`-Header und `BREAKING CHANGE:`-Footer; gruppiert in Added / Changed / Deprecated / Removed / Fixed / Security mit einem BREAKING-CHANGES-Block; hebt Reverts im Bereich auf, überspringt Merges, entfernt Duplikate, markiert Fixup/WIP- und nicht konforme Commits mit einem vorgeschlagenen Header; verlinkt Issues, Commits und den Vergleichsbereich; schlägt den SemVer-Bump vor (0.x-bewusst); kann den Abschnitt in eine bestehende CHANGELOG.md einfügen (nur Python-3.8+-Standardbibliothek) - `references/commit-to-changelog-mapping.md` - die Typ-zu-Abschnitt-Tabelle, Breaking-Change-Regeln, Bump-Regeln und die Finding-Codes CC01-CC10 - `references/release-hygiene.md` - Einträge für Nutzer schreiben, Migrationshinweise, Umgang mit nicht konformer Historie und CI-Checks - `templates/release-notes-review.md` - die Überprüfung, die zusammen mit dem Abschnitt zurückgegeben wird - `examples/git-log.txt` - 21 Commits eines fiktiven CLI (tidyq) seit v2.3.1: zwei Breaking Changes, ein Security-Fix, eine Deprecation, ein Revert, ein Duplikat-Cherry-Pick, ein Fixup, ein WIP und ein einfacher "Fixed ..."-Commit - `examples/CHANGELOG.md` - das bestehende Changelog des Projekts (Unreleased + 2.3.1 + 2.3.0) - `examples/changelog-report.md` - die echte Builder-Ausgabe für dieses Log ## Arbeitsablauf ### 1. Commit-Bereich abrufen Frage nach dem letzten veröffentlichten Tag und exportiere alles danach, neueste zuerst: ``` git log v2.3.1..HEAD > commits.txt git log v2.3.1..HEAD --format='%H%x1f%s%x1f%b%x1e' > commits.txt # am sichersten: behält Bodies, keine Parse-Ratearbeit ``` Frage auch nach der aktuellen Version, dem Veröffentlichungsdatum, der Repository-URL (für Links), dem Tag-Präfix (`v` standardmäßig) und ob interne Commits (refactor, docs, ci, chore, test) aufgelistet werden sollen. Ein Squash-Merge-Workflow ist ideal: ein PR = ein Commit = eine Zeile. ### 2. Builder ausführen ``` python3 scripts/changelog_build.py examples/git-log.txt --current 2.3.1 --date 2026-11-03 --repo-url https://github.com/tidyq/tidyq python3 scripts/changelog_build.py commits.txt --current 2.3.1 --insert CHANGELOG.md > CHANGELOG.new.md python3 scripts/changelog_build.py commits.txt --current 0.9.4 --include-internal --json python3 scripts/changelog_build.py --self-test ``` Exit 0 = bereit zum Tagen, 1 = hohe Findings, 2 = ungültige Eingabe. Ohne Shell wende `references/commit-to-changelog-mapping.md` manuell an: parse jeden Header, ordne den Typ dem Abschnitt zu, sammle `!`- und `BREAKING CHANGE:`-Footer, hebe Reverts auf, dann wähle den höchsten Bump. ### 3. Findings vor dem Tagen beheben - CC03 (hoch): ein `!`-Commit ohne `BREAKING CHANGE:`-Footer gibt Nutzern keinen Migrationspfad. Schreibe den Hinweis (was bricht, was stattdessen tun) in den Abschnitt. - CC08 (hoch): nicht konforme Commits, die wie Features oder Fixes aussehen, fehlen im Changelog. Füge sie manuell mit dem vorgeschlagenen Header hinzu und aktiviere einen Commit-Lint-Check. - CC07: Fixup/WIP-Commits sollten vor der Veröffentlichung gesquasht werden; CC04: Reverts älterer Releases brauchen einen Satz, der erklärt warum. - CC01/CC02/CC05/CC06: Formulierung und Konformität; behebe im Changelog-Text, nicht durch Umschreiben veröffentlichter Historie. ### 4. Für Menschen bearbeiten Der Builder liefert korrekte Struktur, keine gute Prosa. Schreibe Einträge als sichtbare Effekte für Nutzer um ("Export schreibt standardmäßig Parquet" statt "refactor writer"), fasse Einträge zusammen, die eine Änderung beschreiben, behalte Scopes, die Nutzer erkennen, und platziere den BREAKING-CHANGES-Block so, dass niemand ihn übersehen kann. Siehe `references/release-hygiene.md`. ### 5. Liefern Fülle `templates/release-notes-review.md` aus: Version und warum, der finale Abschnitt, die Migrationshinweise, was weggelassen wurde und Folgeaufgaben (commitlint, PR-Titel-Check). Mit `--insert` gib die aktualisierte CHANGELOG.md zurück; die Originaldatei wird nie verändert. ## Beispielergebnis Auf `examples/git-log.txt` (aktuell 2.3.1) liest der Builder 21 Commits, 85% konform, und schlägt **3.0.0** vor: `feat(export)!` macht Parquet zum Standard (mit korrektem BREAKING-CHANGE-Footer) und `fix(config)!` entfernt die INI-Konfigurationsdatei ohne Migrationshinweis (CC03, hoch). "Fixed crash when the config file is empty" ist kein Conventional Commit und würde still im Changelog fehlen (CC08, hoch; vorgeschlagen: `fix: crash when the config file is empty`). Der Token-Leak-Fix landet unter Security, die `--legacy-dates`-Deprecation unter Deprecated, das Farbthemen-Feature und sein Revert heben sich auf, der gecherry-pickte BOM-Fix wird einmal aufgelistet, und der Merge, Fixup, WIP und 5 interne Commits werden als weggelassen aufgelistet. ## Regeln - Erfinde niemals Einträge: jede Zeile stammt aus einem Commit, und jeder Commit ist entweder im Abschnitt oder in der "weggelassen"-Liste. - Ein Breaking Change bekommt immer einen Migrationshinweis und den Major-Bump (Minor bei 0.x); verstecke ihn nie in Changed. - Security-Fixes gehören unter Security, auch wenn der Commit-Typ `fix` ist. - Schreibe veröffentlichte Historie nicht um, um Commit-Nachrichten zu korrigieren; behebe den Changelog-Text und füge einen Lint-Check für die Zukunft hinzu. - Halte die neueste Veröffentlichung oben, Daten als YYYY-MM-DD und einen Vergleichslink pro Version. - Die Version ist ein Vorschlag: Der Maintainer entscheidet, besonders bei Verhaltensänderungen, die als `fix` typisiert sind.