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 (see 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 (see 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 see 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 erstellen. 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 see 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 auf see Der Store).

Zum Schluss müssen Sie make check aufrufen, um die Tests auszuführen (see Die Testsuite laufen lassen). Falls etwas fehlschlägt, werfen Sie einen Blick auf die Installationsanweisungen (see 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 (see 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 (see 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 (see Aufruf von guix pull).  Um Ihren lokalen Quellbaum zu aktualisieren, müssen Sie stattdessen git pull benutzen.

Perfekt eingerichtet
====================

The Perfect Setup to hack on Guix is basically the perfect setup used for Guile hacking (see Using Guile in Emacs (Guile Reference Manual)).  First, you need more than an editor, you need Emacs (http://www.gnu.org/software/emacs), empowered by the wonderful Geiser (http://nongnu.org/geiser/).  To set that up, run:

     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 (see 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
================

The GNU distribution is nascent and may well lack some of your favorite packages.  This section describes how you can help make the distribution grow.

Free software packages are usually distributed in the form of source code tarballs---typically tar.gz files that contain all the source files.  Adding a package to the distribution means essentially two things: adding a recipe that describes how to build the package, including a list of other packages required to build it, and adding package metadata along with that recipe, such as a description and licensing information.

In Guix all this information is embodied in package definitions. Package definitions provide a high-level view of the package.  They are written using the syntax of the Scheme programming language; in fact, for each package we define a variable bound to the package definition, and export that variable from a module (see Paketmodule).  However, in-depth Scheme knowledge is not a prerequisite for creating packages.  For more information on package definitions, see Pakete definieren.

Once a package definition is in place, stored in a file in the Guix source tree, it can be tested using the guix build command (see Aufruf von guix build).  For example, assuming the new package is called gnew, you may run this command from the Guix build tree (see Guix vor der Installation ausführen):

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

Using --keep-failed makes it easier to debug build failures since it provides access to the failed build tree.  Another useful command-line option when debugging is --log-file, to access the build log.

If the package is unknown to the guix command, it may be that the source file contains a syntax error, or lacks a define-public clause to export the package variable.  To figure it out, you may load the module from Guile to get more information about the actual error:

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

Once your package builds correctly, please send us a patch (see Einreichen von Patches).  Well, if you need help, we will be happy to help you too.  Once the patch is committed in the Guix repository, the new package automatically gets built on the supported platforms by our continuous integration system (http://hydra.gnu.org/jobset/gnu/master).

Users can obtain the new package definition simply by running guix
pull (see Aufruf von guix pull).  When SUBSTITUTE-SERVER is done building the package, installing the package automatically downloads binaries from there (see Substitute).  The only place where human intervention is needed is to review and apply the patch.

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

The GNU operating system has been developed so that users can have freedom in their computing.  GNU is free software, meaning that users have the four essential freedoms (http://www.gnu.org/philosophy/free-sw.html): to run the program, to study and change the program in source code form, to redistribute exact copies, and to distribute modified versions.  Packages found in the GNU distribution provide only software that conveys these four freedoms.

In addition, the GNU distribution follow the free software distribution guidelines (http://www.gnu.org/distros/free-system-distribution-guidelines.html).  Among other things, these guidelines reject non-free firmware, recommendations of non-free software, and discuss ways to deal with trademarks and patents.

Some otherwise free upstream package sources contain a small and optional subset that violates the above guidelines, for instance because this subset is itself non-free code.  When that happens, the offending items are removed with appropriate patches or code snippets in the origin form of the package (see Pakete definieren).  This way, guix build --source returns the ``freed'' source rather than the unmodified upstream source.

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

A package has actually two names associated with it: First, there is the name of the Scheme variable, the one following define-public. By this name, the package can be made known in the Scheme code, for instance as input to another package.  Second, there is the string in the name field of a package definition.  This name is used by package management commands such as guix package and guix build.

Both are usually the same and correspond to the lowercase conversion of the project name chosen upstream, with underscores replaced with hyphens.  For instance, GNUnet is available as gnunet, and SDL_net as sdl-net.

We do not add lib prefixes for library packages, unless these are already part of the official project name.  But see Python-Module and Perl-Module for special rules concerning modules for the Python and Perl languages.

Font package names are handled differently, see Schriftarten.

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

We usually package only the latest version of a given free software project.  But sometimes, for instance for incompatible library versions, two (or more) versions of the same package are needed.  These require different Scheme variable names.  We use the name as defined in Paketbenennung for the most recent version; previous versions use the same name, suffixed by - and the smallest prefix of the version number that may distinguish the two versions.

The name inside the package definition is the same for all versions of a package and does not contain any version number.

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

Occasionally, we package snapshots of upstream's version control system (VCS) instead of formal releases.  This should remain exceptional, because it is up to upstream developers to clarify what the stable release is.  Yet, it is sometimes necessary.  So, what should we put in the version field?

Clearly, we need to make the commit identifier of the VCS snapshot visible in the version string, but we also need to make sure that the version string is monotonically increasing so that guix package --upgrade can determine which version is newer.  Since commit identifiers, notably with Git, are not monotonically increasing, we add a revision number that we increase each time we upgrade to a newer snapshot.  The resulting version string looks like this:

     2.0.11-3.cabba9e
       ^    ^    ^
       |    |    `-- upstream commit ID
       |    |
       |    `--- Guix package revision
       |
     latest upstream version

It is a good idea to strip commit identifiers in the version field to, say, 7 digits.  It avoids an aesthetic annoyance (assuming aesthetics have a role to play here) as well as problems related to OS limits such as the maximum shebang length (127 bytes for the Linux kernel.)  It is best to use the full commit identifiers in origins, though, to avoid ambiguities.  A typical package definition may look like this:

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

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

As we have seen before, each package in GNU Guix includes a synopsis and a description (see Pakete definieren).  Synopses and descriptions are important: They are what guix package --search searches, and a crucial piece of information to help users determine whether a given package suits their needs.  Consequently, packagers should pay attention to what goes into them.

Synopses must start with a capital letter and must not end with a period. They must not start with ``a'' or ``the'', which usually does not bring anything; for instance, prefer ``File-frobbing tool'' over ``A tool that frobs files''.  The synopsis should say what the package is---e.g., ``Core GNU utilities (file, text, shell)''---or what it is used for---e.g., the synopsis for GNU grep is ``Print lines matching a pattern''.

Keep in mind that the synopsis must be meaningful for a very wide audience. For example, ``Manipulate alignments in the SAM format'' might make sense for a seasoned bioinformatics researcher, but might be fairly unhelpful or even misleading to a non-specialized audience.  It is a good idea to come up with a synopsis that gives an idea of the application domain of the package.  In this example, this might give something like ``Manipulate nucleotide sequence alignments'', which hopefully gives the user a better idea of whether this is what they are looking for.

Descriptions should take between five and ten lines.  Use full sentences, and avoid using acronyms without first introducing them.  Please avoid marketing phrases such as ``world-leading'', ``industrial-strength'', and ``next-generation'', and avoid superlatives like ``the most advanced''---they are not helpful to users looking for a package and may even sound suspicious.  Instead, try to be factual, mentioning use cases and features.

Descriptions can include Texinfo markup, which is useful to introduce ornaments such as @code or @dfn, bullet lists, or hyperlinks (see Overview (GNU Texinfo)).  However you should be careful when using some characters for example @ and curly braces which are the basic special characters in Texinfo (see Special Characters (GNU Texinfo)).  User interfaces such as guix package --show take care of rendering it appropriately.

Synopses and descriptions are translated by volunteers at the Translation Project (http://translationproject.org/domain/guix-packages.html) so that as many users as possible can read them in their native language.  User interfaces search them and display them in the language specified by the current locale.

To allow xgettext to extract them as translatable strings, synopses and descriptions must be literal strings.  This means that you cannot use string-append or format to construct these strings:

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

Translation is a lot of work so, as a packager, please pay even more attention to your synopses and descriptions as every change may entail additional work for translators.  In order to help them, it is possible to make recommendations or instructions visible to them by inserting special comments like this (see 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
-------------

We currently package Python 2 and Python 3, under the Scheme variable names python-2 and python as explained in Versionsnummern.  To avoid confusion and naming clashes with other programming languages, it seems desirable that the name of a package for a Python module contains the word python.

Some modules are compatible with only one version of Python, others with both.  If the package Foo compiles only with Python 3, we name it python-foo; if it compiles only with Python 2, we name it python2-foo. If it is compatible with both versions, we create two packages with the corresponding names.

If a project already contains the word python, we drop this; for instance, the module python-dateutil is packaged under the names python-dateutil and python2-dateutil.  If the project name starts with py (e.g. pytz), we keep it and prefix it as described above.

Specifying Dependencies
.......................

Dependency information for Python packages is usually available in the package source tree, with varying degrees of accuracy: in the setup.py file, in requirements.txt, or in tox.ini.

Your mission, when writing a recipe for a Python package, is to map these dependencies to the appropriate type of ``input'' (see inputs).  Although the pypi importer normally does a good job (see Aufruf von guix import), you may want to check the following check list to determine which dependency goes where.

  * We currently package Python 2 with setuptools and pip installed like Python 3.4 has per default.  Thus you don't need to specify either of these as an input.  guix lint will warn you if you do.

  * Python dependencies required at run time go into propagated-inputs. They are typically defined with the install_requires keyword in setup.py, or in the requirements.txt file.

  * Python packages required only at build time---e.g., those listed with the setup_requires keyword in setup.py---or only for testing---e.g., those in tests_require---go into native-inputs.  The rationale is that (1) they do not need to be propagated because they are not needed at run time, and (2) in a cross-compilation context, it's the ``native'' input that we'd want.

     Examples are the pytest, mock, and nose test frameworks.  Of course if any of these packages is also required at run-time, it needs to go to propagated-inputs.

  * Anything that does not fall in the previous categories goes to inputs, for example programs or C libraries required for building Python packages containing C extensions.

  * If a Python package has optional dependencies (extras_require), it is up to you to decide whether to add them or not, based on their usefulness/overhead ratio (see guix size).

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

Perl programs standing for themselves are named as any other package, using the lowercase upstream name.  For Perl packages containing a single class, we use the lowercase class name, replace all occurrences of :: by dashes and prepend the prefix perl-.  So the class XML::Parser becomes perl-xml-parser.  Modules containing several classes keep their lowercase upstream name and are also prepended by perl-.  Such modules tend to have the word perl somewhere in their name, which gets dropped in favor of the prefix.  For instance, libwww-perl becomes perl-libwww.

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

Java programs standing for themselves are named as any other package, using the lowercase upstream name.

To avoid confusion and naming clashes with other programming languages, it is desirable that the name of a package for a Java package is prefixed with java-.  If a project already contains the word java, we drop this; for instance, the package ngsjava is packaged under the name java-ngs.

For Java packages containing a single class or a small class hierarchy, we use the lowercase class name, replace all occurrences of . by dashes and prepend the prefix java-.  So the class apache.commons.cli becomes package java-apache-commons-cli.

Schriftarten
------------

For fonts that are in general not installed by a user for typesetting purposes, or that are distributed as part of a larger software package, we rely on the general packaging rules for software; for instance, this applies to the fonts delivered as part of the X.Org system or fonts that are part of TeX Live.

To make it easier for a user to search for fonts, names for other packages containing only fonts are constructed as follows, independently of the upstream package name.

The name of a package containing only one font family starts with font-; it is followed by the foundry name and a dash - if the foundry is known, and the font family name, in which spaces are replaced by dashes (and as usual, all upper case letters are transformed to lower case).  For example, the Gentium font family by SIL is packaged under the name font-sil-gentium.

For a package containing several font families, the name of the collection is used in the place of the font family name.  For instance, the Liberation fonts consist of three families, Liberation Sans, Liberation Serif and Liberation Mono.  These could be packaged separately under the names font-liberation-sans and so on; but as they are distributed together under a common name, we prefer to package them together as font-liberation.

In the case where several formats of the same font family or font collection are packaged separately, a short form of the format, prepended by a dash, is added to the package name.  We use -ttf for TrueType fonts, -otf for OpenType fonts and -type1 for PostScript Type 1 fonts.

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

Im Allgemeinen folgt unser Code den GNU Coding Standards (see 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 (see Development (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 (see Senden einer Patch-Reihe).

Bitte schreiben Sie Commit-Logs im ChangeLog-Format (see 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 kryptographische Signatur 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 see 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 (see 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. We recommend you also try building the package on other supported platforms.  As you may not have access to actual hardware platforms, we recommend using the qemu-binfmt-service-type to emulate them.  In order to enable it, add the following service to the list of services in your operating-system configuration:

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

     Then reconfigure your system.

     You can then build packages for different platforms by specifying the --system option.  For example, to build the "hello" package for the armhf, aarch64, powerpc, or mips64 architectures, you would run the following commands, respectively:

          guix build --system=armhf-linux --rounds=2 hello
          guix build --system=aarch64-linux --rounds=2 hello
          guix build --system=powerpc-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. Take a look at the profile reported by guix size (see Aufruf von guix size).  This will allow you to notice references to other packages unwillingly retained.  It may also help determine whether to split the package (see Pakete mit mehreren Ausgaben.), and which optional dependencies should be used.  In particular, avoid adding texlive as a dependency: because of its extreme size, use texlive-tiny or texlive-union instead.

 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 (see 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 in master gemerget. 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 (see 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.

     Another option is to use guix challenge (see Aufruf von guix challenge).  You may run it once the package has been committed and built by SUBSTITUTE-SERVER to check whether it obtains the same result as you did.  Better yet: Find another machine that can build it and run guix publish.  Since the remote build machine is likely different from yours, this can catch non-determinism issues related to the hardware---e.g., use of different instruction set extensions---or to the operating system kernel---e.g., reliance on uname or /proc files.

 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 (see Formatierung von Code).

 13. Benutzen Sie, wenn möglich, Spiegelserver (Mirrors) in der Quell-URL (see 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 (see 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.