Nächste: , Vorige: , Nach oben: Mitwirken   [Inhalt][Index]

22.10 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 Änderungen). 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.

Sie können dabei helfen, dass die Überprüfung Ihres Patches schneller vonstattengeht und die Wahrscheinlichkeit erhöhen, dass sich bald jemand den Patch anschaut: Beschreiben Sie die Umstände des Patches und wie er sich auswirken dürfte. Zum Beispiel, wenn etwas kaputt ist und der Patch das behebt, dann beschreiben Sie das Problem und wie es in Ihrem Patch behoben wird. Müssen die Verwender des betroffenen Codes dazu ihre Arbeitsweise ändern oder nicht? Wenn doch, schreiben Sie wie. Allgemein sollten Sie sich vorstellen, welche Fragen ein Überprüfender stellen würde, und diese im Voraus beantworten.

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

  1. 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.
  2. 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.
  3. Verwenden Sie guix lint Paket, wobei Paket das neue oder geänderte Paket bezeichnet, und beheben Sie alle gemeldeten Fehler (siehe guix lint aufrufen).
  4. Verwenden Sie guix style Paket, um die neue Paketdefinition gemäß den Konventionen des Guix-Projekts zu formatieren (siehe guix style aufrufen).
  5. Make sure the package builds on your platform, using guix build package. Also build at least its direct dependents with guix build --dependents=1 package (siehe guix build).
  6. 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
  7. 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.

  8. Schauen Sie sich das von guix size ausgegebene Profil an (siehe guix size aufrufen). 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 die Prozedur texlive-updmap.cfg.
  9. Achten Sie darauf, dass abhängige Pakete (falls vorhanden) nicht von der Änderung beeinträchtigt werden; guix refresh --list-dependent Paket hilft Ihnen dabei (siehe guix refresh aufrufen).
  10. Ü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 guix challenge aufrufen) zu benutzen. Sie können es ausführen, sobald ein Paket commitet und von bordeaux.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.

  11. 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.
  12. 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.

  13. 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).
  14. Benutzen Sie, wenn möglich, Spiegelserver (Mirrors) in der Quell-URL (siehe guix download aufrufen). 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.
  15. Ü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.
  16. 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, den Befehl git send-email (siehe Senden einer Patch-Reihe) oder den Befehl mumi send-email benutzen (siehe Debbugs-Benutzerschnittstellen). 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.

Nächste: Überblick über gemeldete Fehler und Änderungen, Vorige: Programmierstil, Nach oben: Mitwirken   [Inhalt][Index]