Mitwirken
*********

Dieses Projekt basiert auf Kooperation, daher benötigen wir Ihre Hilfe, um es wachsen zu lassen! Bitte kontaktieren Sie uns auf guix-devel@gnu.org und #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 Paketrichtlinien).

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 http://contributor-covenant.org/ übernommen wurde. Eine übersetzte Fassung finden Sie auf https://www.contributor-covenant.org/de/version/1/4/code-of-conduct sowie eine mitgelieferte, englische Fassung in der Datei 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.

Erstellung aus dem Git
======================

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

     git clone https://git.savannah.gnu.org/git/guix.git

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

  * GNU Autoconf (http://gnu.org/software/autoconf/);

  * GNU Automake (http://gnu.org/software/automake/);

  * GNU Gettext (http://gnu.org/software/gettext/);

  * GNU Texinfo (http://gnu.org/software/texinfo/);

  * Graphviz (http://www.graphviz.org/);

  * GNU Help2man (optional) (http://www.gnu.org/software/help2man/).

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:

     guix environment guix

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

     guix environment guix --ad-hoc help2man git strace

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

     configure.ac:46: error: possibly undefined macro: PKG_CHECK_MODULES

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

     export ACLOCAL_PATH=/usr/share/aclocal

In Macro Search Path (The GNU Automake Manual) finden Sie weitere Informationen.

Dann führen Sie wie gewohnt ./configure aus. Achten Sie darauf, --localstatedir=VERZEICHNIS zu übergeben, wobei VERZEICHNIS der von Ihrer aktuellen Installation verwendete localstatedir-Wert ist (weitere Informationen siehe Der Store).

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

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 make install laufen lassen.  Dazu müssen Sie sich in einer Umgebung befinden, in der alle Abhängigkeiten von Guix verfügbar sind (siehe Erstellung aus dem Git) und darin einfach vor jeden Befehl ./pre-inst-env schreiben (das Skript pre-inst-env befindet sich auf oberster Ebene im Verzeichnis, wo Guix erstellt wird, wo es durch ./configure erzeugt wird), zum Beispiel so (Die Befehlszeilenoption -E von sudo stellt sicher, dass GUILE_LOAD_PATH richtig gesetzt wird, damit guix-daemon und die davon benutzten Werkzeuge die von ihnen benötigten Guile-Module finden können.):

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

Entsprechend, um eine Guile-Sitzung zu öffnen, die die Guix-Module benutzt:

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

     ;;; ("x86_64-linux")

... und auf einer REPL (siehe Using Guile Interactively (Guile Reference Manual)):

     $ ./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

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

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

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 Using Guile in Emacs (Guile Reference Manual)). Zunächst brauchen Sie mehr als ein Textverarbeitungsprogramm, Sie brauchen Emacs (http://www.gnu.org/software/emacs) zusammen mit den vom wunderbaren Geiser (http://nongnu.org/geiser/) verliehenen Kräften. Um diese zu installieren, können Sie Folgendes ausführen:

     guix package -i emacs guile emacs-geiser

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, M-. um zu einer Objektdefinition zu springen, eine REPL, um Ihren Code auszuprobieren, und mehr (siehe Einführung (Geiser User Manual)). Zur bequemen Guix-Entwicklung sollten Sie Guiles Ladepfad so ergänzen, dass die Quelldateien in Ihrem Checkout gefunden werden.

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

Um den Code tatsächlich zu bearbeiten, bietet Emacs schon einen netten Scheme-Modus. Aber Sie dürfen auch Paredit (http://www.emacswiki.org/emacs/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.

Wir bieten auch Vorlagen für häufige Git-Commit-Nachrichten und Paketdefinitionen im Verzeichnis etc/snippets. Diese Vorlagen können mit YASnippet (http://joaotavora.github.io/yasnippet/) zusammen benutzt werden, um kurze Auslöse-Zeichenketten zu interaktiven Textschnipseln umzuschreiben. Vielleicht möchten Sie das Schnipselverzeichnis zu Ihrer YAS-SNIPPET-DIRS-Variablen in Emacs hinzufügen.

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

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

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

Paketrichtlinien
================

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 Tarballs mit dem Quellcode angeboten — typischerweise in 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 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 Paketmetadaten zum Rezept hinzu, wie zum Beispiel eine Beschreibung und Lizenzinformationen.

In Guix sind all diese Informationen ein Teil der 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 Paketmodule). Allerdings ist kein tiefgehendes Wissen über Scheme erforderlich, um Pakete zu erstellen. Mehr Informationen über Paketdefinitionen finden Sie im Abschnitt Pakete definieren.

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

     ./pre-inst-env guix build gnew --keep-failed

Wenn Sie --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 --log-file, womit das Erstellungsprotokoll eingesehen werden kann.

Wenn der guix-Befehl das Paket nicht erkennt, kann es daran liegen, dass die Quelldatei einen Syntaxfehler hat oder ihr eine 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:

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

Sobald Ihr Paket erfolgreich erstellt werden kann, schicken Sie uns bitte einen Patch (siehe 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 unser System zur Kontinuierlichen Integration (http://hydra.gnu.org/jobset/gnu/master) auf allen unterstützten Plattformen erstellt.

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

Software-Freiheit
-----------------

Das GNU-Betriebssystem wurde entwickelt, um Menschen Freiheit bei der Nutzung ihrer Rechengeräte zu ermöglichen. GNU ist freie Software, was bedeutet, dass Benutzer die vier wesentlichen Freiheiten (http://www.gnu.org/philosophy/free-sw.de.html) 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 Richtlinien für freie Systemverteilungen (http://www.gnu.org/distros/free-system-distribution-guidelines.de.html). 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 origin-Form des Pakets entfernt (siehe Pakete definieren). Dadurch liefert Ihnen guix build --source nur den »befreiten« Quellcode und nicht den unmodifizierten Quellcode des Anbieters.

Paketbenennung
--------------

Tatsächlich sind mit jedem Paket zwei Namen assoziiert: Zum einen gibt es den Namen der Scheme-Variablen, der direkt nach 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 name-Feld einer Paketdefinition. Dieser Name wird von Paketverwaltungsbefehlen wie guix package und 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 gnunet angeboten und SDL_net als sdl-net.

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

Auch Pakete mit Schriftarten werden anders behandelt, siehe Schriftarten.

Versionsnummern
---------------

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 Paketbenennung festgelegt wird, und geben vorherigen Versionen denselben Namen mit einem zusätzlichen Suffix aus - 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:

     (define-public gtk+
       (package
         (name "gtk+")
         (version "3.9.12")
         ...))
     (define-public gtk+-2
       (package
         (name "gtk+")
         (version "2.24.20")
         ...))

Wenn wir auch GTK 3.8.2 wollten, würden wir das Paket schreiben als

     (define-public gtk+-3.8
       (package
         (name "gtk+")
         (version "3.8.2")
         ...))

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 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 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:

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

Es ist eine gute Idee, die Commit-Bezeichner im 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 origins, um Mehrdeutigkeiten zu vermeiden. Eine typische Paketdefinition könnte so aussehen:

     (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))))
           ;; ...
           )))

Zusammenfassungen und Beschreibungen
------------------------------------

Wie wir bereits gesehen haben, enthält jedes Paket in GNU Guix eine (im Code englischsprachige) Zusammenfassung (englisch: Synopsis) und eine Beschreibung (englisch: Description; siehe Pakete definieren). Zusammenfassungen und Beschreibungen sind wichtig: Sie werden mit 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 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.

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

Zusammenfassungen und Beschreibungen werden von Freiwilligen beim Translation Project (http://translationproject.org/domain/guix-packages.html) ü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 xgettext sie als übersetzbare Zeichenketten extrahieren kann, müssen Zusammenfassungen und Beschreibungen einfache Zeichenketten-Literale sein. Das bedeutet, dass Sie diese Zeichenketten nicht mit Prozeduren wie string-append oder format konstruieren können:

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

Ü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 xgettext Invocation (GNU Gettext)):

     ;; 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. ...")

Python-Module
-------------

Zur Zeit stellen wir ein Paket für Python 2 und eines für Python 3 jeweils über die Scheme-Variablen mit den Namen python-2 und python zur Verfügung, entsprechend der Erklärungen im Abschnitt 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 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 python-foo, wenn es nur mit Python 2 kompilierbar ist, wählen wir den Namen python2-foo. Ist es mit beiden Versionen kompatibel, erstellen wir zwei Pakete jeweils mit dem entsprechenden Namen.

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

Abhängigkeiten angeben
......................

Informationen über Abhängigkeiten von Python-Paketen, welche mal mehr und mal weniger stimmen, finden sich normalerweise im Verzeichnisbaum des Paketquellcodes: in der Datei setup.py, in requirements.txt oder in 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 inputs). Obwohl der pypi-Importer hier normalerweise eine gute Arbeit leistet (siehe Aufruf von guix import), könnten Sie die folgende Prüfliste durchgehen wollen, um zu bestimmen, wo welche Abhängigkeit eingeordnet werden sollte.

  * Derzeit ist unser Python-2-Paket so geschrieben, dass es setuptools und 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 guix lint Sie darauf mit einer Warnung aufmerksam machen.

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

  * Python-Pakete, die nur zur Erstellungszeit gebraucht werden — z.B. jene, die mit dem Schlüsselwort setup_requires in setup.py aufgeführt sind — oder die nur zum Testen gebraucht werden — also die in tests_require —, stehen in 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 pytest, mock und nose. Wenn natürlich irgendeines dieser Pakete auch zur Laufzeit benötigt wird, muss es doch in propagated-inputs stehen.

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

  * Wenn ein Python-Paket optionale Abhängigkeiten hat (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 guix size).

Perl-Module
-----------

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 :: durch Striche und hängen davor das Präfix perl- an. Die Klasse XML::Parser wird also zu 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 perl- angehängt. Es gibt die Tendenz, solche Module mit dem Wort perl irgendwo im Namen zu versehen, das wird zu Gunsten des Präfixes weggelassen. Zum Beispiel wird aus libwww-perl bei uns perl-libwww.

Java-Pakete
-----------

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 java- vorangestellt wird. Wenn ein Projekt bereits das Wort java im Namen trägt, lassen wir es weg; zum Beispiel befindet sich das Java-Paket ngsjava in einem Paket namens 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 . durch Striche und setzen das Präfix java- davor. Die Klasse apache.commons.cli wird also zum Paket java-apache-commons-cli.

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 font-. Darauf folgt der Name des Schriftenherstellers und ein Strich -, 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 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 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 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 -ttf für TrueType-Schriftarten, -otf für OpenType-Schriftarten und -type1 für PostScript-Typ-1-Schriftarten.

Code-Stil
=========

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

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

Module
------

Guile-Module, die beim Erstellen nutzbar sein sollen, müssen im Namensraum (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 (gnu ...) und nicht in (guix ...) stehen.

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 car, cdr, 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 define-record-type*) statt Listen zu missbrauchen. Außerdem sollte er das (ice-9 match)-Modul von Guile zum Mustervergleich benutzen, besonders mit Listen.

Formatierung von Code
---------------------

Beim Schreiben von Scheme-Code halten wir uns an die üblichen Gepflogenheiten unter Scheme-Programmierern. Im Allgemeinen bedeutet das, dass wir uns an Riastradh's Lisp Style Rules (http://mumble.net/~campbell/scheme/style.txt) 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 substitute*-Makro, haben abweichende Regeln für die Einrückung. Diese sind in der Datei .dir-locals.el definiert, die Emacs automatisch benutzt. Beachten Sie auch, dass Emacs-Guix einen Modus namens guix-devel-mode bereitstellt, der Guix-Code richtig einrückt und hervorhebt (siehe Entwicklung (The Emacs-Guix Reference Manual)).

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:

     ./etc/indent-code.el gnu/packages/DATEI.scm PAKET

Dadurch wird die Definition von PAKET in gnu/packages/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:

     ./etc/indent-code.el gnu/services/DATEI.scm

Wenn Sie Code mit Vim bearbeiten, empfehlen wir, dass Sie :set autoindent ausführen, damit Ihr Code automatisch eingerückt wird, während Sie ihn schreiben. Außerdem könnte Ihnen paredit.vim (https://www.vim.org/scripts/script.php?script_id=3998) 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 (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.

Einreichen von Patches
======================

Die Entwicklung wird mit Hilfe des verteilten Versionskontrollsystems Git durchgeführt. Daher ist eine ständige Verbindung zum Repository nicht unbedingt erforderlich. Wir begrüßen Beiträge in Form von Patches, die mittels git format-patch erstellt und an die Mailingliste guix-patches@gnu.org geschickt werden.

Diese Mailing-Liste setzt auf einer Debbugs-Instanz auf, die zugänglich ist unter 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 NNN@debbugs.gnu.org senden kann, wobei NNN für die Folgenummer steht (siehe Senden einer Patch-Reihe).

Bitte schreiben Sie Commit-Logs im ChangeLog-Format (siehe Change Logs (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:

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

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

 3. Verwenden Sie guix lint PAKET, wobei PAKET das neue oder geänderte Paket bezeichnet, und beheben Sie alle gemeldeten Fehler (siehe Aufruf von guix lint).

 4. Stellen Sie sicher, dass das Paket auf Ihrer Plattform erstellt werden kann, indem Sie guix build PAKET ausführen.

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

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

     Rekonfigurieren Sie anschließend Ihr System.

     Sie können Pakete für andere Plattformen erstellen lassen, indem Sie die Befehlszeilenoption --system angeben. Um zum Beispiel das Paket »hello« für die Architekturen armhf, aarch64 oder mips64 erstellen zu lassen, würden Sie jeweils die folgenden Befehle angeben:

          guix build --system=armhf-linux --rounds=2 hello
          guix build --system=aarch64-linux --rounds=2 hello
          guix build --system=mips64el-linux --rounds=2 hello

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

 7. Schauen Sie sich das von guix size ausgegebene Profil an (siehe Aufruf von guix size). Dadurch können Sie Referenzen auf andere Pakete finden, die ungewollt vorhanden sind. Dies kann auch dabei helfen, zu entscheiden, ob das Paket aufgespalten werden sollte (siehe Pakete mit mehreren Ausgaben.) und welche optionalen Abhängigkeiten verwendet werden sollten. Dabei sollten Sie es wegen seiner enormen Größe insbesondere vermeiden, texlive als eine Abhängigkeit hinzuzufügen; benutzen Sie stattdessen texlive-tiny oder texlive-union.

 8. Achten Sie bei wichtigen Änderungen darauf, dass abhängige Pakete (falls vorhanden) nicht von der Änderung beeinträchtigt werden; guix refresh --list-dependent PAKET hilft Ihnen dabei (siehe Aufruf von guix refresh).

     Je nachdem, 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:

     300 abhängige Pakete oder weniger
          master-Branch (störfreie Änderungen).

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

     mehr als 1200 abhängige Pakete
          core-updates-Branch (kann auch größere und womöglich andere Software beeinträchtigende Änderungen umfassen). Dieser Branch wird planmäßig in master alle 2,5 Monate oder so gemerget.

     All diese Branches werden kontinuierlich auf unserer Build-Farm (https://hydra.gnu.org/project/gnu) erstellt und in master gemerget, sobald alles erfolgreich erstellt worden ist. Dadurch können wir Probleme beheben, bevor sie bei Nutzern auftreten, und zudem das Zeitfenster, während dessen noch keine vorerstellten Binärdateien verfügbar sind, verkürzen.

     Im Allgemeinen werden Branches außer master als unveränderlich angesehen, wenn sie kürzlich ausgewertet wurden oder ein entsprechender -next-Branch existiert. Bitte fragen Sie auf der Mailing-Liste oder IRC, wenn Sie sich nicht sicher sind, wo ein Patch eingespielt werden sollte.

 9. Überprüfen Sie, ob der Erstellungsprozess deterministisch ist. Dazu prüfen Sie typischerweise, ob eine unabhängige Erstellung des Pakets genau dasselbe Ergebnis wie Ihre Erstellung hat, Bit für Bit.

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

          guix build --rounds=2 mein-paket

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

     Eine weitere Möglichkeit ist, guix challenge (siehe Aufruf von guix challenge) zu benutzen. Sie können es ausführen, sobald ein Paket commitet und von 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 guix publish aus. Da sich die entfernte Erstellungsmaschine wahrscheinlich von Ihrer unterscheidet, können Sie auf diese Weise Probleme durch Nichtdeterminismus erkennen, die mit der Hardware zu tun haben — zum Beispiel die Nutzung anderer Befehlssatzerweiterungen — oder mit dem Betriebssystem-Kernel — zum Beispiel, indem uname oder /proc-Dateien verwendet werden.

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

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

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

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

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

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

Senden einer Patch-Reihe
------------------------

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