Jamie-BitFlight/conventional-commits

Conventional Commits

Erstelle Commit-Nachrichten gemäß der Conventional-Commits-v1.0.0-Spezifikation für einen strukturierten Commit-Verlauf, automatisierte Changelog-Generierung und semantische Versionierung.

Wann dieses Skill verwendet werden soll

Verwende dieses Skill, wenn:

• Git-Commit-Nachrichten für strukturierte Projekte erstellt werden
• Das Format von Commit-Nachrichten gegen die Conventional-Commits-Spezifikation validiert wird
• Die Validierung von Commit-Nachrichten mit commitlint eingerichtet wird
• Die Changelog-Generierung aus dem Commit-Verlauf konfiguriert wird
• Die Automatisierung der semantischen Versionierung implementiert wird
• Commit-Nachrichten auf Spezifikationskonformität überprüft werden
• Teams in Commit-Nachrichten-Standards geschult werden
• Werkzeuge wie semantic-release, commitizen oder git-cliff integriert werden

Nachrichtenstruktur

<typ>[optionaler bereich]: <beschreibung>

[optionaler nachrichtentext]

[optionale fußzeile(n)]

Bestandteile

Bestandteil	Erforderlich	Beschreibung	Beispiel
typ	Ja	Kategorie des Commits	feat, fix, docs
bereich	Nein	Betroffener Codebereich	(auth), (parser)
beschreibung	Ja	Kurze Zusammenfassung der Änderung	Benutzerauthentifizierung hinzufügen
nachrichtentext	Nein	Detaillierte Erklärung	Mehrere Absätze mit Kontext
fußzeile	Nein	Breaking Changes, Issue-Referenzen	BREAKING CHANGE:, Refs: #123

Commit-Typen

Erforderliche Typen (SemVer-Auswirkung)

Diese Typen sind von der Conventional-Commits-Spezifikation vorgeschrieben und wirken sich direkt auf die semantische Versionierung aus:

flowchart LR
    Fix[fix: Fehlerbehebung<br/>für Nutzer] --> PatchVer[PATCH<br/>0.0.X]
    Feat[feat: Neue Funktion<br/>für Nutzer] --> MinorVer[MINOR<br/>0.X.0]
    Breaking[Jeder Typ mit<br/>BREAKING CHANGE oder !] --> MajorVer[MAJOR<br/>X.0.0]

    style PatchVer fill:#e1f5ff
    style MinorVer fill:#fff4e1
    style MajorVer fill:#ffe1e1

Typ	Beschreibung	SemVer	Beispiel
feat	Neue Funktion für Nutzer	MINOR (0.X.0)	feat: Benutzerauthentifizierung hinzufügen
fix	Fehlerbehebung für Nutzer	PATCH (0.0.X)	fix: Absturz bei leerer Eingabe verhindern

Empfohlene Typen (Angular-Konvention)

Diese Typen stammen aus @commitlint/config-conventional basierend auf den Angular-Commit-Richtlinien. Sie haben keine implizite SemVer-Auswirkung, es sei denn, sie enthalten BREAKING CHANGE.

Typ	Beschreibung	Beispiel
build	Änderungen am Build-System oder externen Abhängigkeiten	build: webpack auf v5 aktualisieren
ci	Änderungen an der CI-Konfiguration	ci: Node 18 zur Testmatrix hinzufügen
docs	Nur Dokumentationsänderungen	docs: API-Referenz aktualisieren
perf	Leistungsverbesserung	perf: Bündelgröße um 20% reduzieren
refactor	Codeänderung ohne Fehlerbehebung oder neues Feature	refactor: Validierungslogik extrahieren
style	Code-Stil-Änderungen (Leerzeichen, Formatierung)	style: Einrückung korrigieren
test	Hinzufügen oder Korrigieren von Tests	test: Unit-Tests für Parser hinzufügen

Zusätzliche gängige Typen

Typ	Beschreibung	Beispiel
chore	Änderungen, die weder src- noch test-Dateien betreffen	chore: .gitignore aktualisieren
revert	Einen vorherigen Commit rückgängig machen	revert: feat: Benutzer-auth hinzufügen

Hinweis: Teams können über feat und fix hinaus eigene Typen definieren, aber die Angular-Konventionstypen werden von Werkzeugen weitgehend unterstützt.

Spezifikationsregeln

Die folgenden Regeln bilden die offizielle Conventional-Commits-1.0.0-Spezifikation gemäß RFC 2119.

Typ und Bereich

