git was soll man beim kommentar beim commit schreiben

Google: GIT commit message guidelines

Zitty Z. schrieb:
> Das was man da gerade gemacht hat

Das.
Und zwar im Imperativ.

"Change Foo to Bar"
nicht
"Changed Foo to Bar"

Zitty Z. schrieb:
> aber warum?

Weil es viel einfacher zu lesen ist, wenn man sich den Commit nachher 
anschaut.
Man liest den Kommentar "change x to y" und dann sieht man das diff, in 
dem x nach y geändert wird.
Es gibt gar keinen Grund hier überhaupt einen zeitlichen Bezug 
(Vergangenheit oder Zukunft) zu haben.

Zitty Z. schrieb:
> aber warum?
> es ist doch schon passiert xD

Wenn Du nach vorne und aus Deiner eigenen Perspektive blickst, ja.

Aber in einem Team zieht sich ja bspw. ein anderer Entwickler einen 
neuen Stand aus git. Und dann liest es sich besser.

Und manchmal dreht man ja auch Versionsstände zurück und wieder vor.
Auch da ist diese Schreibweise manchmal vorteilhaft. Ist ja eh schon oft 
genug Gehirnakrobatik...

Aber wenn man die Versionierung vorwiegend für sich alleine nutzt, ist 
es eigentlich egal.

Zitty Z. schrieb:
> Für mich ist es immer praktisch zu wissen was der aktuelle Stand ist.

Da sollte offensichtlich sein, warum man das nicht macht:
Es skaliert nicht.

Oder was ist "der aktuelle Stand" des Linux Kernels, wenn man in einem 
USB-Treiber etwas ändert?

Der aktuelle Stand ist die Summe aller Commits in einem 
zusammenhängenden Weg zu einer Wurzel.

Zitty Z. schrieb:
> Aber gibt es da andere Vorgehensweisen?

"minor changes"
"according requirement item zyx"
"see change request xyz"

Zitty Z. schrieb:
> und wenn da stehen würde: "foo hinzufügen" , dann denkt man dass man das
> noch hinzufügen soll xD

Nein.
Commit-Logs sind keine TODO-Liste.
Commit-Logs beschreiben, was ein commit macht. Nicht, was er gemacht 
hat. Denn du weißt gar nicht, ob der Leser der Nachricht diesen Commit 
bereits hat (= gemacht hat) oder nicht. Es ist unnötig einen zeitlichen 
Bezug zu haben. Der verwirrt nur.

Hannes J. schrieb:
> RuckZuckFresseDick schrieb:

>> "according requirement item zyx"
>> "see change request xyz"
>
> Alles klar. Dann sogar noch lieber
>
>  git commit --allow-empty -m ""

Ein Verweis auf das zugrundeliegende Änderungsdokument, oder Requiremnt 
ist aber alles andere als eine leere/empty Message.

Wahrscheinlich haste übersehen das [xyz] als Platzhalter für einen Link 
zu verstehen ist. Natürlich kann man hier auch das Referenzierte in 
eigenen Worten wiederholen - das ist aber wie jede Redundanz verwirrend 
und fehlerträchtig.

RuckZuckFresseDick schrieb:
> see change request xyz

Schlecht und verwirrend wird das allerdings, wenn man mehr als einen 
solchen Commit mit dieser Message hat.
Und ein riesiges Feature in einem einzigen Commit zu implementieren ist 
natürlich auch schlecht.

Also funktioniert das Schema nur, wenn der Change Request sehr klein 
ist.

Zitty Z. schrieb:
> MaWin schrieb:
>> Und zwar im Imperativ.
>
> aber warum?
> es ist doch schon passiert xD

Weil die geläufige Konvention bei git eben ist zu sagen was der Commit 
machen soll, wenn man ihn z. B in seinen Code merged oder cherry-picked. 
Und eben nicht was der Entwickler gemacht hat.

Von der "klassischen" Konvention geht die Welt sicher auch nicht unter, 
aber das Team sollte sich halt einig sein.

