@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
Libera-Chat-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 beim Schreiben 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::  Die Ordnung bewahren.
* Commit-Zugriff::           Auf die offiziellen Repositorys pushen.
* Das Guix-Paket aktualisieren::  Die Paketdefinition für Guix erneuern.
* Dokumentation schreiben::  Die Dokumentation in GNU Guix verbessern.
* Guix übersetzen.::        Bring Guix deine Muttersprache bei.
@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 shell -D guix --pure
@end example

Siehe @ref{Aufruf von guix shell} 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 shell} ausführen:

@example
guix shell -D guix help2man git strace --pure
@end example

Damit können Sie die Infrastruktur des Erstellungssystems mit Autoconf und
Automake erzeugen.

@example
./bootstrap
@end example

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.

Anschließend führen Sie dies aus:

@example
./configure --localstatedir=/var
@end example

@noindent
Dabei ist @file{/var} der normale @code{localstatedir}-Wert (weitere
Informationen siehe @ref{Der Store}). 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.

Schließlich können Sie Guix erstellen und, wenn Sie möchten, die Tests
ausführen (siehe @ref{Den Testkatalog laufen lassen}):

@example
make
make check
@end example

@noindent
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

Wenn Sie das Repository einmal aktualisieren, kann es passieren, dass
@command{make} mit einer Fehlermeldung ähnlich wie dieser fehlschlägt:

@example
error: failed to load 'gnu/packages/dunst.scm':
ice-9/eval.scm:293:34: In procedure abi-check: #<record-type <origin>>: record ABI mismatch; recompilation needed
@end example

Das bedeutet, dass sich einer der in Guix definierten Verbundstypen (in
diesem Beispiel der @code{origin}-Verbundstyp) geändert hat und alle Teile
von Guix für diese Änderung neu kompiliert werden müssen. Um das zu
veranlassen, führen Sie @command{make clean-go} aus, gefolgt von
@command{make}.

@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{Interaktiv mit Guix arbeiten}):

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

Manchmal, insbesondere wenn Sie das Repository aktualisiert haben, wird beim
Ausführen mit @command{./pre-inst-env} eine Nachricht ähnlich wie in diesem
Beispiel erscheinen:

@example
;;; note: source file /home/user/projects/guix/guix/progress.scm
;;;       newer than compiled /home/user/projects/guix/guix/progress.go
@end example

Es handelt sich lediglich um einen Hinweis und Sie können ihn getrost
ignorieren. Los werden Sie die Nachricht, indem Sie @command{make -j4}
ausführen. Bis dahin läuft Guile etwas langsamer als sonst, weil es den
Quellcode interpretieren muss und nicht auf vorbereitete
Guile-Objekt-Dateien (@file{.go}) zurückgreifen kann.

Sie können @command{make} automatisch ausführen lassen, während Sie am Code
arbeiten, nämlich mit @command{watchexec} aus dem Paket @code{watchexec}. Um
zum Beispiel jedes Mal neu zu erstellen, wenn Sie etwas an einer Paketdatei
ändern, führen Sie @samp{watchexec -w gnu/packages -- make -j4} aus.

