Einzelne Patches

Der Befehl git send-email ist die beste Art, wie Sie sowohl einzelne Patches als auch Patch-Reihen (siehe Mehrere Patches) an die Guix-Mailing-Liste schicken können. Würden Sie Patches als E-Mail-Anhänge schicken, wäre es in manchen Mailprogrammen umständlich, diese zu überprüfen. Und wenn Sie aus git diff kopierten, würden die Metadaten des Commits fehlen.

Anmerkung: Der Befehl git send-email ist in der Ausgabe namens send-email des git-Pakets enthalten, also git:send-email.

Mit dem folgenden Befehl erzeugen Sie eine E-Mail mit dem Patch aus dem neuesten Commit, öffnen diese in Ihrem gewählten EDITOR oder VISUAL, um sie zu bearbeiten, und schicken sie an die Guix-Mailing-Liste, damit jemand sie überprüft und merget:

$ git send-email -1 -a --base=auto --to=guix-patches@gnu.org

Tipp: Wenn Sie in der Betreffzeile zu Ihrem Patch ein zusätzliches Präfix mitgeben möchten, können Sie die Befehlszeilenoption --subject-prefix benutzen. Beim Guix-Projekt wird so angegeben, dass der Patch für einen bestimmten Branch oder ein anderes Repository bestimmt ist, statt für den master-Branch von https://git.savannah.gnu.org/cgit/guix.git.

git send-email -1 -a --base=auto \
    --subject-prefix='PATCH core-updates' \
    --to=guix-patches@gnu.org

In der Patch-E-Mail finden Sie eine Trennlinie aus drei Bindestrichen unter der Commit-Nachricht. Sie dürfen erklärende Bemerkungen zum Patch unterhalb dieser Linie anbringen. Wenn Sie keine solchen Annotationen in der E-Mail schreiben möchten, können Sie oben auf die Befehlszeilenoption -a (der Abkürzung von --annotate) verzichten.

Mit der Befehlszeilenoption --base=auto wird automatisch eine Bemerkung zum Ende des Patches hinzugefügt, die angibt, auf welchem Commit der Patch basiert. Damit fällt es Betreuern leichter, Ihre Patches mit rebase zu übernehmen und zu mergen.

Wenn Sie einen überarbeiteten Patch schicken müssen, geht das anders. Machen Sie es nicht so und schicken Sie keinen Patch mit einem „Fix“, der als Nächstes angewandt werden müsste, sondern verwenden Sie stattdessen git commit -a oder git rebase, um den alten Commit zu verändern, und schicken den an die Adresse FEHLERNUMMER@debbugs.gnu.org, wobei Sie außerdem die Befehlszeilenoption -v von git send-email angeben.

$ git commit -a
$ git send-email -1 -a --base=auto -v REVISION \
      --to=FEHLERNUMMER@debbugs.gnu.org

Die FEHLERNUMMER finden Sie heraus, indem Sie entweder auf der Mumi-Oberfläche auf issues.guix.gnu.org nach dem Namen Ihres Patches suchen oder indem Sie in Ihren E-Mails auf die Eingangsbestätigung schauen, die Debbugs Ihnen automatisch als Antwort auf eingehende Fehlerberichte (Bugs) und Patches hat zukommen lassen. Darin finden Sie die Fehlernummer.

Teams ansprechen

Mit dem Skript etc/teams.scm können Sie direkt all die Leute in Kenntnis setzen, die sich für Ihren Patch interessieren könnten (siehe Teams). Benutzen Sie etc/teams.scm list-teams, um alle Teams angezeigt zu bekommen, damit Sie entscheiden können, welches Team oder welche Teams Ihr Patch betrifft, und sich mit etc/teams.scm cc die geeigneten Befehlszeilenoptionen für git send-email ausgeben lassen, um die richtigen Teammitglieder anzuschreiben; alternativ werden mit etc/teams.scm cc-members die Teams automatisch ermittelt.

Mehrere Patches

Obwohl git send-email allein für einen einzelnen Patch genügt, führt eine Unzulänglichkeit in Debbugs dazu, dass Sie beim Versenden mehrerer Patches achtgeben müssen: Wenn Sie alle auf einmal an die Adresse guix-patches@gnu.org schicken würden, würde für jeden Patch jeweils ein Fehlerbericht eröffnet!

Wenn Sie die Patches aber als Patch-Reihe abschicken wollen, sollten Sie als Erstes mit Git ein „Deckblatt“ schicken, das den Gutachtern einen Überblich über die Patch-Reihe gibt. Zum Beispiel können Sie ein Verzeichnis namens ausgehend anlegen und darin sowohl Ihre Patch-Reihe als auch ein Deckblatt namens 0000-cover-letter.patch platzieren, indem Sie git format-patch aufrufen.

$ git format-patch -ANZAHL_COMMITS -o ausgehend \
      --cover-letter --base=auto

Jetzt schicken Sie nur das Deckblatt an die Adresse guix-patches@gnu.org, so dass ein Fehlerbericht aufgemacht wird, an den wir dann die restlichen Patches schicken können.

$ git send-email ausgehend/0000-cover-letter.patch -a \
      --to=guix-patches@debbugs.gnu.org \
      $(etc/teams.scm cc-members …)
$ rm ausgehend/0000-cover-letter.patch # nicht nochmal schicken!

Passen Sie auf und bearbeiten die E-Mail nochmal, um ihr vor dem Abschicken eine angemessene Betreffzeile (Subject) und anstelle von Blurb Ihren Text mitzugeben. Sie werden bemerken, dass unterhalb des Textes automatisch ein Shortlog und Diffstat aufgelistet wurden.

Sobald Sie vom Debbugs-Mailer eine Antwort auf Ihre Deckblatt-E-Mail erhalten haben, können Sie die eigentlichen Patches an die neu erzeugte Adresse für diesen Fehlerbericht senden.

$ git send-email ausgehend/*.patch \
      --to=FEHLERNUMMER@debbugs.gnu.org \
      $(etc/teams.scm cc-members …)
$ rm -rf ausgehend # wir sind damit fertig

Zum Glück können wir uns diesen Tanz mit git format-patch danach sparen, wenn wir eine überarbeitete Patch-Reihe schicken, weil wir die Fehlernummer dann bereits haben.

$ git send-email -ANZAHL_COMMITS \
      -vREVISION --base=auto \
      --to FEHLERNUMMER@debbugs.gnu.org

Wenn nötig, können Sie mit --cover-letter -a auch dann ein weiteres Deckblatt mitschicken, z.B. um zu erklären, was die Änderungen seit der letzten Revision sind und warum sie nötig waren.