> Zum Beispiel: cgit.freebsd.org ...

Wow. Ich hätte Open Source Entwickler werden sollen. Bei der Software, 
an der ich jetzt weiter murksen soll, stehen im Kommentar nur 2-3 
verwirrende Worte. Manchmal eine Ticketnummer, über sich herausfinden 
lässt, was die Kundebetreuerin in Auftrag gegeben hatte.

Wenn du als Entwickler überhaupt nachdenkst, was da drin stehen muss, 
sind deine Kommentare absolut vorbildlich einwandfrei.

A. S. schrieb:
> Wie immer ist die Frage bei Dokumentation:
>
> Für wen schreibst du sie und was will die Person wissen?

Ein Fall der mir immer mal wieder begegnet: von Benutzern/Tester wurde 
ein Fehler gemeldet, ist als Ticket/Issue Nr.xYz eingetragen. Dessen 
Ausmerzung umfass Änderungen an mehreren Dateien, durchaus auch über 
mehrere Commits, im Abstand von mehreren Tagen..

Wie findet man später alles was dazugehört wieder?
Bloss übers Datum greift zu kurz.
Also: Ticket Nr.xYz im Commit-Kommentar nennen (gerne auch als deep-URL, 
falls das nicht automagisch geschieht)

Ist analog zu "Anforderung Nr.aBc" usw.

Egregio Commendatore schrieb:
> Wie findet man später alles was dazugehört wieder?

dann sollte eher ein Branch für den Fix erzeugt werden, damit sind die 
Commits dazu zusammen.

> Also: Ticket Nr.xYz im Commit-Kommentar nennen

Damit lässt sich zumindest schon mal heraus finden, warum das Programm 
so einen hirnverbrannten Unfug macht.

Was immer fehlt - die Dokumentation, warum die Entwickler diese Lösung 
gewählt haben.

Wussten die nicht, dass es eine einfache Lösung gibt? Funktioniert diese 
einfache Lösung nicht? Hatten die keine Zeit für ein sauberes Konzept? 
...

MaWin schrieb:
> Es ist unnötig einen zeitlichen Bezug zu haben.

Das stimmt zwar nicht, aber die Grammatik ist hier zu ungenau. Wenn 
dieser notwendig ist, dann schreibt man zum Kommentar auch ein Datum 
dazu.

Noch ein Kommentar schrieb:
> hirnverbrannten Unfug

ist nur so ein Kommentar.

Wow! schrieb:
>> Zum Beispiel: cgit.freebsd.org ...
>
> Wow. Ich hätte Open Source Entwickler werden sollen. Bei der Software,
> an der ich jetzt weiter murksen soll, stehen im Kommentar nur 2-3
> verwirrende Worte. Manchmal eine Ticketnummer, über sich herausfinden
> lässt, was die Kundebetreuerin in Auftrag gegeben hatte.
>
> Wenn du als Entwickler überhaupt nachdenkst, was da drin stehen muss,
> sind deine Kommentare absolut vorbildlich einwandfrei.

Ja. Im (kommerziellen) Berufsumfeld wollen zwar alle "intelligente 
tools", gerne mit KI gewürzt. Will aber ein Entwickler genau sowas 
einführen, resp. solche tools miteinander integrieren erfordert das je 
nach "legacy"/Alter Kruscht soundsoviele Stunden Arbeit; weil diese 
nicht am Produkt selbst ist, gilt sie als "unproduktiv" (kann nicht 
einfach auf die morgige Kundenrechnung draufgeschlagen und kassiert 
werden) und wird nur selten genehmigt oder braucht unverhaeltnismaessig 
viel Lobbyaufwand damit man sowas "darf".
OpenSource-Projekte sind da viel offener und haben bessere chancen auf 
solche "best practices" drumherum.

Schau dir alleine an wie gerade dieses FreeBSD "alt" ist, das kann man 
heute durchaus als Legacy bezeichnen. Damals konnten viele Firmen 
nichtmal "Versionierungssystem" buchstabieren, geschweige denn die 
Notwendigkeit dafür einsehen.

