Einreichen von Patches (Referenzhandbuch zu GNU Guix)

22.6 Einreichen von Patches

Die Entwicklung wird mit Hilfe des verteilten Versionskontrollsystems Git durchgeführt. Daher ist eine ständige Verbindung zum Repository nicht unbedingt erforderlich. Wir begrüßen Beiträge in Form von Patches, die mittels git format-patch erstellt und an die Mailingliste guix-patches@gnu.org geschickt werden (siehe Submitting patches to a project in Git-Benutzerhandbuch). In diesem Fall möchten wir Ihnen nahelegen, zunächst einige Git-Repository-Optionen festzulegen (siehe Git einrichten), damit Ihr Patch leichter lesbar wird. Erfahrene Guix-Entwickler möchten vielleicht auch einen Blick auf den Abschnitt über Commit-Zugriff werfen (siehe Commit-Zugriff).

Diese Mailing-Liste setzt auf einer Debbugs-Instanz auf, wodurch wir den Überblick über Eingereichtes behalten können (siehe Überblick über gemeldete Fehler und Patches). Jede an diese Mailing-Liste gesendete Nachricht bekommt eine neue Folgenummer zugewiesen, so dass man eine Folge-E-Mail zur Einreichung an FEHLERNUMMER@debbugs.gnu.org senden kann, wobei FEHLERNUMMER für die Folgenummer steht (siehe Senden einer Patch-Reihe).

Bitte schreiben Sie Commit-Logs im ChangeLog-Format (siehe Change Logs in GNU Coding Standards); dazu finden Sie Beispiele unter den bisherigen Commits.

You can help make the review process more efficient, and increase the chance that your patch will be reviewed quickly, by describing the context of your patch and the impact you expect it to have. For example, if your patch is fixing something that is broken, describe the problem and how your patch fixes it. Tell us how you have tested your patch. Will users of the code changed by your patch have to adjust their workflow at all? If so, tell us how. In general, try to imagine what questions a reviewer will ask, and answer those questions in advance.

Bevor Sie einen Patch einreichen, der eine Paketdefinition hinzufügt oder verändert, gehen Sie bitte diese Prüfliste durch:

Wenn die Autoren der verpackten Software eine kryptografische Signatur bzw. Beglaubigung für den Tarball der Veröffentlichung anbieten, so machen Sie sich bitte die Mühe, die Echtheit des Archivs zu überprüfen. Für eine abgetrennte GPG-Signaturdatei würden Sie das mit dem Befehl gpg --verify tun.
Nehmen Sie sich die Zeit, eine passende Zusammenfassung und Beschreibung für das Paket zu verfassen. Unter Zusammenfassungen und Beschreibungen finden Sie dazu einige Richtlinien.
Verwenden Sie guix lint Paket, wobei Paket das neue oder geänderte Paket bezeichnet, und beheben Sie alle gemeldeten Fehler (siehe Aufruf von guix lint).
Verwenden Sie guix style Paket, um die neue Paketdefinition gemäß den Konventionen des Guix-Projekts zu formatieren (siehe Aufruf von guix style).
Stellen Sie sicher, dass das Paket auf Ihrer Plattform erstellt werden kann, indem Sie guix build Paket ausführen.
Wir empfehlen, dass Sie auch versuchen, das Paket auf anderen unterstützten Plattformen zu erstellen. Da Sie vielleicht keinen Zugang zu echter Hardware für diese Plattformen haben, empfehlen wir, den qemu-binfmt-service-type zu benutzen, um sie zu emulieren. Um ihn zu aktivieren, fügen Sie virtualization zu use-service-modules und den folgenden Dienst in die Liste der Dienste („services“) in Ihrer operating-system-Konfiguration ein:
```
(service qemu-binfmt-service-type
 (qemu-binfmt-configuration
   (platforms (lookup-qemu-platforms "arm" "aarch64"))))
```
Rekonfigurieren Sie anschließend Ihr System.

