@node Mitwirken
@chapter Mitwirken

Dieses Projekt basiert auf Kooperation, daher benötigen wir Ihre Hilfe, um
es wachsen zu lassen! Bitte kontaktieren Sie uns auf
@email{guix-devel@@gnu.org} und @code{#guix} im Freenode-IRC-Netzwerk. Wir
freuen uns auf Ihre Ideen, Fehlerberichte, Patches und alles, was hilfreich
für das Projekt sein könnte. Besonders willkommen ist Hilfe bei der
Erstellung von Paketen (siehe @ref{Paketrichtlinien}).

@cindex Verhaltensregeln, für Mitwirkende
@cindex Verhaltenskodex für Mitwirkende
Wir möchten eine angenehme, freundliche und von Belästigungen freie Umgebung
bereitstellen, so dass jeder Beiträge nach seinen Fähigkeiten leisten
kann. Zu diesem Zweck verwendet unser Projekt einen „Verhaltenskodex für
Mitwirkende“, der von @url{https://contributor-covenant.org/} übernommen
wurde. Eine übersetzte Fassung finden Sie auf
@url{https://www.contributor-covenant.org/de/version/1/4/code-of-conduct}
sowie eine mitgelieferte, englische Fassung in der Datei
@file{CODE-OF-CONDUCT} im Quellbaum.

Von Mitwirkenden wird nicht erwartet, dass sie in Patches oder in der
Online-Kommunikation ihre echten Namen preisgeben. Sie können einen
beliebigen Namen oder ein Pseudonym ihrer Wahl verwenden.

@menu
* Erstellung aus dem Git::   Das Neueste und Beste.
* Guix vor der Installation ausführen::  Hacker-Tricks.
* Perfekt eingerichtet::     Die richtigen Werkzeuge.
* Paketrichtlinien::         Die Distribution wachsen lassen.
* Programmierstil::          Wie Mitwirkende hygienisch arbeiten.
* Einreichen von Patches::   Teilen Sie Ihre Arbeit.
* Überblick über gemeldete Fehler und Patches::  Debbugs benutzen.
* Commit-Zugriff::           Auf die offiziellen Repositorys pushen.
* Das Guix-Paket aktualisieren::  Die Paketdefinition für Guix erneuern.
@end menu

@node Erstellung aus dem Git
@section Erstellung aus dem Git

Wenn Sie an Guix selbst hacken wollen, ist es empfehlenswert, dass Sie die
neueste Version aus dem Git-Softwarebestand verwenden:

@example
git clone https://git.savannah.gnu.org/git/guix.git
@end example

@cindex Authentifizieren, eines Guix-Checkouts
Doch wie können Sie sichergehen, dass sie eine unverfälschte Kopie des
Repositorys erhalten haben? Dazu müssen Sie @command{guix git authenticate}
ausführen, wobei Sie den Commit und den OpenPGP-Fingerabdruck der
@dfn{Kanaleinführung} angeben (siehe @ref{Aufruf von guix git authenticate}):

@c ===========================================================================
@c
@c This file was generated with po4a. Translate the source file.
@c
@c ===========================================================================

@c The commit and fingerprint below must match those of the channel
@c introduction in '%default-channels'.
@example
git fetch origin keyring:keyring
guix git authenticate 9edb3f66fd807b096b48283debdcddccfea34bad \
  "BBB0 2DDF 2CEA F6A8 0D1D  E643 A2A0 6DF2 A33A 54FA"
@end example

@noindent
Dieser Befehl gibt bei Erfolg am Ende null als Exit-Status zurück, ansonsten
wird eine Fehlermeldung ausgegeben und ein anderer Exit-Status
zurückgegeben.

Wie Sie sehen können, liegt hier ein Henne-Ei-Problem vor: Sie müssen Guix
zuvor bereits installiert haben. Üblicherweise würden Sie Guix System erst
auf einem anderen System installieren (siehe @ref{Systeminstallation}) oder
Guix auf einer anderen Distribution installieren (siehe @ref{Aus Binärdatei installieren}); in beiden Fällen würden Sie die OpenPGP-Signatur auf dem
Installationsmedium prüfen. Damit haben Sie ein „Bootstrapping“ der
Vertrauenskette durchgeführt.

Der einfachste Weg, eine Entwicklungsumgebung für Guix einzurichten, ist
natürlich, Guix zu benutzen! Der folgende Befehl startet eine neue Shell, in
der alle Abhängigkeiten und Umgebungsvariablen bereits eingerichtet sind, um
an Guix zu arbeiten:

@example
guix environment guix --pure
@end example

Siehe @ref{Aufruf von guix environment} für weitere Informationen zu diesem
Befehl.

Wenn Sie Guix nicht benutzen können, wenn Sie es aus einem Checkout
erstellen, werden die folgenden Pakete zusätzlich zu denen benötigt, die in
den Installationsanweisungen angegeben sind (siehe @ref{Voraussetzungen}).

@itemize
@item @url{https://gnu.org/software/autoconf/, GNU Autoconf},
@item @url{https://gnu.org/software/automake/, GNU Automake},
@item @url{https://gnu.org/software/gettext/, GNU Gettext},
@item @url{https://gnu.org/software/texinfo/, GNU Texinfo},
@item @url{https://www.graphviz.org/, Graphviz},
@item @url{https://www.gnu.org/software/help2man/, GNU Help2man (optional)}.
@end itemize

Auf Guix können zusätzliche Abhängigkeiten hinzugefügt werden, indem Sie
stattdessen @command{guix environment} mit @option{--ad-hoc} ausführen:

@example
guix environment guix --pure --ad-hoc help2man git strace
@end example

Führen Sie @command{./bootstrap} aus, um die Infrastruktur des
Erstellungssystems mit Autoconf und Automake zu erzeugen. Möglicherweise
erhalten Sie eine Fehlermeldung wie diese:

@example
configure.ac:46: error: possibly undefined macro: PKG_CHECK_MODULES
@end example

@noindent
Das bedeutet wahrscheinlich, dass Autoconf @file{pkg.m4} nicht finden
konnte, welches von pkg-config bereitgestellt wird. Stellen Sie sicher, dass
@file{pkg.m4} verfügbar ist. Gleiches gilt für den von Guile
bereitgestellten Makrosatz @file{guile.m4}. Wenn Sie beispielsweise Automake
in @file{/usr/local} installiert haben, würde in @file{/usr/share} nicht
nach @file{.m4}-Dateien geschaut. In einem solchen Fall müssen Sie folgenden
Befehl aufrufen:

@example
export ACLOCAL_PATH=/usr/share/aclocal
@end example

In @ref{Macro Search Path,,, automake, The GNU Automake Manual} finden Sie
weitere Informationen.

Dann führen Sie wie gewohnt @command{./configure} aus. Achten Sie darauf,
@code{--localstatedir=@var{Verzeichnis}} zu übergeben, wobei
@var{Verzeichnis} der von Ihrer aktuellen Installation verwendete
@code{localstatedir}-Wert ist (weitere Informationen siehe @ref{Der Store}),
im Normalfall geben Sie @file{/var} an. Denken Sie daran, dass Sie am Ende
wahrscheinlich @emph{nicht} @command{make install} ausführen möchten (müssen
Sie auch nicht), aber es ist dennoch wichtig, die richtige
@code{localstatedir} zu übergeben.

Zum Schluss müssen Sie @code{make && make check} aufrufen, um Guix zu
erstellen und die Tests auszuführen (siehe @ref{Den Testkatalog laufen lassen}). Falls etwas fehlschlägt, werfen Sie einen Blick auf die
Installationsanweisungen (siehe @ref{Installation}) oder senden Sie eine
E-Mail an die @email{guix-devel@@gnu.org, Mailingliste}.

Von da an können Sie alle Commits in Ihrem Checkout authentifizieren, indem
Sie dies ausführen:

@example
make authenticate
@end example

Die erste Ausführung dauert ein paar Minuten, aber nachfolgende Ausführungen
gehen schneller.

Für den Fall, dass die Konfiguration Ihres lokal verfügbaren Git-Repositorys
nicht der voreingestellten entspricht, können Sie die Referenz für den
@code{keyring}-Branch über die Variable @code{GUIX_GIT_KEYRING} angeben. Im
folgenden Beispiel nehmen wir an, Sie haben ein Remote-Repository namens
@samp{myremote} eingerichtet, das auf das offizielle Guix-Repository
verweist:

@example
make authenticate GUIX_GIT_KEYRING=myremote/keyring
@end example

@quotation Anmerkung
Wir raten Ihnen dazu, nach jedem Aufruf von @command{git pull} auch
@command{make authenticate} auszuführen. Das stellt sicher, dass Sie
weiterhin nur gültige Änderungen in Ihr Repository übernehmen.
@end quotation


@node Guix vor der Installation ausführen
@section Guix vor der Installation ausführen

Um eine gesunde Arbeitsumgebung zu erhalten, ist es hilfreich, die im
lokalen Quellbaum vorgenommenen Änderungen zunächst zu testen, ohne sie
tatsächlich zu installieren. So können Sie zwischen Ihrem
Endnutzer-„Straßenanzug“ und Ihrem „Faschingskostüm“ unterscheiden.

Zu diesem Zweck können alle Befehlszeilenwerkzeuge auch schon benutzt
werden, ohne dass Sie @code{make install} laufen lassen. Dazu müssen Sie
sich in einer Umgebung befinden, in der alle Abhängigkeiten von Guix
verfügbar sind (siehe @ref{Erstellung aus dem Git}) und darin einfach vor jeden
Befehl @command{./pre-inst-env} schreiben (das Skript @file{pre-inst-env}
befindet sich auf oberster Ebene im Verzeichnis, wo Guix erstellt wird; es
wird durch Ausführung von @command{./bootstrap} gefolgt von
@command{./configure} erzeugt). Zum Beispiel würden Sie so das Paket
@code{hello} erstellen lassen, so wie es in der gegenwärtigen Kopie des
Guix-Quellbaums definiert wurde (es wird angenommen, dass
@command{guix-daemon} auf Ihrem System bereits läuft, auch wenn es eine
andere Version ist):

@example
$ ./pre-inst-env guix build hello
@end example

@noindent
Entsprechend würden Sie dies eingeben, um eine Guile-Sitzung zu öffnen, die
die Guix-Module benutzt:

@example
$ ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))'

;;; ("x86_64-linux")
@end example

@noindent
@cindex REPL
@cindex Lese-Auswerten-Schreiben-Schleife
…@: und auf einer REPL (siehe @ref{Using Guile Interactively,,, guile,
Guile-Referenzhandbuch}):

@example
$ ./pre-inst-env guile
scheme@@(guile-user)> ,use(guix)
scheme@@(guile-user)> ,use(gnu)
scheme@@(guile-user)> (define snakes
                       (fold-packages
                         (lambda (package lst)
                           (if (string-prefix? "python"
                                               (package-name package))
                               (cons package lst)
                               lst))
                         '()))
scheme@@(guile-user)> (length snakes)
$1 = 361
@end example

Wenn Sie am Daemon und damit zu tun habendem Code hacken oder wenn
@command{guix-daemon} nicht bereits auf Ihrem System läuft, können Sie ihn
direkt aus dem Verzeichnis heraus starten, wo Sie Guix erstellen
lassen@footnote{Die Befehlszeilenoption @option{-E} von @command{sudo}
stellt sicher, dass @code{GUILE_LOAD_PATH} richtig gesetzt wird, damit
@command{guix-daemon} und die davon benutzten Werkzeuge die von ihnen
benötigten Guile-Module finden können.}:

@example
$ sudo -E ./pre-inst-env guix-daemon --build-users-group=guixbuild
@end example

Das @command{pre-inst-env}-Skript richtet alle Umgebungsvariablen ein, die
nötig sind, um dies zu ermöglichen, einschließlich @env{PATH} und
@env{GUILE_LOAD_PATH}.

Beachten Sie, dass @command{./pre-inst-env guix pull} den lokalen Quellbaum
@emph{nicht} aktualisiert; es aktualisiert lediglich die symbolische
Verknüpfung @file{~/.config/guix/current} (siehe @ref{Aufruf von guix pull}). Um Ihren lokalen Quellbaum zu aktualisieren, müssen Sie stattdessen
@command{git pull} benutzen.


@node Perfekt eingerichtet
@section Perfekt eingerichtet

Um perfekt für das Hacken an Guix eingerichtet zu sein, brauchen Sie an sich
dasselbe wie um perfekt für das Hacken mit Guile (siehe @ref{Using Guile in
Emacs,,, guile, Guile-Referenzhandbuch}). Zunächst brauchen Sie mehr als ein
Textverarbeitungsprogramm, Sie brauchen
@url{https://www.gnu.org/software/emacs, Emacs} zusammen mit den vom
wunderbaren @url{https://nongnu.org/geiser/, Geiser} verliehenen Kräften. Um
diese zu installieren, können Sie Folgendes ausführen:

@example
guix package -i emacs guile emacs-geiser
@end example

Geiser ermöglicht interaktive und inkrementelle Entwicklung aus Emacs
heraus: Code kann in Puffern kompiliert und ausgewertet werden. Zugang zu
Online-Dokumentation (Docstrings) steht ebenso zur Verfügung wie
kontextabhängige Vervollständigung, @kbd{M-.} um zu einer Objektdefinition
zu springen, eine REPL, um Ihren Code auszuprobieren, und mehr (siehe
@ref{Einführung,,, geiser, Geiser User Manual}). Zur bequemen
Guix-Entwicklung sollten Sie Guiles Ladepfad so ergänzen, dass die
Quelldateien in Ihrem Checkout gefunden werden.

@lisp
;; @r{Angenommen das Guix-Checkout ist in ~/src/guix.}
(with-eval-after-load 'geiser-guile
  (add-to-list 'geiser-guile-load-path "~/src/guix"))
@end lisp

Um den Code tatsächlich zu bearbeiten, bietet Emacs schon einen netten
Scheme-Modus. Aber Sie dürfen auch
@url{https://www.emacswiki.org/emacs/ParEdit, Paredit} nicht verpassen. Es
bietet Hilfsmittel, um direkt mit dem Syntaxbaum zu arbeiten, und kann so
zum Beispiel einen S-Ausdruck hochheben oder ihn umhüllen, ihn verschlucken
oder den nachfolgenden S-Ausdruck verwerfen, etc.

@cindex Code-Schnipsel
@cindex Vorlagen
@cindex Tipparbeit sparen
Wir bieten auch Vorlagen für häufige Git-Commit-Nachrichten und
Paketdefinitionen im Verzeichnis @file{etc/snippets}. Diese Vorlagen können
mit @url{https://joaotavora.github.io/yasnippet/, YASnippet} zusammen
benutzt werden, um kurze Auslöse-Zeichenketten zu interaktiven
Textschnipseln umzuschreiben. Vielleicht möchten Sie das
Schnipselverzeichnis zu Ihrer @var{yas-snippet-dirs}-Variablen in Emacs
hinzufügen.

@lisp
;; @r{Angenommen das Guix-Checkout ist in ~/src/guix.}
(with-eval-after-load 'yasnippet
  (add-to-list 'yas-snippet-dirs "~/src/guix/etc/snippets"))
@end lisp

Die Schnipsel für Commit-Nachrichten setzen @url{https://magit.vc/, Magit}
voraus, um zum Commit vorgemerkte Dateien anzuzeigen. Wenn Sie eine
Commit-Nachricht bearbeiten, können Sie @code{add} gefolgt von @kbd{TAB}
eintippen, um eine Commit-Nachrichten-Vorlage für das Hinzufügen eines
Pakets zu erhalten; tippen Sie @code{update} gefolgt von @kbd{TAB} ein, um
eine Vorlage zum Aktualisieren eines Pakets zu bekommen; tippen Sie
@code{https} gefolgt von @kbd{TAB} ein, um eine Vorlage zum Ändern der
Homepage-URI eines Pakets auf HTTPS einzufügen.

Das Hauptschnipsel für @code{scheme-mode} wird ausgelöst, indem Sie
@code{package...} gefolgt von @kbd{TAB} eintippen. Dieses Snippet fügt auch
die Auslöse-Zeichenkette @code{origin...} ein, die danach weiter
umgeschrieben werden kann. Das @code{origin}-Schnipsel kann wiederum andere
Auslöse-Zeichenketten einfügen, die alle auf @code{...} enden, was selbst
wieder weiter umgeschrieben werden kann.

@cindex Copyright einfügen oder aktualisieren
@cindex @code{M-x guix-copyright}
@cindex @code{M-x copyright-update}
Außerden stellen wir automatisches Einfügen und Aktualisieren von
Urheberrechtsinformationen („Copyright“) über @file{etc/copyright.el} zur
Verfügung. Dazu müssten Sie Ihren vollständigen Namen mit E-Mail-Adresse
festlegen und eine Datei laden.

@lisp
(setq user-full-name "Alice Doe")
(setq user-mail-address "alice@@mail.org")
;; @r{Assuming the Guix checkout is in ~/src/guix.}
(load-file "~/src/guix/etc/copyright.el")
@end lisp

Um an der aktuellen Zeile Copyright-Informationen einzufügen, rufen Sie
@code{M-x guix-copyright} auf.

Um Copyright-Informationen aktualisieren zu können, müssen Sie einen
regulären Ausdruck @code{copyright-names-regexp} angeben.

@lisp
(setq copyright-names-regexp
      (format "%s <%s>" user-full-name user-mail-address))
@end lisp

Sie können prüfen, ob Ihre Urheberrechtsinformationen aktuell sind, indem
Sie @code{M-x copyright-update} auswerten. Wenn Sie möchten, dass dies
automatisch nach jedem Speichern des Puffers geschieht, fügen Sie
@code{(add-hook 'after-save-hook 'copyright-update)} in Emacs hinzu.

@node Paketrichtlinien
@section Paketrichtlinien

@cindex Pakete definieren
Die GNU-Distribution ist noch sehr jung und einige Ihrer Lieblingspakete
könnten noch fehlen. Dieser Abschnitt beschreibt, wie Sie dabei helfen
können, die Distribution wachsen zu lassen.

Pakete mit freier Software werden normalerweise in Form von @dfn{Tarballs
mit dem Quellcode} angeboten — typischerweise in
@file{tar.gz}-Archivdateien, in denen alle Quelldateien enthalten sind. Ein
Paket zur Distribution hinzuzufügen, bedeutet also zweierlei Dinge: Zum
einen fügt man ein @dfn{Rezept} ein, das beschreibt, wie das Paket erstellt
werden kann, einschließlich einer Liste von anderen Paketen, die für diese
Erstellung gebraucht werden, zum anderen fügt man @dfn{Paketmetadaten} zum
Rezept hinzu, wie zum Beispiel eine Beschreibung und Lizenzinformationen.

In Guix sind all diese Informationen ein Teil der
@dfn{Paketdefinitionen}. In Paketdefinitionen hat man eine abstrahierte,
hochsprachliche Sicht auf das Paket. Sie werden in der Syntax der
Scheme-Programmiersprache verfasst; tatsächlich definieren wir für jedes
Paket eine Variable und binden diese an dessen Definition, um die Variable
anschließend aus einem Modul heraus zu exportieren (siehe @ref{Paketmodule}). Allerdings ist @emph{kein} tiefgehendes Wissen über Scheme
erforderlich, um Pakete zu erstellen. Mehr Informationen über
Paketdefinitionen finden Sie im Abschnitt @ref{Pakete definieren}.

Eine fertige Paketdefinition kann, nachdem sie in eine Datei im
Quell-Verzeichnisbaum von Guix eingesetzt wurde, mit Hilfe des Befehls
@command{guix build} getestet werden (siehe @ref{Aufruf von guix build}). Wenn
das Paket zum Beispiel den Namen @code{gnew} trägt, können Sie folgenden
Befehl aus dem Erstellungs-Verzeichnisbaum von Guix heraus ausführen (siehe
@ref{Guix vor der Installation ausführen}):

@example
./pre-inst-env guix build gnew --keep-failed
@end example

Wenn Sie @code{--keep-failed} benutzen, ist es leichter, fehlgeschlagene
Erstellungen zu untersuchen, weil dann der Verzeichnisbaum der
fehlgeschlagenen Erstellung zugänglich bleibt. Eine andere nützliche
Befehlszeilenoption bei der Fehlersuche ist @code{--log-file}, womit das
Erstellungsprotokoll eingesehen werden kann.

Wenn der @command{guix}-Befehl das Paket nicht erkennt, kann es daran
liegen, dass die Quelldatei einen Syntaxfehler hat oder ihr eine
@code{define-public}-Klausel fehlt, die die Paketvariable exportiert. Um das
herauszufinden, können Sie das Modul aus Guile heraus laden, um mehr
Informationen über den tatsächlichen Fehler zu bekommen:

@example
./pre-inst-env guile -c '(use-modules (gnu packages gnew))'
@end example

Sobald Ihr Paket erfolgreich erstellt werden kann, schicken Sie uns bitte
einen Patch (siehe @ref{Einreichen von Patches}). Wenn Sie dabei Hilfe brauchen
sollten, helfen wir gerne. Ab dem Zeitpunkt, zu dem der Patch als Commit ins
Guix-Repository eingepflegt wurde, wird das neue Paket automatisch durch
@url{@value{SUBSTITUTE-URL}, unser System zur Kontinuierlichen Integration}
auf allen unterstützten Plattformen erstellt.

@cindex Substituierer
Benutzern steht die neue Paketdefinition zur Verfügung, nachdem sie das
nächste Mal @command{guix pull} ausgeführt haben (siehe @ref{Aufruf von guix pull}). Wenn @code{@value{SUBSTITUTE-SERVER}} selbst damit fertig ist, das
Paket zu erstellen, werden bei der Installation automatisch Binärdateien von
dort heruntergeladen (siehe @ref{Substitute}). Menschliches Eingreifen muss
nur stattfinden, um den Patch zu überprüfen und anzuwenden.


@menu
* Software-Freiheit::        Was in die Distribution aufgenommen werden 
                               darf.
* Paketbenennung::           Was macht einen Namen aus?
* Versionsnummern::          Wenn der Name noch nicht genug ist.
* Zusammenfassungen und Beschreibungen::  Den Nutzern helfen, das richtige 
                                            Paket zu finden.
* „Snippets“ oder Phasen::  Benutzt man Code-Schnipsel oder eine 
                                  Erstellungsphase?
* Emacs-Pakete::             Für Ihren Elisp-Bedarf.
* Python-Module::            Ein Touch britischer Comedy.
* Perl-Module::              Kleine Perlen.
* Java-Pakete::              Kaffeepause.
* Rust-Crates::              Umgang mit Oxidation.
* Schriftarten::             Schriften verschriftlicht.
@end menu

@node Software-Freiheit
@subsection Software-Freiheit

@c Adapted from http://www.gnu.org/philosophy/philosophy.html.
@cindex freie Software
Das GNU-Betriebssystem wurde entwickelt, um Menschen Freiheit zu
ermöglichen, wie sie ihre Rechengeräte benutzen. GNU ist @dfn{freie
Software}, was bedeutet, dass Benutzer die
@url{https://www.gnu.org/philosophy/free-sw.de.html,vier wesentlichen
Freiheiten} haben: das Programm auszuführen, es zu untersuchen, das Programm
in Form seines Quellcodes anzupassen und exakte Kopien ebenso wie
modifizierte Versionen davon an andere weiterzugeben. Die Pakete, die Sie in
der GNU-Distribution finden, stellen ausschließlich solche Software zur
Verfügung, die Ihnen diese vier Freiheiten gewährt.

Außerdem befolgt die GNU-Distribution die
@url{https://www.gnu.org/distros/free-system-distribution-guidelines.de.html,Richtlinien
für freie Systemverteilungen}. Unter anderem werden unfreie Firmware sowie
Empfehlungen von unfreier Software abgelehnt und Möglichkeiten zum Umgang
mit Markenzeichen und Patenten werden diskutiert.

Ansonsten freier Paketquellcode von manchen Anbietern enthält einen kleinen
und optionalen Teil, der diese Richtlinien verletzt. Zum Beispiel kann
dieser Teil selbst unfreier Code sein. Wenn das vorkommt, wird der sie
verletzende Teil mit angemessenen Patches oder Code-Schnipseln innerhalb der
@code{origin}-Form des Pakets entfernt (siehe @ref{Pakete definieren}). Dadurch liefert Ihnen @code{guix build --source} nur den
„befreiten“ Quellcode und nicht den unmodifizierten Quellcode des Anbieters.


@node Paketbenennung
@subsection Paketbenennung

@cindex Paketname
Tatsächlich sind mit jedem Paket zwei Namen assoziiert: Zum einen gibt es
den Namen der @emph{Scheme-Variablen}, der direkt nach @code{define-public}
im Code steht. Mit diesem Namen kann das Paket im Scheme-Code nutzbar
gemacht und zum Beispiel als Eingabe eines anderen Pakets benannt
werden. Zum anderen gibt es die Zeichenkette im @code{name}-Feld einer
Paketdefinition. Dieser Name wird von Paketverwaltungsbefehlen wie
@command{guix package} und @command{guix build} benutzt.

Meistens sind die beiden identisch und ergeben sich aus einer Umwandlung des
vom Anbieter verwendeten Projektnamens in Kleinbuchstaben, bei der
Unterstriche durch Bindestriche ersetzt werden. Zum Beispiel wird GNUnet
unter dem Paketnamen @code{gnunet} angeboten und SDL_net als @code{sdl-net}.

Es gibt eine nennenswerte Ausnahme zu dieser Regel, nämlich wenn der
Projektname nur ein einzelnes Zeichen ist oder auch wenn es bereits ein
älteres, aktives Projekt mit demselben Namen gibt, egal ob es schon für Guix
verpackt wurde. Lassen Sie Ihren gesunden Menschenverstand einen eindeutigen
und sprechenden Namen auswählen. Zum Beispiel wurde die Shell, die bei ihrem
Anbieter „s“ heißt, @code{s-shell} genannt und @emph{nicht} @code{s}. Sie
sind eingeladen, Ihre Hackerkollegen um Inspiration zu bitten.

An Bibliothekspakete hängen wir vorne kein @code{lib} als Präfix an, solange
es nicht Teil des offiziellen Projektnamens ist. Beachten Sie aber die
Abschnitte @ref{Python-Module} und @ref{Perl-Module}, in denen
Sonderregeln für Module der Programmiersprachen Python und Perl beschrieben
sind.

Auch Pakete mit Schriftarten werden anders behandelt, siehe @ref{Schriftarten}.


@node Versionsnummern
@subsection Versionsnummern

@cindex Paketversion
Normalerweise stellen wir nur für die neueste Version eines
Freie-Software-Projekts ein Paket bereit. Manchmal gibt es allerdings Fälle
wie zum Beispiel untereinander inkompatible Bibliotheksversionen, so dass
zwei (oder mehr) Versionen desselben Pakets angeboten werden müssen. In
diesem Fall müssen wir verschiedene Scheme-Variablennamen benutzen. Wir
benutzen dann für die neueste Version den Namen, wie er im Abschnitt
@ref{Paketbenennung} festgelegt wird, und geben vorherigen Versionen
denselben Namen mit einem zusätzlichen Suffix aus @code{-} gefolgt vom
kürzesten Präfix der Versionsnummer, mit dem noch immer zwei Versionen
unterschieden werden können.

Der Name innerhalb der Paketdefinition ist hingegen derselbe für alle
Versionen eines Pakets und enthält keine Versionsnummer.

Zum Beispiel können für GTK in den Versionen 2.24.20 und 3.9.12 Pakete wie
folgt geschrieben werden:

@lisp
(define-public gtk+
  (package
    (name "gtk+")
    (version "3.9.12")
    …))
(define-public gtk+-2
  (package
    (name "gtk+")
    (version "2.24.20")
    …))
@end lisp
Wenn wir auch GTK 3.8.2 wollten, würden wir das Paket schreiben als
@lisp
(define-public gtk+-3.8
  (package
    (name "gtk+")
    (version "3.8.2")
    …))
@end lisp

@c See <https://lists.gnu.org/archive/html/guix-devel/2016-01/msg00425.html>,
@c for a discussion of what follows.
@cindex Versionsnummer, bei Snapshots aus Versionskontrolle
Gelegentlich fügen wir auch Pakete für Snapshots aus dem
Versionskontrollsystem des Anbieters statt formaler Veröffentlichungen zur
Distribution hinzu. Das sollte die Ausnahme bleiben, weil die Entwickler
selbst klarstellen sollten, welche Version als die stabile Veröffentlichung
gelten sollte, ab und zu ist es jedoch notwendig. Was also sollten wir dann
im @code{version}-Feld eintragen?

Offensichtlich muss der Bezeichner des Commits, den wir als Snapshot aus dem
Versionskontrollsystem nehmen, in der Versionszeichenkette zu erkennen sein,
aber wir müssen auch sicherstellen, dass die Version monoton steigend ist,
damit @command{guix package --upgrade} feststellen kann, welche Version die
neuere ist. Weil Commit-Bezeichner, insbesondere bei Git, nicht monoton
steigen, müssen wir eine Revisionsnummer hinzufügen, die wir jedes Mal
erhöhen, wenn wir das Paket auf einen neueren Snapshot aktualisieren. Die
sich ergebende Versionszeichenkette sieht dann so aus:

@example
2.0.11-3.cabba9e
  ^    ^    ^
  |    |    `-- Commit-ID beim Anbieter
  |    |
  |    `--- Revisionsnummer des Guix-Pakets
  |
die neueste Version, die der Anbieter veröffentlicht hat
@end example

Es ist eine gute Idee, die Commit-Bezeichner im @code{version}-Feld auf,
sagen wir, 7 Ziffern zu beschränken. Das sieht besser aus (angenommen, das
sollte hier eine Rolle spielen) und vermeidet Probleme, die mit der
maximalen Länge von Shebangs zu tun haben (127 Bytes beim Linux-Kernel). Am
besten benutzen Sie jedoch den vollständigen Commit-Bezeichner in
@code{origin}s, um Mehrdeutigkeiten zu vermeiden. Eine typische
Paketdefinition könnte so aussehen:

@lisp
(define mein-paket
  (let ((commit "c3f29bc928d5900971f65965feaae59e1272a3f7")
        (revision "1"))          ;Guix-Paketrevision
    (package
      (version (git-version "0.9" revision commit))
      (source (origin
                (method git-fetch)
                (uri (git-reference
                      (url "git://example.org/mein-paket.git")
                      (commit commit)))
                (sha256 (base32 "1mbikn…"))
                (file-name (git-file-name name version))))
      ;; …
      )))
@end lisp

@node Zusammenfassungen und Beschreibungen
@subsection Zusammenfassungen und Beschreibungen

@cindex Paketbeschreibung
@cindex Paketzusammenfassung
Wie wir bereits gesehen haben, enthält jedes Paket in GNU@tie{}Guix eine (im
Code englischsprachige) Zusammenfassung (englisch: Synopsis) und eine
Beschreibung (englisch: Description; siehe @ref{Pakete definieren}). Zusammenfassungen und Beschreibungen sind wichtig: Sie werden
mit @command{guix package --search} durchsucht und stellen eine
entscheidende Informationsquelle für Nutzer dar, die entscheiden wollen, ob
das Paket Ihren Bedürfnissen entspricht, daher sollten Paketentwickler Acht
geben, was sie dort eintragen.

Zusammenfassungen müssen mit einem Großbuchstaben beginnen und dürfen nicht
mit einem Punkt enden. Sie dürfen nicht mit den Artikeln „a“ oder „the“
beginnen, die meistens ohnehin nichts zum Verständnis beitragen. Zum
Beispiel sollte „File-frobbing tool“ gegenüber „A tool that frobs files“
vorgezogen werden. Die Zusammenfassung sollte aussagen, um was es sich beim
Paket handelt — z.B.@: „Core GNU utilities (file, text, shell)“ —, oder
aussagen, wofür es benutzt wird — z.B.@: ist die Zusammenfassung für
GNU@tie{}grep „Print lines matching a pattern“.

Beachten Sie, dass die Zusammenfassung für eine sehr große Leserschaft einen
Sinn ergeben muss. Zum Beispiel würde „Manipulate alignments in the SAM
format“ vielleicht von einem erfahrenen Forscher in der Bioinformatik
verstanden, könnte für die Nicht-Spezialisten in Guix’ Zielgruppe aber wenig
hilfreich sein oder würde diesen sogar eine falsche Vorstellung geben. Es
ist eine gute Idee, sich eine Zusammenfassung zu überlegen, die eine
Vorstellung von der Anwendungsdomäne des Pakets vermittelt. Im Beispiel hier
würden sich die Nutzer mit „Manipulate nucleotide sequence alignments“
hoffentlich ein besseres Bild davon machen können, ob das Paket ist, wonach
sie suchen.

Beschreibungen sollten zwischen fünf und zehn Zeilen lang sein. Benutzen Sie
vollständige Sätze und vermeiden Sie Abkürzungen, die Sie nicht zuvor
eingeführt haben. Vermeiden Sie bitte Marketing-Phrasen wie „world-leading“
(„weltweit führend“), „industrial-strength“ („industrietauglich“) und
„next-generation“ („der nächsten Generation“) ebenso wie Superlative wie
„the most advanced“ („das fortgeschrittenste“) — davon haben Nutzer nichts,
wenn sie ein Paket suchen, und es könnte sogar verdächtig klingen. Versuchen
Sie stattdessen, bei den Fakten zu bleiben und dabei Anwendungszwecke und
Funktionalitäten zu erwähnen.

@cindex Texinfo-Auszeichnungen, in Paketbeschreibungen
Beschreibungen können wie bei Texinfo ausgezeichneten Text enthalten. Das
bedeutet, Text kann Verzierungen wie @code{@@code} oder @code{@@dfn},
Auflistungen oder Hyperlinks enthalten (siehe @ref{Overview,,, texinfo, GNU
Texinfo}). Sie sollten allerdings vorsichtig sein, wenn Sie bestimmte
Zeichen wie @samp{@@} und geschweifte Klammern schreiben, weil es sich dabei
um die grundlegenden Sonderzeichen in Texinfo handelt (siehe @ref{Special
Characters,,, texinfo, GNU Texinfo}). Benutzungsschnittstellen wie
@command{guix package --show} kümmern sich darum, solche Auszeichnungen
angemessen darzustellen.

Zusammenfassungen und Beschreibungen werden von Freiwilligen
@uref{https://translate.fedoraproject.org/projects/guix/packages, bei
Weblate} übersetzt, damit so viele Nutzer wie möglich sie in ihrer
Muttersprache lesen können. Mit Schnittstellen für Benutzer können sie in
der von der aktuell eingestellten Locale festgelegten Sprache durchsucht und
angezeigt werden.

Damit @command{xgettext} sie als übersetzbare Zeichenketten extrahieren
kann, @emph{müssen} Zusammenfassungen und Beschreibungen einfache
Zeichenketten-Literale sein. Das bedeutet, dass Sie diese Zeichenketten
nicht mit Prozeduren wie @code{string-append} oder @code{format}
konstruieren können:

@lisp
(package
  ;; …
  (synopsis "This is translatable")
  (description (string-append "This is " "*not*" " translatable.")))
@end lisp

Übersetzen ist viel Arbeit, also passen Sie als Paketentwickler bitte umso
mehr auf, wenn Sie Ihre Zusammenfassungen und Beschreibungen formulieren,
weil jede Änderung zusätzliche Arbeit für Übersetzer bedeutet. Um den
Übersetzern zu helfen, können Sie Empfehlungen und Anweisungen für diese
sichtbar machen, indem Sie spezielle Kommentare wie in diesem Beispiel
einfügen (siehe @ref{xgettext Invocation,,, gettext, GNU Gettext}):

@lisp
;; TRANSLATORS: "X11 resize-and-rotate" should not be translated.
(description "ARandR is designed to provide a simple visual front end
for the X11 resize-and-rotate (RandR) extension. …")
@end lisp

@node „Snippets“ oder Phasen
@subsection „Snippets“ oder Phasen

@cindex snippet-Feld, wann man es benutzt
Die Grenze, wann man Code-Schnipsel im @code{origin}-„@code{snippet}“-Feld
gegenüber einer Erstellungsphase für Änderungen an den Quelldateien eines
Pakets bevorzugen sollte, ist fließend. Schnipsel im Paketursprung werden
meistens dazu benutzt, unerwünschte Dateien wie z.B.@: gebündelte
Bibliotheken oder unfreie Quelldateien zu entfernen, oder um einfache
Textersetzungen durchzuführen. Die Quelle, die sich aus einem Paketursprung
ableitet, sollte Quellcode erzeugen, um das Paket auf jedem vom Anbieter
unterstützten System zu erstellen (d.h.@: um als dessen „corresponding
source“, „korrespondierender Quelltext“, herzuhalten). Insbesondere dürfen
Snippets im Paketursprung keine Store-Objekte in den Quelldateien einbetten;
solche Anpassungen sollten besser in Erstellungsphasen stattfinden. Schauen
Sie in die Dokumentation des @code{origin}-Verbundsobjekts für weitere
Informationen (siehe @ref{„origin“-Referenz}).

@node Emacs-Pakete
@subsection Emacs-Pakete

@cindex emacs, Pakete dafür schreiben
@cindex elisp, Pakete dafür schreiben
Für Emacs-Pakete sollte man bevorzugt das Emacs-Erstellungssystem benutzen
(siehe @ref{emacs-build-system}), wegen der Einheitlichkeit und der Vorteile
durch seine Erstellungsphasen. Dazu gehören das automatische Erzeugen der
Autoloads-Datei und das Kompilieren des Quellcodes zu Bytecode (Byte
Compilation). Weil es keinen Standard gibt, wie ein Testkatalog eines
Emacs-Pakets ausgeführt wird, sind Tests nach Vorgabe abgeschaltet. Wenn es
einen Testkatalog gibt, sollte er aktiviert werden, indem Sie das Argument
@code{#:tests?} auf @code{#true} setzen. Vorgegeben ist, die Tests mit dem
Befehl @command{make check} auszuführen, aber mit dem Argument
@code{#:test-command} kann ein beliebiger anderer Befehl festgelegt
werden. Für das Argument @code{#:test-command} wird eine Liste aus dem
Befehl und den Argumenten an den Befehl erwartet. Er wird während der
@code{check}-Phase aufgerufen.

Die Elisp-Abhängigkeiten von Emacs-Paketen werden typischerweise als
@code{propagated-inputs} bereitgestellt, wenn sie zur Laufzeit benötigt
werden. Wie bei anderen Paketen sollten Abhängigkeiten zum Erstellen oder
Testen als @code{native-inputs} angegeben werden.

Manchmal hängen Emacs-Pakete von Ressourcenverzeichnissen ab, die zusammen
mit den Elisp-Dateien installiert werden sollten. Diese lassen sich mit dem
Argument @code{#:include} kennzeichnen, indem eine Liste dazu passender
regulärer Ausdrücke angegeben wird. Idealerweise ergänzen Sie den
Vorgabewert des @code{#:include}-Arguments (aus der Variablen
@code{%default-include}), statt ihn zu ersetzen. Zum Beispiel enthält ein
yasnippet-Erweiterungspaket typischerweise ein @file{snippets}-Verzeichnis,
das wie folgt in das Installationsverzeichnis kopiert werden könnte:

@lisp
#:include (cons "^snippets/" %default-include))
@end lisp

Wenn Sie auf Probleme stoßen, ist es ratsam, auf eine Kopfzeile
@code{Package-Requires} in der Hauptquellcodedatei des Pakets zu achten, ob
allen Abhängigkeiten und deren dort gelisteten Versionen genügt wird.

@node Python-Module
@subsection Python-Module

@cindex python
Zurzeit stellen wir ein Paket für Python 2 und eines für Python 3 jeweils
über die Scheme-Variablen mit den Namen @code{python-2} und @code{python}
zur Verfügung, entsprechend der Erklärungen im Abschnitt @ref{Versionsnummern}. Um Verwirrungen und Namenskollisionen mit anderen
Programmiersprachen zu vermeiden, erscheint es als wünschenswert, dass der
Name eines Pakets für ein Python-Modul auch das Wort @code{python} enthält.

Manche Module sind nur mit einer Version von Python kompatibel, andere mit
beiden. Wenn das Paket Foo mit Python 3 kompiliert wird, geben wir ihm den
Namen @code{python-foo}. Wenn es mit Python 2 kompiliert wird, wählen wir
den Namen @code{python2-foo}. Pakete sollten dann hinzugefügt werden, wenn
sie gebraucht werden. Wir erstellen keine Python-2-Varianten von Paketen,
wenn wir sie nicht benutzen wollen.

Wenn ein Projekt bereits das Wort @code{python} im Namen hat, lassen wir es
weg; zum Beispiel ist das Modul python-dateutil unter den Namen
@code{python-dateutil} und @code{python2-dateutil} verfügbar. Wenn der
Projektname mit @code{py} beginnt (z.B.@: @code{pytz}), behalten wir ihn bei
und stellen das oben beschriebene Präfix voran.

@subsubsection Abhängigkeiten angeben
@cindex Eingaben, für Python-Pakete

Informationen über Abhängigkeiten von Python-Paketen, welche mal mehr und
mal weniger stimmen, finden sich normalerweise im Verzeichnisbaum des
Paketquellcodes: in der Datei @file{setup.py}, in @file{requirements.txt}
oder in @file{tox.ini}.

Wenn Sie ein Rezept für ein Python-Paket schreiben, lautet Ihr Auftrag,
diese Abhängigkeiten auf angemessene Arten von „Eingaben“ abzubilden (siehe
@ref{„package“-Referenz, Eingaben}). Obwohl der @code{pypi}-Importer hier
normalerweise eine gute Arbeit leistet (siehe @ref{Aufruf von guix import}),
könnten Sie die folgende Prüfliste durchgehen wollen, um zu bestimmen, wo
welche Abhängigkeit eingeordnet werden sollte.

@itemize

@item
Derzeit ist unser Python-2-Paket so geschrieben, dass es @code{setuptools}
und @code{pip} installiert, wie es auch in den Vorgaben zu Python 3.4
gemacht wird. Sie müssen also keines der beiden als Eingabe angeben. Wenn
Sie es doch tun, wird @command{guix lint} Sie darauf mit einer Warnung
aufmerksam machen.

@item
Python-Abhängigkeiten, die zur Laufzeit gebraucht werden, stehen im
@code{propagated-inputs}-Feld. Solche werden typischerweise mit dem
Schlüsselwort @code{install_requires} in @file{setup.py} oder in der Datei
@file{requirements.txt} definiert.

@item
Python-Pakete, die nur zur Erstellungszeit gebraucht werden — z.B.@: jene,
die mit dem Schlüsselwort @code{setup_requires} in @file{setup.py}
aufgeführt sind — oder die nur zum Testen gebraucht werden — also die in
@code{tests_require} —, stehen in @code{native-inputs}. Die Begründung ist,
dass (1) sie nicht propagiert werden müssen, weil sie zur Laufzeit nicht
gebraucht werden, und (2) wir beim Cross-Kompilieren die „native“ Eingabe
des Wirtssystems wollen.

Beispiele sind die Testrahmen @code{pytest}, @code{mock} und
@code{nose}. Wenn natürlich irgendeines dieser Pakete auch zur Laufzeit
benötigt wird, muss es doch in @code{propagated-inputs} stehen.

@item
Alles, was nicht in die bisher genannten Kategorien fällt, steht in
@code{inputs}, zum Beispiel Programme oder C-Bibliotheken, die zur
Erstellung von Python-Paketen mit enthaltenen C-Erweiterungen gebraucht
werden.

@item
Wenn ein Python-Paket optionale Abhängigkeiten hat (@code{extras_require}),
ist es Ihnen überlassen, sie hinzuzufügen oder nicht hinzuzufügen, je
nachdem wie es um deren Verhältnis von Nützlichkeit zu anderen Nachteilen
steht (siehe @ref{Einreichen von Patches, @command{guix size}}).

@end itemize


@node Perl-Module
@subsection Perl-Module

@cindex perl
Eigenständige Perl-Programme bekommen einen Namen wie jedes andere Paket,
unter Nutzung des Namens beim Anbieter in Kleinbuchstaben. Für Perl-Pakete,
die eine einzelne Klasse enthalten, ersetzen wir alle Vorkommen von
@code{::} durch Striche und hängen davor das Präfix @code{perl-} an. Die
Klasse @code{XML::Parser} wird also zu @code{perl-xml-parser}. Module, die
mehrere Klassen beinhalten, behalten ihren Namen beim Anbieter, in
Kleinbuchstaben gesetzt, und auch an sie wird vorne das Präfix @code{perl-}
angehängt. Es gibt die Tendenz, solche Module mit dem Wort @code{perl}
irgendwo im Namen zu versehen, das wird zu Gunsten des Präfixes
weggelassen. Zum Beispiel wird aus @code{libwww-perl} bei uns
@code{perl-libwww}.


@node Java-Pakete
@subsection Java-Pakete

@cindex java
Eigenständige Java-Programme werden wie jedes andere Paket benannt, d.h.@:
mit ihrem in Kleinbuchstaben geschriebenen Namen beim Anbieter.

Um Verwirrungen und Namenskollisionen mit anderen Programmiersprachen zu
vermeiden, ist es wünschenswert, dass dem Namem eines Pakets zu einem
Java-Paket das Präfix @code{java-} vorangestellt wird. Wenn ein Projekt
bereits das Wort @code{java} im Namen trägt, lassen wir es weg; zum Beispiel
befindet sich das Java-Paket @code{ngsjava} in einem Paket namens
@code{java-ngs}.

Bei Java-Paketen, die eine einzelne Klasse oder eine kleine
Klassenhierarchie enthalten, benutzen wir den Klassennamen in
Kleinbuchstaben und ersetzen dabei alle Vorkommen von @code{.} durch Striche
und setzen das Präfix @code{java-} davor. Die Klasse
@code{apache.commons.cli} wird also zum Paket
@code{java-apache-commons-cli}.


@node Rust-Crates
@subsection Rust-Crates

@cindex rust
Eigenständige Rust-Programme werden wie jedes andere Paket benannt, d.h.@:
mit ihrem in Kleinbuchstaben geschriebenen Namen beim Anbieter.

Um Namensraumkollisionen vorzubeugen, versehen wir alle anderen Rust-Pakete
mit dem Präfix @code{rust-}. Der Name sollte wie sonst in Kleinbuchstaben
geschrieben werden und Bindestriche dort bleiben, wo sie sind.

Im Rust-Ökosystem werden oft mehrere inkompatible Versionen desselben Pakets
gleichzeitig benutzt, daher sollte allen Paketdefinitionen ein die Version
angebendes Suffix gegeben werden. Das Versionssuffix besteht aus der am
weitesten links stehenden Ziffer, die @emph{nicht} null ist (natürlich mit
allen führenden Nullen). Dabei folgen wir dem von Cargo gewollten
„Caret“-Versionsschema. Beispiele: @code{rust-clap-2}, @code{rust-rand-0.6}.

Weil die Verwendung von Rust-Paketen als vorab kompilierte Eingaben für
andere Pakete besondere Schwierigkeiten macht, gibt es im
Cargo-Erstellungssystem (siehe @ref{Erstellungssysteme,
@code{cargo-build-system}}) die Schlüsselwörter @code{#:cargo-inputs} und
@code{#:cargo-development-inputs} als Argumente an das Erstellungssystem. Es
ist hilfreich, sie sich ähnlich wie @code{propagated-inputs} und
@code{native-inputs} vorzustellen. Was in Rust @code{dependencies} und
@code{build-dependencies} sind, sollte unter @code{#:cargo-inputs}
aufgeführt werden, während @code{dev-dependencies} zu den
@code{#:cargo-development-inputs} gehören. Wenn ein Rust-Paket andere
Bibliotheken einbindet, gilt die normale Einordnung in @code{inputs} usw.@:
wie anderswo auch.

Man sollte aufpassen, dass man die richtige Version von Abhängigkeiten
benutzt. Deswegen versuchen wir, Tests nicht mit @code{#:skip-build?} zu
überspringen, wenn es möglich ist. Natürlich geht das nicht immer,
vielleicht weil das Paket für ein anderes Betriebssystem entwickelt wurde,
Funktionalitäten der allerneuesten „Nightly“-Version des Rust-Compilers
voraussetzt oder weil der Testkatalog seit seiner Veröffentlichung
verkümmert ist.


@node Schriftarten
@subsection Schriftarten

@cindex Schriftarten
Wenn Schriftarten in der Regel nicht von Nutzern zur Textbearbeitung
installiert werden oder als Teil eines größeren Software-Pakets mitgeliefert
werden, gelten dafür die allgemeinen Paketrichtlinien für Software. Zum
Beispiel trifft das auf als Teil des X.Org-Systems ausgelieferte
Schriftarten zu, oder auf Schriftarten, die ein Teil von TeX Live sind.

Damit es Nutzer leichter haben, nach Schriftarten zu suchen, konstruieren
wir die Namen von anderen Paketen, die nur Schriftarten enthalten, nach dem
folgenden Schema, egal was der Paketname beim Anbieter ist.

Der Name eines Pakets, das nur eine Schriftfamilie enthält, beginnt mit
@code{font-}. Darauf folgt der Name des Schriftenherstellers und ein Strich
@code{-}, sofern bekannt ist, wer der Schriftenhersteller ist, und dann der
Name der Schriftfamilie, in dem Leerzeichen durch Striche ersetzt werden
(und wie immer mit Großbuchstaben statt Kleinbuchstaben). Zum Beispiel
befindet sich die von SIL hergestellte Gentium-Schriftfamilie im Paket mit
dem Namen @code{font-sil-gentium}.

Wenn ein Paket mehrere Schriftfamilien enthält, wird der Name der Sammlung
anstelle des Schriftfamiliennamens benutzt. Zum Beispiel umfassen die
Liberation-Schriftarten drei Familien: Liberation Sans, Liberation Serif und
Liberation Mono. Man könnte sie getrennt voneinander mit den Namen
@code{font-liberation-sans} und so weiter in Pakete einteilen. Da sie aber
unter einem gemeinsamen Namen angeboten werden, packen wir sie lieber
zusammen in ein Paket mit dem Namen @code{font-liberation}.

Für den Fall, dass mehrere Formate derselben Schriftfamilie oder
Schriftartensammlung in separate Pakete kommen, wird ein Kurzname für das
Format mit einem Strich vorne zum Paketnamen hinzugefügt. Wir benutzen
@code{-ttf} für TrueType-Schriftarten, @code{-otf} für OpenType-Schriftarten
und @code{-type1} für PostScript-Typ-1-Schriftarten.


@node Programmierstil
@section Programmierstil

Im Allgemeinen folgt unser Code den GNU Coding Standards (siehe @ref{Top,,,
standards, GNU Coding Standards}). Da diese aber nicht viel über Scheme zu
sagen haben, folgen hier einige zusätzliche Regeln.

@menu
* Programmierparadigmen::    Wie Sie Ihre Elemente zusammenstellen.
* Module::                   Wo Sie Ihren Code unterbringen.
* Datentypen und Mustervergleich::  Implementierung von Datenstrukturen.
* Formatierung von Code::    Schreibkonventionen.
@end menu

@node Programmierparadigmen
@subsection Programmierparadigmen

Scheme-Code wird in Guix auf rein funktionale Weise geschrieben. Eine
Ausnahme ist Code, der mit Ein- und Ausgabe zu tun hat, und Prozeduren, die
grundlegende Konzepte implementieren, wie zum Beispiel die Prozedur
@code{memoize}.

@node Module
@subsection Module

Guile-Module, die beim Erstellen nutzbar sein sollen, müssen im Namensraum
@code{(guix build …)} leben. Sie dürfen auf keine anderen Guix- oder
GNU-Module Bezug nehmen. Jedoch ist es in Ordnung, wenn ein „wirtsseitiges“
Modul ein erstellungsseitiges Modul benutzt.

Module, die mit dem weiteren GNU-System zu tun haben, sollten im Namensraum
@code{(gnu …)} und nicht in @code{(guix …)} stehen.

@node Datentypen und Mustervergleich
@subsection Datentypen und Mustervergleich

Im klassischen Lisp gibt es die Tendenz, Listen zur Darstellung von allem zu
benutzen, und diese dann „händisch“ zu durchlaufen mit @code{car},
@code{cdr}, @code{cadr} und so weiter. Dieser Stil ist aus verschiedenen
Gründen problematisch, insbesondere wegen der Tatsache, dass er schwer zu
lesen, schnell fehlerbehaftet und ein Hindernis beim Melden von Typfehlern
ist.

Guix-Code sollte angemessene Datentypen definieren (zum Beispiel mit
@code{define-record-type*}) statt Listen zu missbrauchen. Außerdem sollte er
das @code{(ice-9 match)}-Modul von Guile zum Mustervergleich benutzen,
besonders mit Listen (siehe @ref{Pattern Matching,,, guile, Referenzhandbuch
zu GNU Guile}).

@node Formatierung von Code
@subsection Formatierung von Code

@cindex Formatierung von Code
@cindex Code-Stil
Beim Schreiben von Scheme-Code halten wir uns an die üblichen
Gepflogenheiten unter Scheme-Programmierern. Im Allgemeinen bedeutet das,
dass wir uns an @url{https://mumble.net/~campbell/scheme/style.txt,
Riastradh's Lisp Style Rules} halten. Es hat sich ergeben, dass dieses
Dokument auch die Konventionen beschreibt, die im Code von Guile
hauptsächlich verwendet werden. Es ist gut durchdacht und schön geschrieben,
also lesen Sie es bitte.

Ein paar in Guix eingeführte Sonderformen, wie zum Beispiel das
@code{substitute*}-Makro, haben abweichende Regeln für die Einrückung. Diese
sind in der Datei @file{.dir-locals.el} definiert, die Emacs automatisch
benutzt. Beachten Sie auch, dass Emacs-Guix einen Modus namens
@code{guix-devel-mode} bereitstellt, der Guix-Code richtig einrückt und
hervorhebt (siehe @ref{Entwicklung,,, emacs-guix, Referenzhandbuch von
Emacs-Guix}).

@cindex Einrückung, Code-
@cindex Formatierung, Code-
Falls Sie nicht Emacs verwenden, sollten Sie sicherstellen, dass Ihr Editor
diese Regeln kennt. Um eine Paketdefinition automatisch einzurücken, können
Sie auch Folgendes ausführen:

@example
./etc/indent-code.el gnu/packages/@var{Datei}.scm @var{Paket}
@end example

@noindent
Dadurch wird die Definition von @var{Paket} in
@file{gnu/packages/@var{Datei}.scm} automatisch eingerückt, indem Emacs im
Batch-Modus läuft. Um die Einrückung in einer gesamten Datei vorzunehmen,
lassen Sie das zweite Argument weg:

@example
./etc/indent-code.el gnu/services/@var{Datei}.scm
@end example

@cindex Vim, zum Editieren von Scheme-Code
Wenn Sie Code mit Vim bearbeiten, empfehlen wir, dass Sie @code{:set
autoindent} ausführen, damit Ihr Code automatisch eingerückt wird, während
Sie ihn schreiben. Außerdem könnte Ihnen
@uref{https://www.vim.org/scripts/script.php?script_id=3998,
@code{paredit.vim}} dabei helfen, mit all diesen Klammern fertigzuwerden.

Wir fordern von allen Prozeduren auf oberster Ebene, dass sie über einen
Docstring verfügen. Diese Voraussetzung kann jedoch bei einfachen, privaten
Prozeduren im Namensraum @code{(guix build …)} aufgeweicht werden.

Prozeduren sollten nicht mehr als vier positionsbestimmte Parameter
haben. Benutzen Sie Schlüsselwort-Parameter für Prozeduren, die mehr als
vier Parameter entgegennehmen.


@node Einreichen von Patches
@section 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 @code{git format-patch} erstellt und an die Mailingliste
@email{guix-patches@@gnu.org} geschickt werden. Erfahrene Guix-Entwickler
möchten vielleicht auch einen Blick auf den Abschnitt über Commit-Zugriff
werfen (siehe @ref{Commit-Zugriff}).

Diese Mailing-Liste setzt auf einer Debbugs-Instanz auf, wodurch wir den
Überblick über Eingereichtes behalten können (siehe @ref{Ü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
@code{@var{NNN}@@debbugs.gnu.org} senden kann, wobei @var{NNN} für die
Folgenummer steht (siehe @ref{Senden einer Patch-Reihe}).

Bitte schreiben Sie Commit-Logs im ChangeLog-Format (siehe @ref{Change
Logs,,, standards, GNU Coding Standards}); dazu finden Sie Beispiele unter
den bisherigen Commits.

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

@enumerate
@item
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 @code{gpg
--verify} tun.

@item
Nehmen Sie sich die Zeit, eine passende Zusammenfassung und Beschreibung für
das Paket zu verfassen. Unter @ref{Zusammenfassungen und Beschreibungen} finden Sie
dazu einige Richtlinien.

@item
Verwenden Sie @code{guix lint @var{Paket}}, wobei @var{Paket} das neue oder
geänderte Paket bezeichnet, und beheben Sie alle gemeldeten Fehler (siehe
@ref{Aufruf von guix lint}).

@item
Stellen Sie sicher, dass das Paket auf Ihrer Plattform erstellt werden kann,
indem Sie @code{guix build @var{Paket}} ausführen.

@item
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
@code{qemu-binfmt-service-type} zu benutzen, um sie zu emulieren. Um ihn zu
aktivieren, fügen Sie den folgenden Dienst in die Liste der Dienste
(„services“) in Ihrer @code{operating-system}-Konfiguration ein:

@lisp
(service qemu-binfmt-service-type
 (qemu-binfmt-configuration
   (platforms (lookup-qemu-platforms "arm" "aarch64"))
@end lisp

Rekonfigurieren Sie anschließend Ihr System.

Sie können Pakete für andere Plattformen erstellen lassen, indem Sie die
Befehlszeilenoption @code{--system} angeben. Um zum Beispiel das Paket
„hello“ für die Architekturen armhf, aarch64 oder mips64 erstellen zu
lassen, würden Sie jeweils die folgenden Befehle angeben:
@example
guix build --system=armhf-linux --rounds=2 hello
guix build --system=aarch64-linux --rounds=2 hello
@end example

@item
@cindex gebündelt
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.

@item
Schauen Sie sich das von @command{guix size} ausgegebene Profil an (siehe
@ref{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 @ref{Pakete mit mehreren Ausgaben.}) und welche optionalen Abhängigkeiten verwendet
werden sollten. Dabei sollten Sie es wegen seiner enormen Größe insbesondere
vermeiden, @code{texlive} als eine Abhängigkeit hinzuzufügen; benutzen Sie
stattdessen das Paket @code{texlive-tiny} oder die Prozedur
@code{texlive-union}.

@item
Achten Sie bei wichtigen Änderungen darauf, dass abhängige Pakete (falls
vorhanden) nicht von der Änderung beeinträchtigt werden; @code{guix refresh
--list-dependent @var{Paket}} hilft Ihnen dabei (siehe @ref{Aufruf von guix refresh}).

@c See <https://lists.gnu.org/archive/html/guix-devel/2016-10/msg00933.html>.
@cindex Branching-Strategie
@cindex Neuerstellungs-Zeitplan
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:

@table @asis
@item 300 abhängige Pakete oder weniger
@code{master}-Branch (störfreie Änderungen).

@item zwischen 300 und 1.800 abhängige Pakete
@code{staging}-Branch (störfreie Änderungen). Dieser Branch wird circa alle
6@tie{}Wochen mit @code{master} zusammengeführt. Themenbezogene Änderungen
(z.B.@: eine Aktualisierung der GNOME-Plattform) können stattdessen auch auf
einem eigenen Branch umgesetzt werden (wie @code{gnome-updates}).

@item mehr als 1.800 abhängige Pakete
@code{core-updates}-Branch (kann auch größere und womöglich andere Software
beeinträchtigende Änderungen umfassen). Dieser Branch wird planmäßig in
@code{master} alle 6 Monate oder so gemerget.
@end table

All diese Branches werden kontinuierlich @uref{@value{SUBSTITUTE-URL}, auf
unserer Erstellungsfarm} erstellt und in @code{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.

@c TODO: It would be good with badges on the website that tracks these
@c branches.  Or maybe even a status page.
Sobald wir uns dazu entscheiden, einen der Branches @code{staging} oder
@code{core-updates} zu erstellen, spalten wir einen neuen Branch davon ab
und hängen an seinen Namen das Suffix @code{-frozen} an. Auf einen
„frozen“-Branch dürfen dann nur noch Fehlerbehebungen gepusht werden. Die
Branches @code{core-updates} und @code{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.

@item
@cindex Determinismus, von Erstellungsprozessen
@cindex Reproduzierbare Erstellungen, Überprüfung
Ü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 @ref{Aufruf von guix build}):

@example
guix build --rounds=2 mein-paket
@end example

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, @command{guix challenge} (siehe @ref{Aufruf von guix challenge}) zu benutzen. Sie können es ausführen, sobald ein Paket
commitet und von @code{@value{SUBSTITUTE-SERVER}} 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 @command{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 @code{uname} oder
@file{/proc}-Dateien verwendet werden.

@item
Beim Schreiben von Dokumentation achten Sie bitte auf eine
geschlechtsneutrale Wortwahl, wenn Sie sich auf Personen beziehen, wie
@uref{https://en.wikipedia.org/wiki/Singular_they, „they“@comma{}
„their“@comma{} „them“ im Singular} und so weiter.

@item
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.

@item
Bitte befolgen Sie unsere Richtlinien für die Code-Formatierung, womöglich
wollen Sie dies automatisch tun lassen durch das Skript
@command{etc/indent-code.el} (siehe @ref{Formatierung von Code}).

@item
Benutzen Sie, wenn möglich, Spiegelserver (Mirrors) in der Quell-URL (siehe
@ref{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
@emph{nicht} das @command{name}-Feld beim Angeben der URL; er hilft nicht
wirklich und wenn sich der Name ändert, stimmt die URL nicht mehr.

@item
Überprüfen Sie, ob Guix erstellt werden kann (siehe @ref{Erstellung aus dem Git})
und kümmern Sie sich um die Warnungen, besonders um solche über nicht
definierte Symbole.

@item
Stellen Sie sicher, dass Ihre Änderungen Guix nicht beeinträchtigen, und
simulieren Sie eine Ausführung von @code{guix pull} über den Befehl:
@example
guix pull --url=/pfad/zu/ihrem/checkout --profile=/tmp/guix.master
@end example

@end enumerate

Bitte benutzen Sie @samp{[PATCH] …} als Betreff, wenn Sie einen Patch an die
Mailing-Liste schicken. Soll Ihr Patch auf einen anderen Branch als
@code{master} angewandt werden, z.B.@: @code{core-updates}, geben Sie dies
im Betreff an als @samp{[PATCH core-updates] …}. Sie können dazu Ihr
E-Mail-Programm oder den Befehl @command{git send-email} benutzen (siehe
@ref{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.

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

@unnumberedsubsec Senden einer Patch-Reihe
@anchor{Senden einer Patch-Reihe}
@cindex Patch-Reihe
@cindex @code{git send-email}
@cindex @code{git-send-email}

@c Debbugs bug: https://debbugs.gnu.org/db/15/15361.html
Wenn Sie eine Patch-Reihe senden (z.B.@: mit @code{git send-email}),
schicken Sie bitte als Erstes eine Nachricht an
@email{guix-patches@@gnu.org} und dann nachfolgende Patches an
@email{@var{NNN}@@debbugs.gnu.org}, um sicherzustellen, dass sie zusammen
bearbeitet werden. Siehe @uref{https://debbugs.gnu.org/Advanced.html, die
Debbugs-Dokumentation} für weitere Informationen. Sie können @command{git
send-email} mit dem Befehl @command{guix install git:send-email}
installieren.

@node Überblick über gemeldete Fehler und Patches
@section Überblick über gemeldete Fehler und Patches

@cindex Bug-Meldungen, Überblick
@cindex Patch-Einreichungen, Überblick
@cindex gemeldete Fehler überblicken
@cindex Debbugs, System zum Überblicken gemeldeter Fehler
Einen Überblick über gemeldete Fehler („Bugs“) und eingereichte Patches
finden Sie derzeit auf der Debbugs-Instanz unter
@uref{https://bugs.gnu.org}. Fehler werden für das „Paket“ (so sagt man im
Sprachgebrauch von Debbugs) namens @code{guix} gemeldet, indem Sie eine
E-Mail an @email{bug-guix@@gnu.org} schicken. Dagegen werden Patches für das
Paket @code{guix-patches} eingereicht, indem Sie eine E-Mail an
@email{guix-patches@@gnu.org} schicken (siehe @ref{Einreichen von Patches}).

Ihnen steht eine Weboberfläche (tatsächlich sogar @emph{zwei}
Weboberflächen!) zur Verfügung, um die Fehlerdatenbank zu durchsuchen:

@itemize
@item
@url{https://issues.guix.gnu.org} erlaubt es Ihnen, über eine hübsche
Schnittstelle @footnote{Die Weboberfläche unter
@url{https://issues.guix.gnu.org} läuft über das Programm Mumi, ein schönes
Stück in Guile geschriebene Software, bei der Sie uns helfen können! Siehe
@url{https://git.elephly.net/gitweb.cgi?p=software/mumi.git}.} eingesendete
Fehlerberichte („Bug Reports“) und Patches einzusehen und an Diskussionen
teilzunehmen.
@item
Auf @url{https://bugs.gnu.org/guix} werden gemeldete Fehler aufgeführt,
@item
auf @url{https://bugs.gnu.org/guix-patches} eingereichte Patches.
@end itemize

Um Diskussionen zum Fehler mit Fehlernummer @var{n} einzusehen, schauen Sie
auf @indicateurl{https://issues.guix.gnu.org/@var{n}} oder
@indicateurl{https://bugs.gnu.org/@var{n}}.

Wenn Sie Emacs benutzen, finden Sie es vielleicht bequemer, sich durch
Nutzung von @file{debbugs.el} mit Fehlern zu befassen, was Sie mit folgendem
Befehl installieren können:

@example
guix install emacs-debbugs
@end example

Um zum Beispiel alle noch ausstehenden, „offenen“ Fehler bezüglich
@code{guix-patches} anzusehen, geben Sie dies ein:

@example
@kbd{C-u} @kbd{M-x} debbugs-gnu @kbd{RET} @kbd{RET} guix-patches @kbd{RET} n y
@end example

Siehe @ref{Top,,, debbugs-ug, Debbugs User Guide} für weitere Informationen
zu diesem raffinierten Werkzeug.

@node Commit-Zugriff
@section Commit-Zugriff

@cindex Commit-Zugriff, für Entwickler
Für Leute, die häufig zu Guix beitragen, ist es praktischer, Schreibzugriff
auf das Repository zu haben. Wenn Sie es für angemessen halten, dann sollten
Sie in Erwägung ziehen, sich wie folgt um Commit-Zugriff zu bewerben:

@enumerate
@item
Finden Sie drei Commiter, die für Sie eintreten. Sie können die Liste der
Commiter unter
@url{https://savannah.gnu.org/project/memberlist.php?group=guix}
finden. Jeder von ihnen sollte eine entsprechende Erklärung per E-Mail an
@email{guix-maintainers@@gnu.org} schicken (eine private Alias-Adresse für
das Kollektiv aus allen Betreuern bzw.@: Maintainern), die jeweils mit ihrem
OpenPGP-Schlüssel signiert wurde.

Von den Commitern wird erwartet, dass sie bereits mit Ihnen als Mitwirkendem
zu tun hatten und beurteilen können, ob Sie mit den Richtlinien des Projekts
hinreichend vertraut sind. Dabei geht es @emph{nicht} darum, wie wertvoll
Ihre Beiträge sind, daher sollte eine Ablehnung mehr als „schauen wir später
nochmal“ verstanden werden.

@item
Senden Sie eine Nachricht an @email{guix-maintainers@@gnu.org}, in der Sie
Ihre Bereitschaft darlegen und die Namen der drei Commiter nennen, die Ihre
Bewerbung unterstützen. Die Nachricht sollte mit dem OpenPGP-Schlüssel
signiert sein, mit dem Sie später auch Ihre Commits signieren, und Sie
sollten den Fingerabdruck hinterlegen (siehe unten). Siehe
@uref{https://emailselfdefense.fsf.org/de/} für eine Einführung in
asymmetrische Kryptografie („Public-Key“) mit GnuPG.

@c See <https://sha-mbles.github.io/>.
Richten Sie GnuPG so ein, dass es niemals den SHA1-Hashalgorithmus für
digitale Signaturen verwendet, der seit 2019 bekanntlich unsicher ist. Fügen
Sie dazu zum Beispiel folgende Zeile in @file{~/.gnupg/gpg.conf} ein (siehe
@ref{GPG Esoteric Options,,, gnupg, The GNU Privacy Guard Manual}):

@example
digest-algo sha512
@end example

@item
Betreuer entscheiden letztendlich darüber, ob Ihnen Commit-Zugriff gegeben
wird, folgen dabei aber normalerweise der Empfehlung Ihrer Fürsprecher.

@item
@cindex OpenPGP, signierte Commits
Wenn und sobald Ihnen Zugriff gewährt wurde, senden Sie bitte eine Nachricht
an @email{guix-devel@@gnu.org}, um dies bekanntzugeben, die Sie erneut mit
dem OpenPGP-Schlüssel signiert haben, mit dem Sie Commits signieren (tun Sie
das, bevor Sie Ihren ersten Commit pushen). Auf diese Weise kann jeder Ihren
Beitritt mitbekommen und nachprüfen, dass dieser OpenPGP-Schlüssel wirklich
Ihnen gehört.

@quotation Wichtig
Bevor Sie zum ersten Mal pushen dürfen, müssen die Betreuer:

@enumerate
@item
Ihren OpenPGP-Schlüssel zum @code{keyring}-Branch hinzugefügt haben,
@item
Ihren OpenPGP-Fingerabdruck in die Datei @file{.guix-authorizations}
derjenigen Branches eingetragen haben, auf die Sie commiten möchten.
@end enumerate
@end quotation

@item
Wenn Sie den Rest dieses Abschnitts jetzt auch noch lesen, steht Ihrer
Karriere nichts mehr im Weg!
@end enumerate

@quotation Anmerkung
Betreuer geben gerne anderen Leuten Commit-Zugriff, die schon einige Zeit
dabei waren und ihre Eignung unter Beweis gestellt haben. Seien Sie nicht
schüchtern und unterschätzen Sie Ihre Arbeit nicht!

Sie sollten sich bewusst sein, dass unser Projekt auf ein besser
automatisiertes System hinarbeitet, um Patches zu überprüfen und zu
mergen. Als Folge davon werden wir vielleicht weniger Leuten Commit-Zugriff
auf das Haupt-Repository geben. Bleiben Sie auf dem Laufenden!
@end quotation

Wenn Sie Commit-Zugriff erhalten, passen Sie bitte auf, dass Sie der
folgenden Richtlinie folgen (Diskussionen über die Richtlinie können wir auf
@email{guix-devel@@gnu.org} führen).

Nichttriviale Patches sollten immer zuerst an @email{guix-patches@@gnu.org}
geschickt werden (zu den trivialen Patches gehört zum Beispiel das Beheben
von Schreibfehlern usw.). Was an diese Mailing-Liste geschickt wird, steht
danach in der Patch-Datenbank (siehe @ref{Überblick über gemeldete Fehler und Patches}).

Bei Patches, die nur ein einziges neues Paket hinzufügen, das auch noch
einfach ist, ist es in Ordnung, sie zu commiten, wenn Sie von von ihnen
überzeugt sind (das bedeutet, Sie sollten es in einer chroot-Umgebung
erstellt haben und Urheberrecht und Lizenzen mit angemessener Gründlichkeit
geprüft haben). Für Paketaktualisierungen gilt dasselbe, außer die
Aktualisierung hat viele Neuerstellungen zur Folge (wenn Sie zum Beispiel
GnuTLS oder GLib aktualisieren). Wir haben eine Mailing-Liste für
Commit-Benachrichtigungen (@email{guix-commits@@gnu.org}), damit andere sie
bemerken. Bevor Sie Ihre Änderungen pushen, führen Sie @code{git pull
--rebase} aus.

Alle Commits, die auf das zentrale Repository auf Savannah gepusht werden,
müssen mit einem OpenPGP-Schlüssel signiert worden sein, und diesen
öffentlichen Schlüssel sollten Sie auf Ihr Benutzerkonto auf Savannah und
auf öffentliche Schlüsselserver wie @code{keys.openpgp.org} hochladen. Um
Git so zu konfigurieren, dass es Commits automatisch signiert, führen Sie
diese Befehle aus:

@example
git config commit.gpgsign true
git config user.signingkey CABBA6EA1DC0FF33
@end example

Sie können als Vorsichtsmaßnahme, um @emph{nicht} versehentlich unsignierte
Commits auf Savannah zu pushen, den Pre-Push-Git-Hook benutzen, der sich
unter @file{etc/git/pre-push} befindet:

@example
cp etc/git/pre-push .git/hooks/pre-push
@end example

Wenn Sie einen Commit für jemand anderen pushen, fügen Sie bitte eine
@code{Signed-off-by}-Zeile am Ende der Commit-Log-Nachricht hinzu — z.B.@:
mit @command{git am --signoff}. Dadurch lässt es sich leichter überblicken,
wer was getan hat.

Wenn Sie Kanalneuigkeiten hinzufügen (siehe @ref{Kanäle, Kanalneuigkeiten
verfassen}), dann sollten Sie prüfen, dass diese wohlgeformt sind, indem Sie
den folgenden Befehl direkt vor dem Pushen ausführen:

@example
make check-channel-news
@end example

Alles andere schicken Sie bitte an @email{guix-patches@@gnu.org} und warten
eine Weile, ohne etwas zu commiten, damit andere Zeit haben, sich die
Änderungen anzuschauen (siehe @ref{Einreichen von Patches}). Wenn Sie nach zwei
Wochen keine Antwort erhalten haben und von den Änderungen überzeugt sind,
ist es in Ordnung, sie zu commiten.

Die letzten Anweisungen werden wir vielleicht noch ändern, damit man
unstrittige Änderungen direkt commiten kann, wenn man mit von Änderungen
betroffenen Teilen vertraut ist.

Damit es weniger wahrscheinlich ist, dass Fehler passieren, werden wir das
Savannah-Konto von Commitern nach 12 Monaten der Inaktivität aus dem
Guix-Projekt bei Savannah löschen und ihren Schlüssel aus
@file{.guix-authorizations} entfernen. Solche Commiter können den Betreuern
eine E-Mail schicken, um ohne einen Durchlauf des Fürsprecherprozesses
wieder Commit-Zugriff zu bekommen.

Eine Sache noch: Das Projekt entwickelt sich nicht nur deswegen schnell,
weil Commiter ihre eigenen tollen Änderungen pushen, sondern auch, weil sie
sich Zeit nehmen, die Änderungen anderer Leute in „Reviews“ zu
@emph{überprüfen} und zu pushen. Als Commiter begrüßen wir es, wenn Sie Ihre
Expertise und Commit-Rechte dafür einsetzen, auch anderen Mitwirkenden zu
helfen!

@node Das Guix-Paket aktualisieren
@section Das Guix-Paket aktualisieren

@cindex update-guix-package, Guix-Paket aktualisieren
Manchmal möchte man die für das Paket @code{guix} (wie es in @code{(gnu
packages package-management)} definiert ist) verwendete Version auf eine
neuere Version aktualisieren, zum Beispiel um neue Funktionalitäten des
Daemons dem Diensttyp @code{guix-service-type} zugänglich zu machen. Um
diese Arbeit zu erleichtern, kann folgender Befehl benutzt werden:

@example
make update-guix-package
@end example

Das make-Ziel @code{update-guix-package} wird den neuesten bekannten
@emph{Commit}, also den, der @code{HEAD} in Ihrem Guix-Checkout entspricht,
verwenden, den Hash des zugehörigen Quellbaums berechnen und die Einträge
für @code{commit}, @code{revision} und den Hash in der Paketdefinition von
@code{guix} anpassen.

Um zu prüfen, dass das aktualisierte @code{guix}-Paket die richtigen Hashes
benutzt und erfolgreich erstellt werden kann, können Sie den folgenden
Befehl aus dem Verzeichnis Ihres Guix-Checkouts heraus ausführen:

@example
./pre-inst-env guix build guix
@end example

Als Schutz vor einer versehentlichen Aktualisierung des @code{guix}-Pakets
auf einen Commit, den andere Leute gar nicht haben, wird dabei geprüft, ob
der benutzte Commit bereits im bei Savannah angebotenen Guix-Git-Repository
vorliegt.

Diese Prüfung können Sie @emph{auf eigene Gefahr hin} abschalten, indem Sie
die Umgebungsvariable @code{GUIX_ALLOW_ME_TO_USE_PRIVATE_COMMIT}
setzen. Wenn diese Variable gesetzt ist, wird der aktualisierte
Paketquellcode außerdem in den Store eingefügt. Dies stellt einen Teil des
Prozesses zur Veröffentlichung neuer Versionen von Guix dar.