Es ist mühsam die Arbeitskultur uneinsichtiger Arbeitskollegen positiv 
umzukrempeln. Noch mühsamer bei Arbeits"kollegen" auf höherer 
Hierarchiestufen denn die fordern zwar Top-Engagement , bremsen aber 
umsomehr bei dafür notwendigen Top-Tools/-Methoden...
BTDT.

Klaus W. schrieb:
> Aber der Regelfall ist bei uns: eine komplette Änderung = ein Commit.

Aber eine Änderung ist erst dann komplett wenn die Testabteilung ihren 
Segen gegegeben hat.

Und die Testabteilung nimmt ihre zu testenden Images nicht über den 
kurzen Dienstweg (email-anhang) sondern auch aus dem Git. Somit hat man 
zwangsläufig den Fall das man ungetestet und damit unfertige Versionen 
comitten muß. Somit kann 'das Paradies: eine Änderung, ein Commit' nie 
auftreten.

Jörg W. schrieb:
> Einfach mal bei anderen schauen. Zum Beispiel:
>
> https://cgit.freebsd.org/src/commit/?id=3fc3fe90915f02e25b4f1d5070e8e01e465e873d

...und die History von Projekten durchschauen und dich selbst fragen, 
welche der Commit-Messages dir sinnvolle Infos geben und welche nicht.

MfG, Arno

Ich schreibe immer Bugfix

Netzwerker schrieb:
> Ich schreibe immer 'Bugfix'

Das klingt aber überheblich, ich bleib da bescheiden: 'try to fix' oder 
'fix one, create two' ;-)

Jörg W. schrieb:
> Ich glaube, es gab schon mal eine seitenlange commit message für eine
> einzige geänderte Codezeile – weil eben die Änderung als solche
> keineswegs so offensichtlich war.

Das nennt man Missbrauch der commit-Funktion weil zu faul dedizierte 
Fall-Doku zu schreiben und dem Commit als Datei mitzugeben.

Mindestens hätte man der Codezeile ein par Comment-zeilen zur Seite 
stellen sollen, damit derjenige, der nur den Code aber nicht die 
CommitPsalmodirerei zum Review vorliegen hat, auch seine Chance auf 
Verständnis bekommt ...

Jörg W. schrieb:
> RuckZuckFresseDick schrieb:
>> Das nennt man Missbrauch der commit-Funktion
>
> Klar, weil du dich so genau auskennst, was da genau passiert ist und wie
> der Code tatsächlich aussieht, kannst du das auch beurteilen.

Ich kann sehr wohl beurteilen, das die Anzahl der Leser des 
Commit-Kommentars sehr viel kleiner ist als die Anzahl derer die den 
Inhalt des besagten Kommentars nötig hätten.

Ich mein, es ist richtig Doku und Erläuterung zu schreiben und es ist 
falsch diese Doku in den Papierkorb zu werfen. Und die commit-mesage ist 
nun mal das was einem Papierkorb am nächsten kommt, weil sie von den 
wenigsten Beteiligten gelesen wird. Oder gelesen werden kann... denn in 
einem source tar ball ist der commit-kommentare meist nicht enthalten.

Jörg W. schrieb:
> RuckZuckFresseDick schrieb:
>> Ich kann sehr wohl beurteilen,
>
> Nein, diese Fähigkeit spreche ich dir ab, da du absolut keine Ahnung
> hast, was an dieser Stelle tatsächlich passiert ist und wie das im
> Sourcecode dokumentiert ist.

Ich kann natürlich nursoviel Ahnung haben wie  dein zitierter beitrag 
zuläßt. Und da steht viele commitzeile für eine einzige Code-zeile.

Aber egal um wieviele LoC es geht, der Commitkommentar ist der falsche 
Ort für die Code-Doku - auch wenn das ein selbstgefälliger Moderator das 
kindischwerweise anders sieht.