1. Commits MÜSSEN mit einem Typ (einem Substantiv wie feat, fix usw.) beginnen, gefolgt von einem OPTIONALEN Bereich, einem OPTIONALEN ! und einem ERFORDERLICHEN Doppelpunkt gefolgt von einem Leerzeichen.

2. Der Typ feat MUSS verwendet werden, wenn ein Commit eine neue Funktion hinzufügt.

3. Der Typ fix MUSS verwendet werden, wenn ein Commit eine Fehlerbehebung darstellt.

4. Ein Bereich KANN nach einem Typ angegeben werden. Ein Bereich MUSS aus einem Substantiv bestehen, das einen Codebereich beschreibt, umgeben von Klammern, z. B. fix(parser):

5. Eine Beschreibung MUSS unmittelbar nach dem Doppelpunkt und Leerzeichen nach dem Typ-/Bereichs-Präfix folgen. Die Beschreibung ist eine kurze Zusammenfassung der Codeänderungen, z. B. fix: Problem beim Parsen von Arrays, wenn mehrere Leerzeichen im String enthalten waren

Nachrichtentext

6. Ein längerer Commit-Text KANN nach der Kurzbeschreibung bereitgestellt werden, um zusätzliche kontextbezogene Informationen zu liefern. Der Text MUSS eine Leerzeile nach der Beschreibung beginnen.

7. Ein Commit-Text ist frei formulierbar und KANN aus einer beliebigen Anzahl von durch Zeilenumbrüche getrennten Absätzen bestehen.

Fußzeile

8. Eine oder mehrere Fußzeilen KÖNNEN eine Leerzeile nach dem Text bereitgestellt werden. Jede Fußzeile MUSS aus einem Wort-Token bestehen, gefolgt von einem Trennzeichen :<space> oder <space>#, gefolgt von einem Zeichenfolgenwert (inspiriert von der git-trailer-Konvention).

9. Das Token einer Fußzeile MUSS - anstelle von Leerzeichen verwenden, z. B. Acked-by (dies hilft, den Fußzeilenabschnitt von einem mehrzeiligen Text zu unterscheiden). Ausnahme: BREAKING CHANGE KANN auch als Token verwendet werden.

10. Der Wert einer Fußzeile KANN Leerzeichen und Zeilenumbrüche enthalten. Das Parsen MUSS beendet werden, wenn das nächste gültige Fußzeilen-Token/Trennzeichen-Paar erkannt wird.

Breaking Changes

11. Breaking Changes MÜSSEN entweder im Typ-/Bereichs-Präfix eines Commits oder als Eintrag in der Fußzeile angegeben werden.

12. Wenn als Fußzeile angegeben, MUSS ein Breaking Change aus dem großgeschriebenen Text BREAKING CHANGE bestehen, gefolgt von Doppelpunkt, Leerzeichen und Beschreibung, z. B. BREAKING CHANGE: Umgebungsvariablen haben jetzt Vorrang vor Konfigurationsdateien

13. Wenn im Typ-/Bereichs-Präfix angegeben, MÜSSEN Breaking Changes durch ein ! unmittelbar vor : gekennzeichnet werden. Wenn ! verwendet wird, KANN BREAKING CHANGE: in der Fußzeile weggelassen werden, und die Commit-Beschreibung SOLLTE verwendet werden, um den Breaking Change zu beschreiben.

Zusätzliche Regeln

14. Andere Typen als feat und fix KÖNNEN in Commit-Nachrichten verwendet werden, z. B. docs: Referenzdokumente aktualisieren

15. Die Informationseinheiten, die Conventional Commits ausmachen, DÜRFEN NICHT als case-sensitive behandelt werden, außer BREAKING CHANGE, welches MUSS großgeschrieben werden.

16. BREAKING-CHANGE MUSS gleichbedeutend mit BREAKING CHANGE sein, wenn es als Token in einer Fußzeile verwendet wird.

Best Practices für die Beschreibung

Basierend auf den Angular-Commit-Nachrichten-Richtlinien:

Richtlinien für Zusammenfassung/Beschreibung

• Imperativ im Präsens verwenden: "ändern", nicht "geändert" oder "Änderungen"
• Ersten Buchstaben nicht großschreiben
• Keinen Punkt (.) am Ende
• Gesamte Kopfzeile (Typ + Bereich + Beschreibung) unter 72 Zeichen halten

Gute Beispiele

feat: Validierung für E-Mail-Eingabe hinzufügen
fix: NullPointer im Benutzerdienst behandeln
docs: Installationsanleitung aktualisieren
refactor: Authentifizierungsablauf vereinfachen

Schlechte Beispiele (Vermeiden)