Sie können Pakete für andere Plattformen erstellen lassen, indem Sie die Befehlszeilenoption --system angeben. Um zum Beispiel das Paket „hello“ für die Architekturen armhf oder aarch64 erstellen zu lassen, würden Sie jeweils die folgenden Befehle angeben:
```
guix build --system=armhf-linux --rounds=2 hello
guix build --system=aarch64-linux --rounds=2 hello
```
Achten Sie darauf, dass im Paket keine Software gebündelt mitgeliefert wird, die bereits in separaten Paketen zur Verfügung steht.
Manchmal enthalten Pakete Kopien des Quellcodes ihrer Abhängigkeiten, um Nutzern die Installation zu erleichtern. Als eine Distribution wollen wir jedoch sicherstellen, dass solche Pakete die schon in der Distribution verfügbare Fassung benutzen, sofern es eine gibt. Dadurch wird sowohl der Ressourcenverbrauch optimiert (die Abhängigkeit wird so nur einmal erstellt und gespeichert) als auch der Distribution die Möglichkeit gegeben, ergänzende Änderungen durchzuführen, um beispielsweise Sicherheitsaktualisierungen für ein bestimmtes Paket an nur einem Ort einzuspielen, die aber das gesamte System betreffen – gebündelt mitgelieferte Kopien würden dies verhindern.
Schauen Sie sich das von guix size ausgegebene Profil an (siehe Aufruf von guix size). Dadurch können Sie Referenzen auf andere Pakete finden, die ungewollt vorhanden sind. Dies kann auch dabei helfen, zu entscheiden, ob das Paket aufgespalten werden sollte (siehe Pakete mit mehreren Ausgaben.) und welche optionalen Abhängigkeiten verwendet werden sollten. Dabei sollten Sie es wegen seiner enormen Größe insbesondere vermeiden, texlive als eine Abhängigkeit hinzuzufügen; benutzen Sie stattdessen das Paket texlive-tiny oder die Prozedur texlive-union.
Achten Sie bei wichtigen Änderungen darauf, dass abhängige Pakete (falls vorhanden) nicht von der Änderung beeinträchtigt werden; guix refresh --list-dependent Paket hilft Ihnen dabei (siehe Aufruf von guix refresh).
Je nachdem, wie viele abhängige Pakete es gibt, und entsprechend wie viele Neuerstellungen dadurch nötig würden, finden Commits auf anderen Branches statt, nach ungefähr diesen Regeln:

300 abhängige Pakete oder weniger

master-Branch (störfreie Änderungen).

zwischen 300 und 1.800 abhängige Pakete

staging-Branch (störfreie Änderungen). Dieser Branch wird circa alle 6 Wochen mit master zusammengeführt. Themenbezogene Änderungen (z.B. eine Aktualisierung der GNOME-Plattform) können stattdessen auch auf einem eigenen Branch umgesetzt werden (wie gnome-updates). Dieser Branch ist erst spät im Entwicklungsprozess nutzbar.

mehr als 1.800 abhängige Pakete

core-updates-Branch (kann auch größere und womöglich andere Software beeinträchtigende Änderungen umfassen). Dieser Branch wird planmäßig in master alle 6 Monate oder so gemerget. Dieser Branch ist erst spät im Entwicklungsprozess nutzbar.

All diese Branches werden kontinuierlich auf unserer Erstellungsfarm erstellt und in master gemerget, sobald alles erfolgreich erstellt worden ist. Dadurch können wir Probleme beheben, bevor sie bei Nutzern auftreten, und zudem das Zeitfenster, während dessen noch keine vorerstellten Binärdateien verfügbar sind, verkürzen.

Sobald wir uns dazu entscheiden, einen der Branches staging oder core-updates zu erstellen, spalten wir einen neuen Branch davon ab und hängen an seinen Namen das Suffix -frozen an. Auf einen „frozen“-Branch dürfen dann nur noch Fehlerbehebungen gepusht werden. Die Branches core-updates und staging bleiben offen; dorthin gehen Patches für den nächsten Durchlauf. Bitte fragen Sie auf der Mailing-Liste oder im IRC nach, wenn Sie sich unsicher sind, wohin ein Patch gehört.
Überprüfen Sie, ob der Erstellungsprozess deterministisch ist. Dazu prüfen Sie typischerweise, ob eine unabhängige Erstellung des Pakets genau dasselbe Ergebnis wie Ihre Erstellung hat, Bit für Bit.
Dies können Sie leicht tun, indem Sie dasselbe Paket mehrere Male hintereinander auf Ihrer Maschine erstellen (siehe Aufruf von guix build):
```
guix build --rounds=2 mein-paket
```
Dies reicht aus, um eine ganze Klasse häufiger Ursachen von Nichtdeterminismus zu finden, wie zum Beispiel Zeitstempel oder zufallsgenerierte Ausgaben im Ergebnis der Erstellung.