@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 install emacs guile emacs-geiser emacs-geiser-guile
@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 an für häufige Git-Commit-Nachrichten und
Paketdefinitionen im Verzeichnis @file{etc/snippets}. Diese Vorlagen können
benutzt werden, um kurze Auslöse-Zeichenketten zu interaktiven
Textschnipseln umzuschreiben. Wenn Sie dazu
@url{https://joaotavora.github.io/yasnippet/, YASnippet} verwenden, möchten
Sie vielleicht das Schnipselverzeichnis @file{etc/snippets/yas} zu Ihrer
@var{yas-snippet-dirs}-Variablen in Emacs hinzufügen. Wenn Sie
@url{https://github.com/minad/tempel/, Tempel} verwenden, fügen Sie
stattdessen den Pfad @file{etc/snippets/tempel/*} zur Emacs-Variablen
@var{tempel-path} hinzu.

@lisp
;; @r{Angenommen das Guix-Checkout ist in ~/src/guix.}
;; @r{Yasnippet-Konfiguration}
(with-eval-after-load 'yasnippet
  (add-to-list 'yas-snippet-dirs "~/src/guix/etc/snippets/yas"))
;; @r{Tempel-Konfiguration}
(with-eval-after-load 'tempel
   ;; Wenn tempel-path noch keine Liste ist, sondern eine Zeichenkette
   (unless (listp 'tempel-path)
     (setq tempel-path (list tempel-path)))
   (add-to-list 'tempel-path "~/src/guix/etc/snippets/tempel/*"))
@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@tie{}– 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{https://@value{SUBSTITUTE-SERVER-1}, 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-1}} 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.
* Elm-Pakete::               Bäume aus Browser-Code.
* 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 (wenn das hier
eine Rolle spielen sollte) und vermeidet Probleme, die mit der maximalen
Länge von Shebangs zu tun haben (127 Bytes beim Linux-Kernel). Bei Paketen,
die @code{git-fetch} oder @code{hg-fetch} benutzen, können Sie dafür
Hilfsfunktionen nutzen (siehe unten). Am besten benutzen Sie in
@code{origin}s jedoch den vollständigen Commit-Bezeichner, 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

@deffn {Scheme-Prozedur} git-version @var{VERSION} @var{REVISION} @var{COMMIT}
Liefert die Zeichenkette für die Version bei Paketen, die @code{git-fetch}
benutzen.

@lisp
(git-version "0.2.3" "0" "93818c936ee7e2f1ba1b315578bde363a7d43d05")
@result{} "0.2.3-0.93818c9"
@end lisp
@end deffn

@deffn {Scheme-Prozedur} hg-version @var{VERSION} @var{REVISION} @var{ÄNDERUNGSSATZ}
Liefert die Zeichenkette für die Version bei Paketen, die @code{hg-fetch}
benutzen.<
@end deffn

@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
achtgeben, 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@tie{}– z.B.@: „Core GNU utilities (file, text, shell)“@tie{}–,
oder aussagen, wofür es benutzt wird@tie{}– 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“)@tie{}– 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 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.

@quotation Anmerkung
Im Moment sind gleich zwei verschiedene Erstellungssysteme für Python-Pakete
in Guix in Umlauf: @var{python-build-system} und
@var{pyproject-build-system}. Lange Zeit hat man sein Python-Paket aus einer
Datei @file{setup.py} heraus erstellt, deren gewachsene Struktur
@emph{nicht} formell festgelegt war. Das lief überraschend gut, wenn man
sich den Erfolg von Python anschaut, allerdings ließen sich nur schwer
Werkzeuge zur Handhabung schreiben. Daraus ergab sich eine Vielzahl
alternativer Erstellungssysteme, bis sich die Gemeinschaft auf einen
@url{https://peps.python.org/pep-0517/, formellen Standard} zum Festlegen
der Erstellungsanforderungen geeinigt hatte. @var{pyproject-build-system}
ist die Implementierung dieses Standards in Guix. Wir stufen es als
„experimentell“ ein, insofern als dass es noch nicht all die @emph{Build
Backends} für PEP-517 unterstützt. Dennoch würden wir es begrüßen, wenn Sie
es für neue Python-Pakete verwenden und Probleme melden
würden. Schlussendlich wird es für veraltet erklärt werden und in
@var{python-build-system} aufgehen.
@end quotation

@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{pyproject.toml}, der Datei
@file{setup.py}, in @file{requirements.txt} oder in @file{tox.ini} (letztere
beherbergt hauptsächlich Abhängigkeiten für Tests).

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-Paket so geschrieben, dass es @code{setuptools} und
@code{pip} mitinstalliert. Das wird sich bald ändern und wir möchten unseren
Nutzern nahelegen, für Python-Entwicklungsumgebungen @code{python-toolchain}
zu verwenden.

@command{guix lint} wird Sie mit einer Warnung darauf aufmerksam machen,
wenn @code{setuptools} oder @code{pip} zu den nativen Eingaben hinzugefügt
wurden, weil man im Allgemeinen keines der beiden anzugeben braucht.

@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@tie{}– z.B.@:
jene, die in @file{pyproject.toml} unter @code{build-system.requires} stehen
oder die mit dem Schlüsselwort @code{setup_requires} in @file{setup.py}
aufgeführt sind@tie{}– oder Abhängigkeiten, die nur zum Testen gebraucht
werden@tie{}– also die in @code{tests_require} oder in der
@file{tox.ini}@tie{}–, schreibt man 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 Elm-Pakete
@subsection Elm-Pakete

@cindex Elm
Sie dürfen Elm-Anwendungen Namen geben wie bei anderer Software: Elm muss
@emph{nicht} im Namen vorkommen.

Die Namen dessen, was bei Elm als Paket bekannt ist (siehe
@code{elm-build-system} im Unterabschnitt @ref{Erstellungssysteme}), müssen
dagegen diesem Format folgen: @var{Autor}@code{/}@var{Projekt}, wo sowohl im
@var{Autor} als auch im @var{Projekt} Bindestriche vorkommen können, und
manchmal im @var{Autor} sogar Großbuchstaben enthalten sind.

Um daraus einen Guix-Paketnamen zu bilden, folgen wir einer ähnlichen
Konvention wie bei Python-Paketen (siehe @ref{Python-Module}), d.h.@: vorne
kommt ein Präfix @code{elm-}, außer der Name beginnt ohnehin mit
@code{elm-}.

In vielen Fällen lässt sich der Name eines Elm-Pakets, den es beim Anbieter
trägt, heuristisch rekonstruieren, aber @emph{nicht} immer, denn bei der
Umwandlung in einen Namen im Guix-Stil geht Information verloren. Also
achten Sie darauf, in solchen Fällen eine Eigenschaft @code{'upstream-name}
anzugeben, damit @samp{guix import elm} funktionieren kann (siehe
@ref{Aufruf von guix import}). Insbesondere ist es nötig, den Namen beim
Anbieter ausdrücklich anzugeben, wenn:

@enumerate
@item
Der @var{Autor} gleich @code{elm} ist und in @var{Projekt} ein oder mehrere
Bindestriche auftauchen, wie bei @code{elm/virtual-dom}, oder wenn

@item
In @var{Autor} Bindestriche oder Großbuchstaben auftauchen, z.B.@:
@code{Elm-Canvas/raster-shapes}@tie{}– sofern @var{Autor} nicht
@code{elm-explorations} ist, was eine Sonderbehandlung bekommt, so dass
Pakete wie @code{elm-explorations/markdown} die Eigenschaft
@code{'upstream-name} @emph{nicht} zu haben brauchen.
@end enumerate

Im Modul @code{(guix build-system elm)} finden Sie folgende Werkzeuge, mit
denen Sie mit den Konventionen für Namen und Ähnliches umgehen können:

@deffn {Scheme-Prozedur} elm-package-origin @var{Elm-Name} @var{Version} @
  @var{Hash} Liefert einen Git-Paketursprung nach den Regeln für
Repository-Name und Tags, die für öffentliche Elm-Pakete vorgeschrieben
sind. Der Name für den Paketursprung ergibt sich aus @var{Elm-Name}, das ist
der Name beim Anbieter, mit der Version @var{Version} und SHA256-Prüfsumme
@var{Hash}.

Zum Beispiel:
@lisp
(package
  (name "elm-html")
  (version "1.0.0")
  (source
   (elm-package-origin
    "elm/html"
    version
    (base32 "15k1679ja57vvlpinpv06znmrxy09lbhzfkzdc89i01qa8c4gb4a")))
  …)
@end lisp
@end deffn

@deffn {Scheme-Prozedur} elm->package-name @var{Elm-Name}
Liefert den Paketnamen im Guix-Stil für ein Elm-Paket, das dort
@var{Elm-Name} heißt.

Achtung, @code{elm->package-name} kann unterschiedliche @var{Elm-Name} auf
dasselbe Ergebnis abbilden.
@end deffn

@deffn {Scheme-Prozedur} guix-package->elm-name @var{Paket}
Für ein Elm-Paket @var{Paket} wird ermittelt, welchen Namen es beim Anbieter
trägt, oder @code{#f}, wenn dieser Anbietername weder in den unter
@var{properties} aufgeführten Paketeigenschaften steht noch sich mit
@code{infer-elm-package-name} ableiten lässt.
@end deffn

@deffn {Scheme-Prozedur} infer-elm-package-name @var{Guix-Name}
Liefert für den @var{guix-name} eines Elm-Pakets den daraus abgeleiteten
Namen beim Anbieter oder @code{#f}, wenn er sich nicht ableiten lässt. Wenn
das Ergebnis etwas anderes als @code{#f} ist, können wir es an
@code{elm->package-name} übergeben und bekommen wieder @var{guix-name}
heraus.
@end deffn

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

@findex define-record-type*
@findex match-record
@cindex Mustervergleich
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}), während bei Verbundstypen @code{match-record} aus dem Modul
@code{(guix records)} angemessener ist, womit, anders als bei @code{match},
bereits bei der Makroumschreibung sichergestellt wird, dass die Feldnamen
richtig sind.

@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
./pre-inst-env guix style @var{Paket}
@end example

@noindent
Siehe @ref{Aufruf von guix style} für weitere Informationen.

@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 (siehe @ref{Submitting patches to a project,,, git, Git-Benutzerhandbuch}). In diesem Fall möchten
wir Ihnen nahelegen, zunächst einige Git-Repository-Optionen festzulegen
(siehe @ref{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 @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{FEHLERNUMMER}@@debbugs.gnu.org} senden kann, wobei
@var{FEHLERNUMMER} 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
Verwenden Sie @code{guix style @var{Paket}}, um die neue Paketdefinition
gemäß den Konventionen des Guix-Projekts zu formatieren (siehe @ref{Aufruf von guix style}).

@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 @code{virtualization} zu @code{use-service-modules}
und 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 oder aarch64 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@tie{}– 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}). Dieser
Branch ist erst spät im Entwicklungsprozess nutzbar.

@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. Dieser Branch ist erst spät im
Entwicklungsprozess nutzbar.
@end table

All diese Branches werden kontinuierlich
@uref{https://@value{SUBSTITUTE-SERVER-1}, 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-1}} 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@tie{}–
zum Beispiel die Nutzung anderer Befehlssatzerweiterungen@tie{}– oder mit
dem Betriebssystem-Kernel@tie{}– 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{guix style}
(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.

Rechnen Sie damit, dass es etwas dauert, bis Ihr erster Patch an
@email{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 @email{@var{FEHLERNUMMER}-done@@debbugs.gnu.org} senden.

@node Git einrichten
@subsection Git einrichten
@cindex Git-Konfiguration
@cindex @code{git format-patch}
@cindex @code{git send-email}

Wenn es noch nicht geschehen ist, wollen Sie vielleicht den Namen und die
E-Mail-Adresse festlegen, mit der Ihre Commits ausgestellt werden (siehe
@ref{telling git your name, , Telling Git your name, git,
Git-Benutzerhandbuch}). Wenn Sie einen anderen Namen oder eine andere
E-Mail-Adresse nur für Commits in diesem Repository verwenden möchten,
können Sie @command{git config --local} benutzen oder Änderungen in der
Datei @file{.git/config} im Repository statt in @file{~/.gitconfig}
durchführen.

Wir stellen einige Standardeinstellungen in @file{etc/git/gitconfig} zur
Verfügung, die ändern, wie Patches erzeugt werden, damit sie leichter zu
lesen und anzuwenden sind. Sie können die Einstellungen von Hand übernehmen,
indem Sie sie in die Datei @file{.git/config} in Ihrem Checkout kopieren,
oder Git anweisen, die ganze Datei per @code{include}-Direktive zu laden:

@example
git config --local include.path ../etc/git/gitconfig
@end example

Von da an werden sich jegliche Änderungen an @file{etc/git/gitconfig}
automatisch auswirken.

Weil der erste Patch in einer Patch-Reihe getrennt versandt werden muss
(siehe @ref{Senden einer Patch-Reihe}), kann es helfen, @command{git
format-patch} statt @command{git send-email} mit der Nachrichtenverkettung
zu beauftragen:

@example
git config --local format.thread shallow
git config --local sendemail.thread no
@end example

@node Senden einer Patch-Reihe
@subsection Senden einer Patch-Reihe
@cindex Patch-Reihe
@cindex @code{git send-email}
@cindex @code{git format-patch}

@unnumberedsubsubsec Einzelne Patches
@anchor{Einzelne Patches}
Der Befehl @command{git send-email} ist die beste Art, wie Sie sowohl
einzelne Patches als auch Patch-Reihen (siehe @ref{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 @command{git diff} kopierten, würden die
Metadaten des Commits fehlen.

@quotation Anmerkung
Der Befehl @command{git send-email} ist in der Ausgabe namens
@code{send-email} des @code{git}-Pakets enthalten, also
@code{git:send-email}.
@end quotation

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

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

@quotation Tipp
Wenn Sie in der Betreffzeile zu Ihrem Patch ein zusätzliches Präfix mitgeben
möchten, können Sie die Befehlszeilenoption @option{--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
@code{master}-Branch von @url{https://git.savannah.gnu.org/cgit/guix.git}.

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

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 @option{-a}
(der Abkürzung von @option{--annotate}) verzichten.

Mit der Befehlszeilenoption @option{--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
@code{rebase} zu übernehmen und zu mergen.

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

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

Die @var{FEHLERNUMMER} finden Sie heraus, indem Sie entweder auf der
Mumi-Oberfläche auf @url{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.

@unnumberedsubsubsec Teams ansprechen
@anchor{Teams ansprechen}
@cindex Teams
Mit dem Skript @file{etc/teams.scm} können Sie direkt all die Leute in
Kenntnis setzen, die sich für Ihren Patch interessieren könnten (siehe
@ref{Teams}). Benutzen Sie @command{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 @command{etc/teams.scm cc} die
geeigneten Befehlszeilenoptionen für @command{git send-email} ausgeben
lassen, um die richtigen Teammitglieder anzuschreiben; alternativ werden mit
@command{etc/teams.scm cc-members} die Teams automatisch ermittelt.

@unnumberedsubsubsec Mehrere Patches
@anchor{Mehrere Patches}
@cindex Deckblatt (Cover Letter)
Obwohl @command{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
@email{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
@file{ausgehend} anlegen und darin sowohl Ihre Patch-Reihe als auch ein
Deckblatt namens @file{0000-cover-letter.patch} platzieren, indem Sie
@command{git format-patch} aufrufen.

@example
$ git format-patch -@var{ANZAHL_COMMITS} -o ausgehend \
      --cover-letter --base=auto
@end example

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

@example
$ 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!
@end example

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.

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

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

@example
$ git send-email -@var{ANZAHL_COMMITS} \
      -v@var{REVISION} --base=auto \
      --to @var{FEHLERNUMMER}@@debbugs.gnu.org
@end example

Wenn nötig, können Sie mit @option{--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.

@node Teams
@subsection Teams
@cindex Teams

Der Quellcode von Guix ist unter mehreren Mentorenteams aufgeteilt. Um sich
eine Liste aller Teams anzeigen zu lassen, führen Sie aus einem
Guix-Checkout Folgendes aus:

@example
$ ./etc/teams.scm list-teams
id: mentors
name: Mentors
description: A group of mentors who chaperone contributions by newcomers.
members:
+ Christopher Baines <mail@@cbaines.net>
+ Ricardo Wurmus <rekado@@elephly.net>
+ Mathieu Othacehe <othacehe@@gnu.org>
+ jgart <jgart@@dismail.de>
+ Ludovic Courtès <ludo@@gnu.org>
…
@end example

Sie können den folgenden Befehl benutzen, um das Team @code{Mentors} bei
einer Patch-Reihe in CC zu setzen:

@example
$ git send-email --to @var{FEHLERNUMMER}@@debbugs.gnu.org $(./etc/teams.scm cc mentors) *.patch
@end example

Das zuständige Team kann auch automatisch anhand der geänderten Dateien
ermittelt werden. Wenn Sie zum Beispiel für die letzten zwei Commits im
aktuellen Git-Repository um Überprüfung bitten möchten, führen Sie dies aus:

@example
$ guix shell -D guix
[env]$ git send-email --to @var{FEHLERNUMMER}@@debbugs.gnu.org $(./etc/teams.scm cc-members HEAD~2 HEAD) *.patch
@end example

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

Dieser Abschnitt beschreibt, wie das Guix-Projekt Fehlerberichte und
eingereichte Patches verwaltet.

@menu
* Der Issue-Tracker::        Die offizielle Übersicht über Bugs und 
                               Patches.
* Debbugs-Benutzerschnittstellen::  Möglichkeiten, mit Debbugs umzugehen.
* Debbugs-Usertags::         Meldungen mit eigenen Kennzeichen versehen.
@end menu

@node Der Issue-Tracker
@subsection Der Issue-Tracker

@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}).

@node Debbugs-Benutzerschnittstellen
@subsection Debbugs-Benutzerschnittstellen

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 Debbugs-Usertags
@subsection Debbugs-Usertags

@cindex Usertags, für Debbugs
@cindex Debbugs-Usertags
Debbugs bietet die Möglichkeit, sogenannte @dfn{Usertags} zu vergeben,
d.h.@: jeder Benutzer kann jedem Fehlerbericht beliebige Kennzeichnungen
zuweisen. Die gemeldeten Fehler können anhand der Usertags gesucht werden,
deshalb lassen sich die Meldungen so gut organisieren@footnote{Die Liste der
Usertags ist öffentlich zugänglich und jeder kann die Usertag-Liste jedes
anderen Nutzers ändern. Sie sollten daran denken, wenn Sie diese
Funktionalität gebrauchen möchten.}.

Wenn Sie sich zum Beispiel alle Fehlerberichte (oder Patches, wenn Sie
@code{guix-patches} betrachten) mit dem Usertag @code{powerpc64le-linux} für
Benutzer @code{guix} ansehen möchten, öffnen Sie eine URL wie die folgende
in einem Webbrowser:
@url{https://debbugs.gnu.org/cgi-bin/pkgreport.cgi?tag=powerpc64le-linux;users=guix}.

Mehr Informationen, wie Sie Usertags benutzen können, finden Sie in der
Dokumentation von Debbugs bzw.@: wenn Sie ein externes Programm benutzen, um
mit Debbugs zu interagieren, in der Dokumentation dieses Programms.

In Guix experimentieren wir damit, Usertags zum Beobachten von Fehlern zu
verwenden, die nur bestimmte Architekturen betreffen. Zur leichteren
Zusammenarbeit verbinden wir all unsere Usertags einzig mit dem Benutzer
@code{guix}. Für diesen Benutzer gibt es zurzeit folgende Usertags:

@table @code

@item powerpc64le-linux
Mit diesem Usertag wollen wir es leichter machen, die Fehler zu finden, die
für den Systemtyp @code{powerpc64le-linux} am wichtigsten sind. Bitte weisen
Sie ihn solchen Bugs oder Patches zu, die nur @code{powerpc64le-linux} und
keine anderen Systemtypen betreffen. Des Weiteren können Sie damit Probleme
kennzeichnen, die für den Systemtyp @code{powerpc64le-linux} besonders
bedeutsam sind, selbst wenn das Problem sich auch bei anderen Systemtypen
zeigt.

@item Reproduzierbarkeit
Verwenden Sie den Usertag @code{reproducibility} für Fehler in der
Reproduzierbarkeit einer Erstellung. Es wäre zum Beispiel angemessen, den
Usertag für einen Fehlerbericht zu einem Paket zuzuweisen, das nicht
reproduzierbar erstellt wird.

@end table

Wenn Sie Commit-Zugriff haben und einen neuen Usertag verwenden möchten,
dann fangen Sie einfach an, ihn mit dem Benutzer @code{guix} zu
benutzen. Erweist sich der Usertag für Sie als nützlich, sollten Sie
vielleicht diesen Handbuchabschnitt ergänzen, um andere in Kenntnis zu
setzen, was Ihr Usertag bedeutet.

@node Commit-Zugriff
@section Commit-Zugriff

@cindex Commit-Zugriff, für Entwickler
Jeder kann bei Guix mitmachen, auch ohne Commit-Zugriff zu haben (siehe
@ref{Einreichen von Patches}). Für Leute, die häufig zu Guix beitragen, kann es
jedoch praktischer sein, Schreibzugriff auf das Repository zu haben. Als
Daumenregel sollte ein Mitwirkender 50-mal überprüfte Commits eingebracht
haben, um als Committer zu gelten, und schon mindestens 6 Monate im Projekt
aktiv sein. Dadurch gab es genug Zusammenarbeit, um Mitwirkende
einzuarbeiten und einzuschätzen, ob sie so weit sind, Committer zu
werden. Dieser Commit-Zugriff sollte nicht als Auszeichnung verstanden
werden, sondern als Verantwortung, die ein Mitwirkender auf sich nimmt, um
dem Projekt zu helfen.

Im folgenden Abschnitt wird beschrieben, wie jemand Commit-Zugriff bekommt,
was man tun muss, bevor man zum ersten Mal einen Commit pusht, und welche
Richtlinien und Erwartungen die Gemeinschaft an Commits richtet, die auf das
offizielle Repository gepusht werden.

@subsection Um Commit-Zugriff bewerben

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 Committer, die für Sie eintreten. Sie können die Liste der
Committer 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 Committern 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 Committer 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

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

# Ersetzen Sie den Fingerabdruck durch Ihren öffentlichen PGP-Schlüssel.
git config user.signingkey CABBA6EA1DC0FF33
@end example

Um zu prüfen, ob Commits mit dem richtigen Schlüssel signiert wurden,
benutzen Sie:

@example
make authenticate
@end example

Sie können als Vorsichtsmaßnahme, um @emph{nicht} versehentlich unsignierte
oder mit dem falschen Schlüssel signierte 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

Dadurch wird außerdem @code{make check-channel-news} aufgerufen, um zu
gewährleisten, dass die Datei @file{news.scm} gültig ist.

@subsection Commit-Richtlinie

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.

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@tie{}–
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.

@subsection Mit Fehlern umgehen

Durch Begutachten der von anderen eingereichten Patches („Peer-Review“,
siehe @ref{Einreichen von Patches}) und durch Werkzeuge wie @command{guix lint}
(siehe @ref{Aufruf von guix lint}) und den Testkatalog (siehe @ref{Den Testkatalog laufen lassen}) sollten Sie Fehler finden können, ehe sie gepusht wurden. Trotz
allem kann es gelegentlich vorkommen, dass nicht bemerkt wird, wenn nach
einem Commit etwas in Guix nicht mehr funktioniert. Wenn das passiert, haben
zwei Dinge Vorrang: Schadensbegrenzung und Verstehen, was passiert ist,
damit es nicht wieder zu vergleichbaren Fehlern kommt. Die Verantwortung
dafür tragen in erster Linie die Beteiligten, aber wie bei allem anderen
handelt es sich um eine Aufgabe der Gruppe.

Manche Fehler können sofort alle Nutzer betreffen, etwa wenn @command{guix
pull} dadurch nicht mehr funktioniert oder Kernfunktionen von Guix
ausfallen, wenn wichtige Pakete nicht mehr funktionieren (zur Erstellungs-
oder zur Laufzeit) oder wenn bekannte Sicherheitslücken eingeführt werden.

@cindex Revert von Commits
Die am Verfassen, Begutachten und Pushen von Commits Beteiligten sollten zu
den ersten gehören, die für zeitnahe Schadensbegrenzung sorgen, indem sie
mit einem nachfolgenden Commit („Follow-up“) den Fehler falls möglich
beseitigen oder den vorherigen Commit rückgängig machen („Revert“), damit
Zeit ist, das Problem auf ordentliche Weise zu beheben. Auch sollten sie das
Problem mit anderen Entwicklern bereden.

Wenn diese Personen nicht verfügbar sind, um den Fehler zeitnah zu beheben,
steht es anderen Committern zu, deren Commit(s) zu reverten und im
Commit-Log und auf der Mailingliste zu erklären, was das Problem war. Ziel
ist, dem oder den ursprünglichen Committer(n), Begutachter(n) und Autoren
mit mehr Zeit Gelegenheit zu geben, einen Vorschlag zum weiteren Vorgehen zu
machen.

Wenn das Problem erledigt wurde, müssen die Beteiligten ein Verständnis für
die Situation sicherstellen. Während Sie sich um Verständnis bemühen, legen
Sie den Fokus auf das Sammeln von Informationen und vermeiden Sie
Schuldzuweisungen. Lassen Sie die Beteiligten beschreiben, was passiert ist,
aber bitten Sie sie nicht, die Situation zu erklären, weil ihnen das
implizit Schuld zuspricht, was nicht hilfreich ist. Verantwortung ergibt
sich aus Einigkeit über das Problem, dass man daraus lernt und die Prozesse
verbessert, damit es nicht wieder vorkommt.

@subsection Entzug des Commit-Zugriffs

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

Betreuer@footnote{Siehe @uref{https://guix.gnu.org/en/about} für eine Liste
der Betreuer. Sie können ihnen eine private E-Mail schicken an
@email{guix-maintainers@@gnu.org}.} dürfen als letzten Ausweg auch jemandem
die Commit-Berechtigung entziehen, wenn die Zusammenarbeit mit der übrigen
Gemeinde zu viel Reibung erzeugt hat@tie{}– selbst wenn sich alles im Rahmen
der Verhaltensregeln abgespielt hat (siehe @ref{Mitwirken}). Davon machen
Betreuer nur Gebrauch nach öffentlichen oder privaten Diskussionen mit der
betroffenen Person und nach eindeutiger Ankündigung. Beispiele für
Verhalten, das die Zusammenarbeit behindert und zu so einer Entscheidung
führen könnte, sind:

@itemize
@item wiederholte Verletzung der oben beschriebenen Commit-Richtlinie,
@item wiederholtes Ignorieren von Kritik anderer Entwickler,
@item verletztes Vertrauen durch mehrere schwere Vorkommnisse in Folge.
@end itemize

Wenn Betreuer diesen Entschluss treffen, benachrichtigen sie die Entwickler
auf @email{guix-devel@@gnu.org}; Anfragen können an
@email{guix-maintainers@@gnu.org} gesendet werden. Abhängig von der
Situation wird ein Mitwirken der Betroffenen trotzdem weiterhin gerne
gesehen.

@subsection Aushelfen

Eine Sache noch: Das Projekt entwickelt sich nicht nur deswegen schnell,
weil Committer 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. Wir begrüßen es, wenn Sie als Committer
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.

@cindex documentation
@node Dokumentation schreiben
@section Dokumentation schreiben

Die Dokumentation für Guix wird mit dem Texinfo-System bereitgestellt. Wenn
Sie damit noch nicht vertraut sind, nehmen wir auch Beiträge zur
Dokumentation in den meisten anderen Formaten an. Reine Textdateien,
Markdown, Org und so weiter sind alle in Ordnung.

Schicken Sie Beiträge zur Dokumentation an @email{guix-patches@@gnu.org}.
Der Betreff sollte mit @samp{[DOCUMENTATION]} beginnen.

Wenn es um mehr als eine kleine Erweiterung der Dokumentation geht, ist es
uns allerdings lieber, wenn Sie einen ordentlichen Patch und keine solche
E-Mail schicken. Siehe @ref{Einreichen von Patches} für mehr Informationen, wie
Sie Patches abschicken.

Änderungen an der Dokumentation können Sie vornehmen, indem Sie
@file{doc/guix.texi} und @file{doc/contributing.texi} bearbeiten (letztere
enthält diesen Mitwirkungsteil der Dokumentation) oder indem Sie
@file{doc/guix-cookbook.texi} bearbeiten, worin Sie das Kochbuch
finden. Wenn Sie schon einmal die Dateien im Guix-Repository kompiliert
haben, werden dort auch viele weitere @file{.texi}-Dateien zu finden sein;
es handelt sich um übersetzte Fassungen dieser Dokumente. Verändern Sie
diese @emph{nicht}, denn die Übersetzung organisieren wir über
@uref{https://translate.fedoraproject.org/projects/guix, Weblate}. Siehe
@ref{Guix übersetzen.} für weitere Informationen.

Um die Dokumentation in lesefreundlichere Formate zu übertragen, ist der
erste Schritt, @command{./configure} in Ihrem Guix-Quellbaum laufen zu
lassen, wenn es noch nicht geschehen ist (siehe @ref{Guix vor der Installation ausführen}). Danach geht es mit diesen Befehlen weiter:

@itemize
@item @samp{make doc/guix.info}, um das Handbuch im Info-Format zu kompilieren.
      Sie können es mit @command{info doc/guix.info} überprüfen.
@item @samp{make doc/guix.html}, um die HTML-Version zu kompilieren.
      Lassen Sie Ihren Browser die entsprechende Datei im Verzeichnis
@file{doc/guix.html} anzeigen.
@item @samp{make doc/guix-cookbook.info}, so kompilieren Sie das Kochbuch im Info-Format.
@item @samp{make doc/guix-cookbook.html}, das kompiliert die HTML-Version des Kochbuchs.
@end itemize

@cindex Übersetzung
@cindex l10n
@cindex i18n
@cindex Native Language Support
@node Guix übersetzen.
@section Guix übersetzen.

Softwareentwicklung und Paketierung sind nicht die einzigen Möglichkeiten,
um bedeutsam zu Guix beizutragen. Übersetzungen in andere Sprachen sind auch
ein wertvoller Beitrag. In diesem Abschnitt ist der Übersetzungsprozess
beschrieben, mit Hinweisen dazu wie du mitmachen kannst, was übersetzt
werden kann, welche Fehler du vermeiden solltest und wie wir dich
unterstützen können.

Guix ist ein großes Projekt und hat mehrere Komponenten, die übersetzt
werden können. Wir koordinieren die Arbeit an der Übersetzung auf einer
@uref{https://translate.fedoraproject.org/projects/guix/,Weblate-Instanz},
die von unseren Freunden bei Fedora zur Verfügung gestellt wird. Sie
brauchen dort ein Konto, um Übersetzungen einzureichen.

Manche mit Guix auslieferbaren Pakete verfügen auch über Übersetzungen. An
deren Übersetzungsplattform sind wir nicht beteiligt. Wenn Sie ein in Guix
angebotenes Paket übersetzen möchten, sollten Sie mit dessen Entwicklern in
Kontakt treten oder auf deren Webauftritt nach Informationen suchen. Sie
können die Homepage zum Beispiel des @code{hello}-Pakets finden, indem Sie
@code{guix show hello} ausführen. Auf der Zeile „homepage“ sehen Sie, dass
@url{https://www.gnu.org/software/hello/} die Homepage ist.

Viele GNU-Pakete und Nicht-GNU-Pakete können beim
@uref{https://translationproject.org,Translation Project} übersetzt
werden. Manche Projekte, die aus mehreren Komponenten bestehen, haben ihre
eigene Plattform. Zum Beispiel hat GNOME die Übersetzungsplattform
@uref{https://l10n.gnome.org/,Damned Lies}.

Guix hat fünf Komponenten, die auf Weblate übersetzt werden können.

@itemize
@item @code{guix} umfasst alle Zeichenketten der Guix-Software (also das
      geführte Installationsprogramm, die Paketverwaltung etc.) außer den Paketen.
@item @code{packages} enthält die Zusammenfassungen (einzeilige Kurzbeschreibung)
      und die ausführlicheren Beschreibungen der Pakete in Guix.
@item @code{website} enthält den offiziellen Webauftritt von Guix außer
      Blogeinträgen und Multimedia.
@item @code{documentation-manual} entspricht diesem Handbuch.
@item @code{documentation-cookbook} ist die Komponente für das Kochbuch.
@end itemize

@subsubheading Wie Sie allgemein vorgehen

Sobald Sie ein Konto haben, sollten Sie eine Komponente des
@uref{https://translate.fedoraproject.org/projects/guix/,Guix-Projekts} und
eine Sprache auswählen können. Wenn Ihre Sprache in der Liste fehlt, gehen
Sie ans Ende und klicken Sie auf den „Neue Übersetzung
starten“-Knopf. Nachdem Sie die Sprache, in die Sie übersetzen möchten,
ausgewählt haben, wird eine neue Übersetzung angelegt.

Wie zahlreiche andere Freie-Software-Pakete benutzt Guix
@uref{https://www.gnu.org/software/gettext,GNU Gettext} für seine
Übersetzungen. Damit werden übersetzbare Zeichenketten aus dem Quellcode in
sogenannte PO-Dateien extrahiert.

Obwohl es sich bei PO-Dateien um Textdateien handelt, sollten Änderungen
nicht mit einem Texteditor vorgenommen werden, sondern mit Software eigens
zum Bearbeiten von PO-Dateien. In Weblate sind PO-Bearbeitungsfunktionen
integriert. Alternativ haben Übersetzer die Wahl zwischen vielen
Freie-Software-Werkzeugen zum Eintragen von Übersetzungen; ein Beispiel ist
@uref{https://poedit.net/,Poedit}. Nachdem Sie sich angemeldet haben,
@uref{https://docs.weblate.org/en/latest/user/files.html,laden} Sie die
geänderte Datei in Weblate hoch. Es gibt auch einen speziellen
@uref{https://www.emacswiki.org/emacs/PoMode,PO-Bearbeitungsmodus} für
Nutzer von GNU Emacs. Mit der Zeit finden Übersetzer heraus, welche Software
sie bevorzugen und welche die Funktionen bietet, die sie brauchen.

In Weblate finden Sie an vielen Stellen Verweise auf den Editor, um
Teilmengen der Zeichenketten oder alle davon zu übersetzen. Sehen Sie sich
um und werfen Sie einen Blick auf Weblates
@uref{https://docs.weblate.org/en/latest/,Dokumentation}, um sich mit der
Plattform vertraut zu machen.

@subsubheading Übersetzungskomponenten

In diesem Abschnitt erklären wir den Übersetzungsprozess genau und geben
Details, was Sie tun sollten und was nicht. Im Zweifelsfall kontaktieren Sie
uns bitte; wir helfen gerne!

@table @asis
@item guix
Guix ist in der Programmiersprache Guile geschrieben und manche
Zeichenketten enthalten besondere Formatzeichen, die von Guile interpretiert
werden. Weblate sollte diese besonderen Formatzeichen hervorheben. Sie
beginnen mit @code{~} gefolgt von einem oder mehreren Zeichen.

Beim Anzeigen der Zeichenkette ersetzt Guile die speziellen
Formatierungsmuster durch echte Werte. Zum Beispiel würde in die
Zeichenkette @samp{ambiguous package specification `~a'} die
Paketspezifikation anstelle von @code{~a} eingesetzt. Um die Zeichenkette
richtig zu übersetzen, müssen Sie den Formatierungscode in Ihrer Übersetzung
erhalten, aber Sie können ihn an die in Ihrer Sprache passenden Stelle in
der Übersetzung verlegen. Die französische Übersetzung ist zum Beispiel
@samp{spécification du paquet « ~a » ambiguë}, weil das Adjektiv dort ans
Ende vom Satz gehört.

Wenn mehrere Formatsymbole vorkommen, sollten Sie darauf achten, die
Reihenfolge beizubehalten. Guile weiß nicht, in welcher Reihenfolge die
eingesetzten Symbole auftauchen sollen, also setzt es sie in derselben
Abfolge wie im englischen Satz ein.

Es geht zum Beispiel @emph{nicht}, den Satz @samp{package '~a' has been
superseded by '~a'} wie @samp{'~a' superseeds package '~a'} zu übersetzen,
weil die Bedeutung umgekehrt wäre. Wenn @var{foo} durch @var{bar} abgelöst
wird, würde die Übersetzung behaupten, @samp{„foo“ löst Paket „bar“ ab}. Um
dieses Problem zu umgehen, ist es möglich, fortgeschrittene Formatierung
einzusetzen, mit der ein bestimmtes Datum ausgewählt wird statt der
englischen Reihenfolge zu folgen. Siehe @ref{Formatted Output,,, guile,
Referenzhandbuch zu GNU Guile} für weitere Informationen zu formatierter
Ausgabe in Guile.

@item Pakete

Manchmal trifft man in einer Paketbeschreibung auf in Texinfo-Markup
ausgezeichnete Wörter (siehe @ref{Zusammenfassungen und Beschreibungen}). Texinfo-Auszeichnungen sehen aus wie @samp{@@code@{rm
-rf@}}, @samp{@@emph@{important@}} usw. Wenn Sie übersetzen, belassen Sie
Auszeichnungen bitte, wie sie sind.

Die „@@“ nachfolgenden Zeichen bilden den Namen der Auszeichnung und der
Text zwischen „@{“ und „@}“ ist deren Inhalt. Im Allgemeinen sollten Sie
@emph{nicht} den Inhalt von Auszeichnungen wie @code{@@code} übersetzen,
weil Code wortwörtlich so aussehen muss und sich @emph{nicht} mit der
Sprache ändert. Dagegen können Sie den Inhalt von zur Formatierung dienenden
Auszeichnungen wie @code{@@emph}, @code{@@i}, @code{@@itemize},
@code{@@item} durchaus ändern. Übersetzen Sie aber @emph{nicht} den Namen
der Auszeichnung, sonst wird sie nicht erkannt. Übersetzen Sie @emph{nicht}
das auf @code{@@end} folgende Wort, denn es ist der Name der Auszeichnung,
die an dieser Position geschlossen wird (z.B.@: @code{@@itemize … @@end
itemize}).

@item documentation-manual und documentation-cookbook

Der erste Schritt für eine erfolgreiche Übersetzung des Handbuchs ist,
folgende Zeichenketten @emph{als Erstes} zu finden und zu übersetzen:

@itemize
@item @code{version.texi}: Übersetzen Sie diese Zeichenkette mit @code{version-xx.texi}
      wobei @code{xx} Ihr Sprachcode ist (wie er in der URL auf Weblate steht).
@item @code{contributing.texi}: Übersetzen Sie diese Zeichenkette mit
      @code{contributing.xx.texi}, wobei @code{xx} derselbe Sprachcode ist.
@item @code{Top}: Übersetzen Sie diese Zeichenkette @emph{nicht}; sie ist wichtig für Texinfo.
      Würden Sie sie übersetzen, würde das Dokument leer (weil ein Top-Knoten
fehlt). Bitte suchen Sie die Zeichenkette und tragen Sie @code{Top} als
Übersetzung ein.
@end itemize

Wenn diese Zeichenketten als erste ausgefüllt wurden, ist gewährleistet,
dass wir die Übersetzung ins Guix-Repository übernehmen können, ohne dass
der make-Vorgang oder die Maschinerie hinter @command{guix pull}
zusammenbricht.

Das Handbuch und das Kochbuch verwenden beide Texinfo. Wie bei
@code{packages} belassen Sie Texinfo-Auszeichnungen bitte so, wie sie
sind. Im Handbuch gibt es mehr mögliche Auszeichnungstypen als in den
Paketbeschreibungen. Im Allgemeinen sollten Sie den Inhalt von
@code{@@code}, @code{@@file}, @code{@@var}, @code{@@value} usw.@:
@emph{nicht} übersetzen. Sie sollten aber den Inhalt von
Formatierungsauszeichnungen wie @code{@@emph}, @code{@@i} usw.@: übersetzen.

Das Handbuch enthält Abschnitte, auf die man anhand ihres Namens mit
@code{@@ref}, @code{@@xref} und @code{@@pxref} verweisen kann. Wir haben
einen Mechanismus eingebaut, damit Sie deren Inhalt @emph{nicht} übersetzen
müssen. Lassen Sie einfach den englischen Titel stehen, dann werden wir ihn
automatisch durch Ihre Übersetzung des Titels ersetzen. So wird garantiert,
dass Texinfo den Knoten auf jeden Fall finden kann. Wenn Sie später die
Übersetzung ändern, ändern sich die Verweise darauf automatisch mit und Sie
müssen sie nicht alle selbst anpassen.

Nur wenn Sie Verweise vom Kochbuch auf das Handbuch übersetzen, dann müssen
Sie den Namen des Handbuchs und den Namen des Abschnitts ersetzen. Zum
Beispiel übersetzen Sie @code{@@pxref@{Defining Packages,,, guix, GNU Guix
Reference Manual@}}, indem Sie @code{Defining Packages} durch den Titel
dieses Abschnittes im übersetzten Handbuch ersetzen, aber @emph{nur dann},
wenn der Titel bereits übersetzt wurde. Wenn er nicht übersetzt wurde, dann
übersetzen Sie ihn auch hier @emph{nicht}, sonst funktioniert der Verweis
nicht. Schreiben Sie @code{guix.xx} statt @code{guix}, wobei @code{xx} Ihr
Sprachcode ist. Bei @code{GNU Guix Reference Manual} handelt es sich um den
Text, mit dem der Verweis angezeigt wird. Übersetzen Sie ihn wie immer Sie
mögen.

@item website

Die Seiten des Webauftritts sind in SXML geschrieben, einer Version von
HTML, der Grundlage des Webs, aber mit S-Ausdrücken. Wir haben einen
Prozess, um übersetzbare Zeichenketten aus dem Quellcode zu extrahieren und
komplexe S-Ausdrücke als vertrautere XML-Auszeichnungen darzustellen. Dabei
werden die Auszeichnungen nummeriert. Übersetzer können deren Reihenfolge
nach Belieben ändern, wie im folgenden Beispiel zu sehen ist.

@example
#. TRANSLATORS: Defining Packages is a section name
#. in the English (en) manual.
#: apps/base/templates/about.scm:64
msgid "Packages are <1>defined<1.1>en</1.1><1.2>Defining-Packages.html</1.2></1> as native <2>Guile</2> modules."
msgstr "Pakete werden als reine <2>Guile</2>-Module <1>definiert<1.1>de</1.1><1.2>Pakete-definieren.html</1.2></1>."
@end example

Allerdings müssen Sie dieselben Auszeichnungen verwenden. Sie können keine
weglassen.
@end table

Wenn Ihnen ein Fehler unterläuft, kann die Komponente in Ihrer Sprache
womöglich @emph{nicht} erstellt werden oder guix pull kann sogar
fehlschlagen. Um dies zu verhindern, haben wir einen Prozess, um den Inhalt
der Dateien vor einem Push auf das Repository zu überprüfen. In so einem
Fall werden wir die Übersetzung für Ihre Sprache @emph{nicht} aktualisieren
können und werden Sie deshalb benachrichtigen (über Weblate und/oder eine
E-Mail), damit Sie die Möglichkeit bekommen, das Problem zu beheben.

@subsubheading Abseits von Weblate

Momentan können manche Teile von Guix noch nicht mit Weblate übersetzt
werden. Wir freuen uns über Hilfe!

@itemize
@item Bei @command{guix pull} angezeigte Neuigkeiten können in @file{news.scm}
      übersetzt werden, jedoch @emph{nicht} über Weblate. Wenn Sie eine
Übersetzung bereitstellen wollen, können Sie uns einen Patch wie oben
beschrieben schicken oder uns einfach die Übersetzung zusammen mit Ihrer
Sprache und dem Namen des Neuigkeiteneintrags, den Sie übersetzt haben,
zukommen lassen. Siehe @ref{Kanalneuigkeiten verfassen} für weitere Informationen
zu Neuigkeiten über Kanäle.
@item Blogeinträge zu Guix können derzeit @emph{nicht} übersetzt werden.
@item Das Installations-Skript (für Fremddistributionen) gibt es nur auf Englisch.
@item Manche der Bibliotheken, die Guix benutzt, können @emph{nicht} übersetzt
      werden oder sie werden außerhalb von Guix übersetzt. Guile selbst ist
@emph{nicht} internationalisiert.
@item Andere Handbücher, auf die vom Handbuch oder Kochbuch aus verwiesen
      wird, sind oft @emph{nicht} übersetzt.
@end itemize

@subsubheading Bedingungen für die Aufnahme

Es müssen keine Bedingungen erfüllt werden, damit neue Übersetzungen der
Komponenten @code{guix} und @code{guix-packages} übernommen werden, außer
dass sie mindestens eine übersetzte Zeichenkette enthalten. Neue Sprachen
werden so bald wie möglich aufgenommen. Die Dateien können wieder entfernt
werden, wenn sie keine Übersetzungen mehr enthalten, weil die Zeichenketten,
die übersetzt wurden, nicht mehr mit den in Guix verwendeten übereinstimmen.

Aufgrund dessen, dass sich der Webauftritt an neue Benutzer richtet, möchten
wir, dass dessen Übersetzung so vollständig wie möglich ist, bevor wir sie
ins Menü zur Sprachauswahl aufnehmen. Eine neue Sprache muss dazu zumindest
zu 80% vollständig sein. Einmal aufgenommen kann eine Sprache dann wieder
entfernt werden, wenn sie eine Zeit lang nicht mehr übereinstimmt und zu
weniger als 60% übersetzt ist.

Handbuch und Kochbuch sind automatisch Teil des Standard-Ziels beim
Kompilieren. Jedes Mal, wenn wir die Übersetzungen in Guix mit Weblate
abgleichen, müssen die Entwickler alle übersetzten Hand- und Kochbücher neu
kompilieren. Das lohnt sich nicht, wenn so wenig übersetzt wurde, dass wir
größtenteils wieder das englische Hand- oder Kochbuch vor uns haben. Aus
diesem Grund nehmen wir eine neue Sprache hier nur auf, wenn mindestens 10%
der jeweiligen Komponente übersetzt sind. Eine bereits aufgenommene Sprache,
die eine Zeit lang nicht übereinstimmt und wo weniger als 5% übersetzt sind,
kann entfernt werden.

@subsubheading Übersetzungsinfrastruktur

Hinter Weblate steht ein Git-Repository, aus dem die Weblate-Instanz neue zu
übersetzende Zeichenketten bezieht und in das sie die neuen und
aktualisierten Übersetzungen pusht. Normalerweise würde es ausreichen,
Weblate Commit-Zugriff auf unsere Repositorys zu geben, aber wir haben uns
aus zwei Gründen dagegen entschieden. Erstens müssten wir sonst Weblate
Commit-Zugriff geben und seinen Signierschlüssel autorisieren, aber wir
haben in Weblate nicht auf gleiche Art Vertrauen wie in die Guix-Entwickler,
besonders weil wir die Instanz nicht selbst verwalten. Zweitens könnten
durch ein Missgeschick der Übersetzer dann das Erzeugen des Webauftritts
und/oder guix-pull-Aufrufe für all unsere Nutzer aufhören zu funktionieren,
ganz gleich was deren Spracheinstellungen sind.

Daher haben wir ein separates Repository für die Übersetzungen, das wir mit
unseren guix- und guix-artwork-Repositorys abgleichen, nachdem wir geprüft
haben, dass es durch die Übersetzung zu keinem Fehler kommt.

Entwickler können die neuesten PO-Dateien von Weblate in ihr Guix-Repository
laden, indem sie den Befehl @command{make download-po} ausführen. Er wird
die neuesten Dateien von Weblate automatisch herunterladen, in eine
kanonische Form bringen und überprüfen, dass sie keine Fehler
verursachen. Das Handbuch muss neu erstellt werden, um sicherzugehen, dass
keine neuen Probleme zum Absturz von Texinfo führen.

Bevor sie neue Übersetzungsdateien pushen, sollten Entwickler achtgeben,
dass jene Dateien eingetragen sind, damit die Make-Maschinerie die
Übersetzungen auch tatsächlich bereitstellt. Der Prozess dafür unterscheidet
sich je nach Komponente.

@itemize
@item Neue PO-Dateien für die Komponenten @code{guix} und @code{packages}
      müssen registriert werden, indem man die neue Sprache in
@file{po/guix/LINGUAS} oder @file{po/packages/LINGUAS} hinzufügt.
@item Neue PO-Dateien für die Komponente @code{documentation-manual} müssen
      registriert werden, indem man deren Dateinamen zu @code{DOC_PO_FILES} in
@file{po/doc/local.mk} hinzufügt, die erzeugte Handbuchdatei
@file{%D%/guix.xx.texi} zu @code{info_TEXINFOS} in @file{doc/local.mk}
hinzufügt und sowohl die erzeugte @file{%D%/guix.xx.texi} als auch
@file{%D%/contributing.xx.texi} zu @code{TRANSLATED_INFO} auch wieder in
@file{doc/local.mk} hinzufügt.
@item Neue PO-Dateien für die Komponente @code{documentation-cookbook} müssen
      registriert werden, indem man deren Dateinamen zu
@code{DOC_COOKBOOK_PO_FILES} in @file{po/doc/local.mk} hinzufügt, die
erzeugte Handbuchdatei @file{%D%/guix-cookbook.xx.texi} zu
@code{info_TEXINFOS} in @file{doc/local.mk} hinzufügt und die erzeugte
@file{%D%/guix-cookbook.xx.texi} zu @code{TRANSLATED_INFO} auch wieder in
@file{doc/local.mk} hinzufügt.
@item Neue PO-Dateien für die Komponente @code{website} müssen zum Repository
      @code{guix-artwork} ins dortige Verzeichnis @file{website/po/} hinzugefügt
werden. @file{website/po/LINGUAS} und @file{website/po/ietf-tags.scm} müssen
entsprechend aktualisiert werden (siehe @file{website/i18n-howto.txt} für
Details zum Prozess).
@end itemize