feat: Validierung für E-Mail-Eingabe hinzugefügt     # Vergangenheit
fix: Behandelt NullPointer im Benutzerdienst          # Dritte Person
docs: Installationsanleitung aktualisieren.           # Punkt am Ende, großgeschrieben
FEAT: Validierung hinzufügen                           # Typ großgeschrieben (inkonsistent)

Richtlinien für den Nachrichtentext

• Imperativ im Präsens verwenden (wie bei der Zusammenfassung)
• Motivation für die Änderung erklären
• Bei Bedarf Vergleich zwischen altem und neuem Verhalten einschließen
• Text MUSS mit einer Leerzeile nach der Beschreibung beginnen
• Empfohlenes Minimum: 20 Zeichen, wenn ein Text vorhanden ist

Breaking Changes

Methoden zur Angabe von Breaking Changes

Drei gleichwertige Ansätze:

1. Fußzeilen-Notation:

   feat: erlaubt, dass bereitgestelltes Konfigurationsobjekt andere Konfigurationen erweitert
   
   BREAKING CHANGE: Der Schlüssel `extends` in der Konfigurationsdatei wird jetzt verwendet, um andere Konfigurationsdateien zu erweitern
   

2. Typ-Suffix mit !:

   feat!: Unterstützung für Node 6 entfernen
   

3. Typ+Bereich-Suffix mit !:

   feat(api)!: sende eine E-Mail an den Kunden, wenn ein Produkt versendet wird
   

Regeln

• BREAKING CHANGE MUSS großgeschrieben werden
• BREAKING-CHANGE ist gleichbedeutend, wenn es als Fußzeilen-Token verwendet wird
• Breaking Changes MÜSSEN mit einer MAJOR-Versionserhöhung in SemVer korrelieren

Korrelation mit semantischer Versionierung

flowchart TD
    Start([Commits analysieren]) --> CheckBreaking{Hat ein Commit<br/>BREAKING CHANGE<br/>oder !?}
    CheckBreaking -->|Ja| Major[MAJOR-Erhöhung<br/>X.0.0]
    CheckBreaking -->|Nein| CheckFeat{Ist ein Commit<br/>feat?}
    CheckFeat -->|Ja| Minor[MINOR-Erhöhung<br/>0.X.0]
    CheckFeat -->|Nein| CheckFix{Ist ein Commit<br/>fix?}
    CheckFix -->|Ja| Patch[PATCH-Erhöhung<br/>0.0.X]
    CheckFix -->|Nein| NoChange[Keine Versionsänderung]

    Major --> End([Release])
    Minor --> End
    Patch --> End
    NoChange --> End

Zuordnung von Commit-Typ zu Version

Commit-Typ	Versionserhöhung
fix	PATCH (0.0.X)
feat	MINOR (0.X.0)
BREAKING CHANGE oder !	MAJOR (X.0.0)

Grund: Ermöglicht automatisierte semantische Versionierung basierend auf dem Commit-Verlauf.

Validierungsmuster

Regex für die Kopfzeilenvalidierung

^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\(.+\))?!?:\s.+$

Python-Validierungsbeispiel

import re

CONVENTIONAL_COMMIT_PATTERN = re.compile(
    r"^(?P<type>feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)"
    r"(?:\((?P<scope>[^)]+)\))?"
    r"(?P<breaking>!)?"
    r":\s"
    r"(?P<description>.+)$"
)


def validate_header(header: str) -> bool:
    """Validiert, ob die Commit-Kopfzeile den Conventional Commits folgt."""
    return bool(CONVENTIONAL_COMMIT_PATTERN.match(header))


def parse_header(header: str) -> dict | None:
    """Zerlegt die Commit-Kopfzeile in ihre Bestandteile."""
    match = CONVENTIONAL_COMMIT_PATTERN.match(header)
    if not match:
        return None
    return {
        "type": match.group("type"),
        "scope": match.group("scope"),
        "breaking": bool(match.group("breaking")),
        "description": match.group("description"),
    }

Vollständige Beispiele

Einfache Commits

feat: Benutzerauthentifizierung hinzufügen

fix: Absturz bei leerer Eingabe verhindern

docs: Rechtschreibung von CHANGELOG korrigieren

Commits mit Bereich

feat(lang): Polnische Sprache hinzufügen

feat(parser): Fähigkeit zum Parsen von Arrays hinzufügen

fix(auth): Token-Ablauf korrekt behandeln

Breaking Changes

feat: erlaubt, dass bereitgestelltes Konfigurationsobjekt andere Konfigurationen erweitert