Eine weitere Möglichkeit ist, guix challenge (siehe Aufruf von guix challenge) zu benutzen. Sie können es ausführen, sobald ein Paket commitet und von ci.guix.gnu.org erstellt wurde, um zu sehen, ob dort dasselbe Ergebnis wie bei Ihnen geliefert wurde. Noch besser: Finden Sie eine andere Maschine, die das Paket erstellen kann, und führen Sie guix publish aus. Da sich die entfernte Erstellungsmaschine wahrscheinlich von Ihrer unterscheidet, können Sie auf diese Weise Probleme durch Nichtdeterminismus erkennen, die mit der Hardware zu tun haben – zum Beispiel die Nutzung anderer Befehlssatzerweiterungen – oder mit dem Betriebssystem-Kernel – zum Beispiel, indem uname oder /proc-Dateien verwendet werden.
Beim Schreiben von Dokumentation achten Sie bitte auf eine geschlechtsneutrale Wortwahl, wenn Sie sich auf Personen beziehen, wie „they“, „their“, „them“ im Singular und so weiter.
Stellen Sie sicher, dass Ihr Patch nur einen Satz zusammengehöriger Änderungen umfasst. Das Zusammenfassen nicht zusammengehöriger Änderungen erschwert und bremst das Durchsehen Ihres Patches.
Beispiele für nicht zusammengehörige Änderungen sind das Hinzufügen mehrerer Pakete auf einmal, oder das Aktualisieren eines Pakets auf eine neue Version zusammen mit Fehlerbehebungen für das Paket.
Bitte befolgen Sie unsere Richtlinien für die Code-Formatierung; womöglich wollen Sie dies automatisch tun lassen durch das Skript guix style (siehe Formatierung von Code).
Benutzen Sie, wenn möglich, Spiegelserver (Mirrors) in der Quell-URL (siehe Aufruf von guix download). Verwenden Sie verlässliche URLs, keine automatisch generierten. Zum Beispiel sind Archive von GitHub nicht immer identisch von einer Generation auf die nächste, daher ist es in diesem Fall besser, als Quelle einen Klon des Repositorys zu verwenden. Benutzen Sie nicht das name-Feld beim Angeben der URL; er hilft nicht wirklich und wenn sich der Name ändert, stimmt die URL nicht mehr.
Überprüfen Sie, ob Guix erstellt werden kann (siehe Erstellung aus dem Git) und kümmern Sie sich um die Warnungen, besonders um solche über nicht definierte Symbole.
Stellen Sie sicher, dass Ihre Änderungen Guix nicht beeinträchtigen, und simulieren Sie eine Ausführung von guix pull über den Befehl:
```
guix pull --url=/pfad/zu/ihrem/checkout --profile=/tmp/guix.master
```

Bitte benutzen Sie ‘[PATCH] …’ als Betreff, wenn Sie einen Patch an die Mailing-Liste schicken. Soll Ihr Patch auf einen anderen Branch als master angewandt werden, z.B. core-updates, geben Sie dies im Betreff an als ‘[PATCH core-updates] …’.

Sie können dazu Ihr E-Mail-Programm oder den Befehl git send-email benutzen (siehe Senden einer Patch-Reihe). Wir bevorzugen es, Patches als reine Textnachrichten zu erhalten, entweder eingebettet (inline) oder als MIME-Anhänge. Sie sind dazu angehalten, zu überprüfen, ob Ihr Mail-Programm solche Dinge wie Zeilenumbrüche oder die Einrückung verändert, wodurch die Patches womöglich nicht mehr funktionieren.

Rechnen Sie damit, dass es etwas dauert, bis Ihr erster Patch an guix-patches@gnu.org zu sehen ist. Sie werden warten müssen, bis Sie eine Bestätigung mit der zugewiesenen Folgenummer bekommen. Spätere Bestätigungen sollten sofort kommen.

Wenn dadurch ein Fehler behoben wurde, schließen Sie bitte den Thread, indem Sie eine E-Mail an FEHLERNUMMER-done@debbugs.gnu.org senden.