Commit-Nachrichten, aus denen das Projekt ein Changelog bauen kann #

Teil 5, Kapitel 11. Eine Commit-Nachricht wird einmal geschrieben und oft gelesen: in Reviews, in git log, in git blame Jahre später und im Changelog des nächsten Releases. Exponential verwendet ein einfaches Format, das all das möglich macht. Verwenden Sie es im Kernel (dort wird es geprüft) und in Ihren eigenen Erweiterungen.

Das Format #

Der Betreff beginnt mit einem von fünf Wörtern und einem Doppelpunkt:

Der Rest des Betreffs ist ein Satz, der sagt, was nach dem Commit zutrifft:

Fixed: The redirect keeps the query string on the own host
Updated: The context menu entries of expchangeclass carry no inline handlers
Added: German translation of the sign-in and setup texts

Das Beispiel für einen Fixed:-Betreff ist dasjenige, das CONTRIBUTING.md angibt.

Warum dieses Format #

• Das Changelog schreibt sich von selbst. Beim Release werden die Commits seit dem letzten Tag nach ihrem ersten Wort in die vier oder fünf Gruppen eines Changelogs sortiert (Changelogs).
• Reviewer wissen, was sie erwartet. Ein Fixed:-Commit sollte keine Funktionen hinzufügen; ein Renamed:-Commit sollte kein Verhalten ändern.
• Es hält Commits klein. Wenn ein Betreff ein „und“ zwischen zwei Präfixen braucht, sind es zwei Commits.

Der Kernel prüft es #

Das Kernel-Repository liefert Git-Hooks in .githooks/ mit. Führen Sie in Ihrem Klon einmal aus:

make hooks

Von da an lehnt git commit einen Betreff ohne eines der fünf Präfixe ab:

commit-msg: the subject must start with 'Added: ', 'Updated: ', 'Fixed: ', 'Removed: ' or 'Renamed: ', e.g.
    Fixed: The redirect keeps the query string on the own host

Merge-Commits und die von Git erzeugten Betreffs Revert, fixup! und squash! sind erlaubt. Die CI prüft die Commits eines Pushs oder Pull Requests mit .githooks/check-commit-range (Qualitätsprüfungen, auf Englisch); laut dieser Seite führt der Commit eines Beitragenden dort nur zu einer Warnung.

Sie können den commit-msg-Hook in das Repository Ihrer Erweiterung kopieren: Es ist ein kurzes Shell-Skript.

Der Text #

Nach einer Leerzeile erklärt der Text, was der Betreff nicht kann: warum die Änderung nötig war, was vorher falsch war und wie sie geprüft wurde. Echte Beispiele aus den Erweiterungen, die dieses Buch anführt:

Updated: Version 1.0.6: installs and runs on PHP 8.0, the oldest PHP Exponential 6 supports

PHP 8.0 is the stock PHP of Red Hat Enterprise Linux 9 and the oldest version Exponential 6 supports. The code of
this extension was checked with PHPCompatibility for PHP 8.0, linted and loaded with PHP 8.0.30, and served by
PHP 8.0 on a full installation.

(se7enxweb/expchangeclass, Commit 32196f0.) Der Text nennt den Grund, die Prüfungen und das Ergebnis. Wer ihn in fünf Jahren liest, weiß, ob er der Änderung trauen kann.

Gute und schlechte Betreffs #

Was nicht in eine Commit-Nachricht gehört #

• Geheimnisse, Passwörter, personenbezogene Daten: Ein Commit ist öffentlich, sobald er gepusht ist, und lässt sich nicht zurücknehmen.
• Private Pfade Ihres Rechners oder Namen interner Server.
• Nennungen von Werkzeugen, mit denen Sie die Änderung geschrieben haben. Der Autor des Commits ist die Person, die dafür verantwortlich ist.

Verwandte Seiten #

• Zurück: Gute Issues schreiben
• Weiter: Die Arbeit anderer prüfen
• Changelogs
• Qualitätsprüfungen (auf Englisch)
• Freie Dokumentation: Diese Seite darf unter der GNU FDL 1.3 frei kopiert, übersetzt und verbessert werden.