Changelog-Konventionen
Changelog-Konventionen
Abschnitt betitelt „Changelog-Konventionen“Diese Seite ist der Vertrag, dem jedes öffentliche NextPDF-Repository folgt, wenn es eine Änderung festhält und ein Release veröffentlicht. Sie ist eine Konventionsreferenz; sie sichert kein Paketverhalten zu. Der paket- und versionsbezogene Fließtext steht in der jeweils eigenen CHANGELOG.md des betreffenden Repositorys. Diese Seite definiert die gemeinsamen Regeln, damit die Zusammenfassung des repository-übergreifenden Changelogs konsistent und frei von Leaks bleibt.
Conventional Commits 1.0.0
Abschnitt betitelt „Conventional Commits 1.0.0“Jeder Commit-Betreff lautet type(scope): description. Der type ist einer der folgenden:
| Typ | Bedeutung | Nutzersichtbar | Versionseffekt |
|---|---|---|---|
feat | Eine neue Funktion | ja | Minor-Erhöhung |
fix | Ein korrigiertes Verhalten | ja | Patch-Erhöhung |
perf | Eine Leistungsverbesserung ohne Verhaltensänderung | ja | Patch-Erhöhung |
refactor | Interne Umstrukturierung, keine beobachtbare Änderung | nein | keine |
docs | Nur Dokumentation | nein | keine |
test | Nur Tests | nein | keine |
build / ci | Nur Build oder Pipeline | nein | keine |
chore | Wartung, Abhängigkeiten, Tooling | nein | keine |
revert | Macht einen vorherigen Commit rückgängig | abhängig | abhängig |
Ein Breaking Change wird durch ein ! nach dem Typ oder Scope (feat(api)!: …) oder durch einen BREAKING CHANGE:-Footer gekennzeichnet. In beiden Fällen wird unter Semantic Versioning die Major-Version erhöht. Ein sicherheitsrelevanter Fix wird festgehalten, damit er in die Spalte Security der repository-übergreifenden Zusammenfassung gefiltert werden kann.
Semantic Versioning 2.0.0
Abschnitt betitelt „Semantic Versioning 2.0.0“Die Versionserhöhung erfolgt mechanisch. Ein Release, das einen Breaking Change enthält, ist ein Major-Release. Andernfalls ist ein Release, das einen feat enthält, ein Minor-Release. Andernfalls ist ein Release, das einen fix oder perf enthält, ein Patch-Release. Pakete vor 1.0 dürfen die Minor-Version für einen Breaking Change gemäß SemVer §4 erhöhen. Der Commit trägt dennoch den Breaking-Marker, damit die Zusammenfassung korrekt bleibt.
Gruppierung nach Keep a Changelog
Abschnitt betitelt „Gruppierung nach Keep a Changelog“Die CHANGELOG.md jedes Repositorys folgt Keep a Changelog 1.1.0: Einträge werden pro veröffentlichter Version unter Added, Changed, Deprecated, Removed, Fixed und Security gruppiert. Ein Abschnitt [Unreleased] kann im Repository Notizen zu laufenden Arbeiten enthalten, doch die repository-übergreifende Zusammenfassung zählt nur getaggte, veröffentlichte Versionen. Unveröffentlichte Arbeiten erscheinen niemals im öffentlichen Index.
Wie die repository-übergreifende Zusammenfassung abgeleitet (und leakfrei gehalten) wird
Abschnitt betitelt „Wie die repository-übergreifende Zusammenfassung abgeleitet (und leakfrei gehalten) wird“Die Zusammenfassungstabelle im Changelog-Index wird erzeugt, indem die Conventional-Commits-Historie jedes Repositorys an seinem jeweils neuesten veröffentlichten Tag schreibgeschützt ausgelesen und die Kategorien gezählt werden. Die Ableitungsregeln sind bewusst eng gefasst, damit kein internes Detail nach außen gelangt:
- Anzahlen, nicht Inhalte. Es wird nur die Anzahl der Commits pro nutzersichtbarem Typ ausgewiesen. Kein Commit-Betreff, kein Body, kein Footer und kein Hash wird gerendert.
- Nur nutzersichtbare Typen.
docs,test,ci,choreundrefactorwerden ausgeschlossen — sie ändern nichts, was ein Paketkonsument beobachtet. - Nur Veröffentlichtes. Ein Commit zählt erst, sobald er Teil eines getaggten Releases eines öffentlichen Pakets ist.
- Keine Bezeichner. Interne Verweise auf Issues, Tickets, Cycles, Waves oder Work-Items, die in einem privaten Commit-Scope auftauchen können, werden niemals offengelegt, weil der Scope-Text selbst nie gerendert wird — nur der Typ wird gelesen.
- Keine Automatisierungs-Zuschreibung. Contributor-Automation-Trailer werden weder gelesen noch angezeigt.
Deshalb ist das öffentliche Changelog eine Kategorienzusammenfassung samt Links zur jeweils eigenen CHANGELOG.md jedes Pakets und kein aggregierter Commit-Feed. Die Zusammenfassung ist konstruktionsbedingt nachweisbar frei von internen Leaks. Der maßgebliche Fließtext verbleibt bei dem Paket, zu dem er gehört.