BREAKING CHANGE: Der Schlüssel `extends` in der Konfigurationsdatei wird jetzt verwendet, um andere Konfigurationsdateien zu erweitern

feat!: sende eine E-Mail an den Kunden, wenn ein Produkt versendet wird

feat(api)!: sende eine E-Mail an den Kunden, wenn ein Produkt versendet wird

chore!: Unterstützung für Node 6 entfernen

BREAKING CHANGE: Verwende JavaScript-Funktionen, die in Node 6 nicht verfügbar sind.

Mehrzeiliger Text mit Fußzeilen

fix: Rennen von Anfragen verhindern

Führe eine Anforderungs-ID und einen Verweis auf die letzte Anforderung ein.
Verwerfe eingehende Antworten, die nicht von der letzten Anforderung stammen.

Entferne Timeouts, die zur Minderung des Rennproblems verwendet wurden, aber jetzt veraltet sind.

Reviewed-by: Z
Refs: #123

Revert-Commit

revert: lasst uns nie wieder über den Nudelvorfall sprechen

Refs: 676104e, a215868

Leistungsverbesserung

perf: Speicherzuweisung im Parser um 40 % reduzieren

Ersetze Zeichenfolgenverkettung durch StringBuilder-Muster.
Benchmark-Ergebnisse zeigen eine 40 %ige Reduzierung der Heap-Zuweisungen.

Refs: #456

Refactoring

refactor: Authentifizierungslogik in separates Modul extrahieren

Verschiebe auth-bezogene Funktionen von utils.py nach auth.py.
Keine funktionalen Änderungen.

Build-/CI-Änderungen

ci: Node 18 zur Testmatrix hinzufügen

build: Upgrade von webpack v4 auf v5

- webpack.config.js für v5-Kompatibilität aktualisieren
- Veraltete Plugins ersetzen
- Alle Loader-Abhängigkeiten aktualisieren

Refs: #789

Test- und Stil-Änderungen

test: Unit-Tests für Benutzervalidierung hinzufügen

Deckt Randfälle für E-Mail-Validierung und Passwortstärke ab.

style: Code gemäß der prettier-Konfiguration formatieren

chore: .gitignore aktualisieren, um IDE-Dateien auszuschließen

Integration mit Validierungswerkzeugen

commitlint-Konfiguration

Validiere Commits mit commitlint unter Verwendung der Angular-Konfiguration:

# Installiere commitlint
npm install --save-dev @commitlint/cli @commitlint/config-conventional

# Erstelle Konfiguration
echo "module.exports = {extends: ['@commitlint/config-conventional']}" > commitlint.config.js

# Teste Commit-Nachricht
echo 'feat(api): neuen Endpunkt hinzufügen' | npx commitlint

Eine umfassende Anleitung zur commitlint-Konfiguration findest du in diesem Dokument. Wenn dein Arbeitsbereich ein installiertes commitlint-Plugin hat, kannst du dich für projektspezifische Regeln und Beispiele darauf beziehen.

Pre-Commit-Hooks

Erzwinge das Commit-Nachrichtenformat mit Pre-Commit-Hooks. Wenn dein Arbeitsbereich ein installiertes Pre-Commit-Plugin hat, verwende es für die Hook-Einrichtungsanleitung; andernfalls konfiguriere Hooks direkt.

Changelog-Generierung

Generiere Changelogs aus Conventional Commits mit semantic-release:

// release.config.js
module.exports = {
  branches: ['main'],
  plugins: [
    '@semantic-release/commit-analyzer',
    '@semantic-release/release-notes-generator',
    '@semantic-release/changelog',
    '@semantic-release/npm',
    '@semantic-release/github',
  ],
};

Gitmoji-Integration (werkzeugspezifisch)

Gitmoji-fähige Werkzeuge erlauben die Emoji-Kennzeichnung von Commit-Typen:

# konventionelle Commit-Nachricht mit gitmoji-cli
$ git commit -m ":sparkles: feat: Benutzerprofilseite hinzufügen"

Empfohlen: Verwende integrierte Unterstützung, wenn dein Arbeitsbereich sie bietet. Konfiguriere gitmoji-cli (separates Installationswerkzeug) andernfalls gemäß seiner Dokumentation.

Quellen und Referenzen

• Offizielle Conventional-Commits-Spezifikation v1.0.0
• Angular-Commit-Nachrichten-Richtlinien
• commitlint (@commitlint/config-conventional)
• git-interpret-trailers-Dokumentation
• RFC 2119 (Schlüsselwörter zur Angabe von Anforderungsstufen)
• semantic-release
• @commitlint/config-conventional