Jörg W. schrieb:
> Das ist es auch nicht, und dein Irrtum wird nicht besser, wenn du jetzt
> anfängst, in die Schimpfwortkiste zu greifen.

Du kannst auch gleich noch mit dem Fuß aufstampfen, denn Dein Verhalten 
ist kein Deut besser. Aber egal, mein Posting wird eh gleich von Dir 
gelöscht.

Einer schrieb:
> Du kannst auch gleich noch mit dem Fuß aufstampfen

Ist nicht notwendig, denn Jörg hat recht.

gerne genommen "update" oder "x"

900ss D. schrieb:
> Aber ich hätte
> vermutlich den langen Text (commit Kommentar) in den Quelltext zur
> Änderung geschrieben und im commit Kommentar darauf deutlich
> hingewiesen.

Also erstens ist das keine lange Commitmessage.
Im OpenSource-Umfeld sind die Commitmessages in der Regel deutlich 
länger.

Zweitens beschreibt die Commitmessage im Beispiel - so wie es auch sein 
soll - zu 90% die Änderung, und nicht den geänderten Code.
Das ist ein Unterschied. Und das ist genau, wie es gedacht ist. Es wird 
nicht beschrieben, was der Code macht, sondern warum er geändert wird.

Und drittens fügt die Änderung einen Kommentar hinzu, der den Code 
genauer beschreibt.
Es bleibt keine Codebeschreibung in der Commitmessage übrig, die nicht 
auch im Code beschrieben wäre.

Jörg W. schrieb:
> RuckZuckFresseDick schrieb:
>> ist der falsche Ort für die Code-Doku
>
> Das ist es auch nicht, und dein Irrtum wird nicht besser, wenn du jetzt
> anfängst, in die Schimpfwortkiste zu greifen.

Oh, da entschuldige ich mich gleich, falls 'Moderator', 'selbstgefällig' 
und/oder 'kindisch' als Schimpfworte angesehen werden. Das ist 
keinesfalls als Beschimpfung gedacht, höchstens als eindringlich 
vorgetragenen Aufforderung nochmals das bisher Gesagte zu überdenken.

Ich seh da wirklich Diskussionsbedarf hinichtlich der Frage, ob ein 
commit-Kommentar wirklich der richtige Platz für eine Dokumentierenden 
Textpassage ist.  Insbesonders unter dem Aspekt der 'Sichtbarkeit', eben 
das Commit-Kommentare nicht Bestandteil des Softwarepaketes sind, die 
dann verteilt werden.  Nur der Depot-Verwalter sieht/braucht  diesen 
Commit.

Wenn man genötigt wird, Commit-Kommentare durchzusehen um die 
Funktionalität des Codes nachzuvollziehen, dann erinnerst das an den 
Hitchhiker Guide to the Galaxy" bei der sich ein Protagonist auch 
darüber beschwert, das Die Abrisspläne für sein Grundstück in einen 
finsteren schwer zugänglichen Keller 'ausgehangen waren'.

Ein commit Kommentar ist lediglich ein kurzer Hinweis was darin geändert 
wurde, aber keine Rechtfertigung desselben. Dehalb genügt ein Verweis 
auf den Änderungs- resp. Featurerequest/Spec..

RuckZuckFresseDick schrieb:
> ob ein
> commit-Kommentar wirklich der richtige Platz für eine Dokumentierenden
> Textpassage ist.

Was verstehst du unter "Dokumentierenden Textpassage"?
Wenn die Textpassage die Änderung dokumentiert, dann ist die 
Commitmessage genau der richtige Platz dafür.
Wenn die Textpassage den Code dokumentiert, dann ist die Commitmessage 
eventuell auch der richtige Platz dafür, wenn diese Textpassage 
zusätzlich zum Beispiel auch noch sinngemäß in der Doku oder im 
Kommentar auftaucht.

> Wenn man genötigt wird, Commit-Kommentare durchzusehen um die
> Funktionalität des Codes nachzuvollziehen

