path: root/doc/contributing.de.texi

@node Mitwirken
@chapter Mitwirken

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

@cindex Verhaltensregeln, für Mitwirkende
@cindex Verhaltenskodex für Mitwirkende
Wir möchten eine angenehme, freundliche und von Belästigungen freie Umgebung
bereitstellen, so dass jeder Beiträge nach seinen Fähigkeiten leisten
kann. Zu diesem Zweck verwendet unser Projekt einen »Verhaltenskodex für
Mitwirkende«, der von @url{http://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.
* Code-Stil::                Wie Mitwirkende hygienisch arbeiten.
* Einreichen von Patches::   Teilen Sie Ihre Arbeit.
@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

Wenn Sie Guix aus einem Checkout erstellen, sind außer den bereits in den
Installationsanweisungen genannten Paketen weitere nötig (siehe
@ref{Voraussetzungen}).

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

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

@example
guix environment guix
@end example

In @ref{Aufruf von guix environment} finden Sie weitere Informationen zu
diesem Befehl. Zusätzliche Abhängigkeiten können mit @option{--ad-hoc}
hinzugefügt werden:

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

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

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

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

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

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

Dann führen Sie wie gewohnt @command{./configure} aus. Achten Sie darauf,
@code{--localstatedir=@var{Verzeichnis}} zu übergeben, wobei
@var{Verzeichnis} der von Ihrer aktuellen Installation verwendete
@code{localstatedir}-Wert ist (weitere Informationen siehe @ref{Der Store}).

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


@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, wo
es durch @command{./configure} erzeugt wird), zum Beispiel so@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
$ ./pre-inst-env guix build hello
@end example

@noindent
Entsprechend, 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
@dots{} und auf einer REPL (siehe @ref{Using Guile Interactively,,, guile,
Guile Reference Manual}):

@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

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

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


@node Perfekt eingerichtet
@section Perfekt eingerichtet

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

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

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

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

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

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

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

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

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


@node Paketrichtlinien
@section Paketrichtlinien

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

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

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

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

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

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

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

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

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

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


@menu
* Software-Freiheit::        Was in die Distribution aufgenommen werden 
                               darf.
* Paketbenennung::           Was macht einen Namen aus?
* Versionsnummern::          Wenn der Name noch nicht genug ist.
* Zusammenfassungen und Beschreibungen::  Den Nutzern helfen, das richtige 
                                            Paket zu finden.
* Python-Module::            Ein Touch britischer Comedy.
* Perl-Module::              Kleine Perlen.
* Java-Pakete::              Kaffeepause.
* Schriftarten::             Schriften verschriftlicht.
@end menu

@node Software-Freiheit
@subsection Software-Freiheit

@c ===========================================================================
@c
@c This file was generated with po4a. Translate the source file.
@c
@c ===========================================================================
@c Adapted from http://www.gnu.org/philosophy/philosophy.html.
@cindex freie Software
Das GNU-Betriebssystem wurde entwickelt, um Menschen Freiheit bei der
Nutzung ihrer Rechengeräte zu ermöglichen. GNU ist @dfn{freie Software}, was
bedeutet, dass Benutzer die
@url{http://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{http://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}.

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:

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

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

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

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

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

@example
(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@dots{}"))
                (file-name (git-file-name name version))))
      ;; @dots{}
      )))
@end example

@node Zusammenfassungen und Beschreibungen
@subsection Zusammenfassungen und Beschreibungen

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

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

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

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

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

Zusammenfassungen und Beschreibungen werden von Freiwilligen
@uref{http://translationproject.org/domain/guix-packages.html, beim
Translation Project} ü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
  ;; @dots{}
  (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}):

@example
;; 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. @dots{}")
@end example


@node Python-Module
@subsection Python-Module

@cindex python
Zur Zeit 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 nur mit Python 3 kompiliert werden kann, geben
wir ihm den Namen @code{python-foo}, wenn es nur mit Python 2 kompilierbar
ist, wählen wir den Namen @code{python2-foo}. Ist es mit beiden Versionen
kompatibel, erstellen wir zwei Pakete jeweils mit dem entsprechenden Namen.

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

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

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

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

@itemize

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

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

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

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

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

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

@end itemize


@node Perl-Module
@subsection Perl-Module

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


@node Java-Pakete
@subsection Java-Pakete

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

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

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


