diff options
Diffstat (limited to 'doc/contributing.de.texi')
| -rw-r--r-- | doc/contributing.de.texi | 1055 |
1 files changed, 0 insertions, 1055 deletions
diff --git a/doc/contributing.de.texi b/doc/contributing.de.texi deleted file mode 100644 index 6a999baece..0000000000 --- a/doc/contributing.de.texi +++ /dev/null @@ -1,1055 +0,0 @@ -@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. |