Niemand wird das.

> Ein commit Kommentar ist lediglich ein kurzer Hinweis was darin geändert
> wurde, aber keine Rechtfertigung desselben.

Eben doch. Die Rechtfertigung der Änderung ist der Hauptteil einer guten 
Commitmessage.

900ss D. schrieb:
> Seitenlang ist für mich lang.

Es ging um das gezeigte Beispiel, nicht?
Die ist nicht seitenlang, sondern nur ein paar kurze Sätze.

MaWin schrieb:
>> Wenn man genötigt wird, Commit-Kommentare durchzusehen um die
>> Funktionalität des Codes nachzuvollziehen
>
> Niemand wird das.
Doch, solange eben der Inhalt der commitmessage nicht irgendwo anders 
auftaucht. Deshalb die oben beschrieben Vorgehensweise, die seitenlange 
Begründung nicht in die commit-message zu packen sondern in die Doku die 
in dem comitteten Pakt beigefügt ist ...
aber vielleicht liegt ja genau hier der Denkfehler, zu glauben das nur 
source comittet wird und nicht gleichzeitig die Doku (ins doc-directory 
oder als source commentar.

dann hätte auch doxygen eine Chance diese zu finden ... als 
commit-message wäre das auch für doxygen verloren.

>> Ein commit Kommentar ist lediglich ein kurzer Hinweis was darin geändert
>> wurde, aber keine Rechtfertigung desselben.
>
> Eben doch. Die Rechtfertigung der Änderung ist der Hauptteil einer guten
> Commitmessage.
nein die commitmessage ist lediglich der verweis auf den Request der zu 
der Änderung geführt hat. Kein Start von Änderungsarbeiten ohne 
(triftigen) Anlaß- 'Rechtfertigung' klingt doch stark nach - ich hatte 
mal Langeweile und hab am Code rumgekritzelt und mir nachträglich ne 
Begründung einfallen lassen ...

MaWin O. schrieb:
> Wie dem auch sei. Eine seitenlange Commitmessage kann völlig in Ordnung
> sein, wenn sie die Änderung (nicht den Code) beschreibt.
> Falls sie den Code beschreibt, sollte diese Beschreibung
> selbstverständlich auch noch irgendwo anders existieren.

Wieso diese doppelte Existenz?

Die Änderung wir einmal beschrieben und diese Beschreibung wird als file 
oder eben fileänderung dem Commit beigefügt. Damit Fertig und 
nachvollziehbar bis in alle Ewigkeit.

MaWin O. schrieb:

> Das kommerzielle Umfeld sieht das in der Regel so wie du.
> Das OpenSource-Umfeld sieht das so wie wir.
>
> OpenSource hat Recht.

Na da denk ich mir einen smiley in das Zitat und alles ist Friede, 
Freude, Eierkuchen in der jeweiligen Blase ...

Da hat doch glatt einer seinen Account und Passwort wiedergefunden. :o))
Oder ist es der Falsche, der meinen Tipp übernommen hat? ;o))

Gastbeiträge werden hier im Forum ja mittlerweile von der Anzahl her 
begrenzt.

MaWin schrieb:
> Gastbeiträge werden hier im Forum ja mittlerweile von der Anzahl her
> begrenzt.

Die Beschränkung gibt es schon etwas länger. Wenn jetzt schon Freitag 
wäre, würden wir jetzt die Länge der Leitung in Lichjahren ausrechnen.
Zwölve in einer Stunde zu posten, geht durchaus problemlos. Ist alles 
nur eine Frage des Wissens, wie so was geht.

Was willst du mir mit diesem Beitrag sagen?

@TO
Mich würde mal interessieren welche Antwort du aus diesem 
Beitragsgefecht gewonnen hast. Also, wie Du nun gedenkst commit-Messages 
zu verfassen (oder auch nicht).

Vielleicht kannst Du dir ja mal diese Minute für ne Antwort Zeit nehmen.