@node 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 Code-Stil
@section Code-Stil

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 @dots{})} 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 @dots{})} und nicht in @code{(guix @dots{})} stehen.

@node Datentypen und Mustervergleich
@subsection Datentypen und Mustervergleich

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

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

@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{http://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, The Emacs-Guix Reference
Manual}).

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

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

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

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

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

Wir fordern von allen Prozeduren auf oberster Ebene, dass sie über einen
Docstring verfügen. Diese Voraussetzung kann jedoch bei einfachen, privaten
Prozeduren im Namensraum @code{(guix build @dots{})} 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.

Diese Mailing-Liste setzt auf einer Debbugs-Instanz auf, die zugänglich ist
unter @uref{https://bugs.gnu.org/guix-patches}, wodurch wir den Überblick
über Eingereichtes behalten können. Jede an diese Mailing-Liste gesendete
Nachricht bekommt eine neue Folgenummer zugewiesen, so dass man eine
Folge-Email zur Einreichung an @code{@var{NNN}@@debbugs.gnu.org} senden
kann, wobei @var{NNN} für die Folgenummer steht (siehe @ref{Senden einer Patch-Reihe}).

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

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

@enumerate
@item
Wenn die Autoren der verpackten Software eine kryptografische Signatur
bzw. Beglaubigung für den Tarball der Veröffentlichung anbieten, so machen
Sie sich bitte die Mühe, die Echtheit des Archivs zu überprüfen. Für eine
abgetrennte GPG-Signaturdatei würden Sie das mit dem Befehl @code{gpg
--verify} tun.

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

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

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

@item
Wir empfehlen, dass Sie auch versuchen, das Paket auf anderen unterstützten
Plattformen zu erstellen. Da Sie vielleicht keinen Zugang zu echter Hardware
für diese Plattformen haben, empfehlen wir, den
@code{qemu-binfmt-service-type} zu benutzen, um sie zu emulieren. Um ihn zu
aktivieren, fügen Sie den folgenden Dienst in die Liste der Dienste
(»services«) in Ihrer @code{operating-system}-Konfiguration ein:

@example
(service qemu-binfmt-service-type
 (qemu-binfmt-configuration
   (platforms (lookup-qemu-platforms "arm" "aarch64" "mips64el"))
   (guix-support? #t)))
@end example

Rekonfigurieren Sie anschließend Ihr System.

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

@item
@cindex gebündelt
Achten Sie darauf, dass im Paket keine Software gebündelt mitgeliefert wird,
die bereits in separaten Paketen zur Verfügung steht.

Manchmal enthalten Pakete Kopien des Quellcodes ihrer Abhängigkeiten, um
Nutzern die Installation zu erleichtern. Als eine Distribution wollen wir
jedoch sicherstellen, dass solche Pakete die schon in der Distribution
verfügbare Fassung benutzen, sofern es eine gibt. Dadurch wird sowohl der
Ressourcenverbrauch optimiert (die Abhängigkeit wird so nur einmal erstellt
und gespeichert) als auch der Distribution die Möglichkeit gegeben,
ergänzende Änderungen durchzuführen, um beispielsweise
Sicherheitsaktualisierungen für ein bestimmtes Paket an nur einem Ort
einzuspielen, die aber das gesamte System betreffen — gebündelt
mitgelieferte Kopien würden dies verhindern.

@item
Schauen Sie sich das von @command{guix size} ausgegebene Profil an (siehe
@ref{Aufruf von guix size}). Dadurch können Sie Referenzen auf andere Pakete
finden, die ungewollt vorhanden sind. Dies kann auch dabei helfen, zu
entscheiden, ob das Paket aufgespalten werden sollte (siehe @ref{Pakete mit mehreren Ausgaben.}) und welche optionalen Abhängigkeiten verwendet
werden sollten. Dabei sollten Sie es wegen seiner enormen Größe insbesondere
vermeiden, @code{texlive} als eine Abhängigkeit hinzuzufügen; benutzen Sie
stattdessen @code{texlive-tiny} oder @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, wieviele abhängige Pakete es gibt, und entsprechend wieviele
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 1200 abhängige Pakete
@code{staging}-Branch (störfreie Änderungen). Dieser Branch wird circa alle
3 Wochen mit @code{master} zusammengeführt. Themenbezogene Änderungen
(z.B.@: eine Aktualisierung der GNOME-Plattform) können stattdessen auch auf
einem eigenen Branch umgesetzt werden (wie @code{gnome-updates}).

@item mehr als 1200 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 2,5 Monate oder so gemerget.
@end table

All diese Branches werden kontinuierlich
@uref{https://hydra.gnu.org/project/gnu, auf unserer Build-Farm} 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.
Im Allgemeinen werden Branches außer @code{master} als @emph{unveränderlich}
angesehen, wenn sie kürzlich ausgewertet wurden oder ein entsprechender
@code{-next}-Branch existiert. Bitte fragen Sie auf der Mailing-Liste oder
IRC, wenn Sie sich nicht sicher sind, wo ein Patch eingespielt werden
sollte.

@item
@cindex Determinismus, von Erstellungsprozessen
@cindex Reproduzierbare Erstellungen, Überprüfung
Überprüfen Sie, ob der Erstellungsprozess deterministisch ist. Dazu prüfen
Sie typischerweise, ob eine unabhängige Erstellung des Pakets genau dasselbe
Ergebnis wie Ihre Erstellung hat, Bit für Bit.

Dies können Sie leicht tun, indem Sie dasselbe Paket mehrere Male
hintereinander auf Ihrer Maschine erstellen (siehe @ref{Aufruf von guix build}):

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

Dies reicht aus, um eine ganze Klasse häufiger Ursachen von
Nichtdeterminismus zu finden, wie zum Beispiel Zeitstempel oder
zufallsgenerierte Ausgaben im Ergebnis der Erstellung.

Eine weitere Möglichkeit ist, @command{guix challenge} (siehe @ref{Aufruf von guix challenge}) zu benutzen. Sie können es ausführen, sobald ein Paket
commitet und von @code{@value{SUBSTITUTE-SERVER}} erstellt wurde, um zu
sehen, ob dort dasselbe Ergebnis wie bei Ihnen geliefert wurde. Noch besser:
Finden Sie eine andere Maschine, die das Paket erstellen kann, und führen
Sie @command{guix publish} aus. Da sich die entfernte Erstellungsmaschine
wahrscheinlich von Ihrer unterscheidet, können Sie auf diese Weise Probleme
durch Nichtdeterminismus erkennen, die mit der Hardware zu tun haben — zum
Beispiel die Nutzung anderer Befehlssatzerweiterungen — oder mit dem
Betriebssystem-Kernel — zum Beispiel, indem @code{uname} oder
@file{/proc}-Dateien verwendet werden.

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

@item
Stelllen Sie sicher, dass Ihr Patch nur einen Satz zusammengehöriger
Änderungen umfasst. Das Zusammenfassen nicht zusammengehöriger Änderungen
erschwert und bremst das Durchsehen Ihres Patches.

Beispiele für nicht zusammengehörige Änderungen sind das Hinzufügen mehrerer
Pakete auf einmal, oder das Aktualisieren eines Pakets auf eine neue Version
zusammen mit Fehlerbehebungen für das Paket.

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

@item
Benutzen Sie, wenn möglich, Spiegelserver (Mirrors) in der Quell-URL (siehe
@ref{Aufruf von guix download}). Verwenden Sie verlässliche URLs, keine
automatisch generierten. Zum Beispiel sind Archive von GitHub nicht immer
identisch von einer Generation auf die nächste, daher ist es in diesem Fall
besser, als Quelle einen Klon des Repositorys zu verwenden. Benutzen Sie
@emph{nicht} das @command{name}-Feld beim Angeben der URL; er hilft nicht
wirklich und wenn sich der Name ändert, stimmt die URL nicht mehr.

@end enumerate

Bitte benutzen Sie @samp{[PATCH] @dots{}} als Betreff, wenn Sie einen Patch
an die Mailing-Liste schicken. Sie können dazu Ihr E-Mail-Programm oder den
Befehl @command{git send-email} benutzen (siehe @ref{Senden einer Patch-Reihe}). Wir bevorzugen es, Patches als reine Textnachrichten zu erhalten,
entweder eingebettet (inline) oder als MIME-Anhänge. Sie sind dazu
angehalten, zu überprüfen, ob Ihr Mail-Programm solche Dinge wie
Zeilenumbrüche oder die Einrückung verändert, wodurch die Patches womöglich
nicht mehr funktionieren.

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

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

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