You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
 

1056 lines
48 KiB

  1. @node Mitwirken
  2. @chapter Mitwirken
  3. Dieses Projekt basiert auf Kooperation, daher benötigen wir Ihre Hilfe, um
  4. es wachsen zu lassen! Bitte kontaktieren Sie uns auf
  5. @email{guix-devel@@gnu.org} und @code{#guix} im Freenode-IRC-Netzwerk. Wir
  6. freuen uns auf Ihre Ideen, Fehlerberichte, Patches und alles, was hilfreich
  7. für das Projekt sein könnte. Besonders willkommen ist Hilfe bei der
  8. Erstellung von Paketen (siehe @ref{Paketrichtlinien}).
  9. @cindex Verhaltensregeln, für Mitwirkende
  10. @cindex Verhaltenskodex für Mitwirkende
  11. Wir möchten eine angenehme, freundliche und von Belästigungen freie Umgebung
  12. bereitstellen, so dass jeder Beiträge nach seinen Fähigkeiten leisten
  13. kann. Zu diesem Zweck verwendet unser Projekt einen »Verhaltenskodex für
  14. Mitwirkende«, der von @url{http://contributor-covenant.org/} übernommen
  15. wurde. Eine übersetzte Fassung finden Sie auf
  16. @url{https://www.contributor-covenant.org/de/version/1/4/code-of-conduct}
  17. sowie eine mitgelieferte, englische Fassung in der Datei
  18. @file{CODE-OF-CONDUCT} im Quellbaum.
  19. Von Mitwirkenden wird nicht erwartet, dass sie in Patches oder in der
  20. Online-Kommunikation ihre echten Namen preisgeben. Sie können einen
  21. beliebigen Namen oder ein Pseudonym ihrer Wahl verwenden.
  22. @menu
  23. * Erstellung aus dem Git:: Das Neueste und Beste.
  24. * Guix vor der Installation ausführen:: Hacker-Tricks.
  25. * Perfekt eingerichtet:: Die richtigen Werkzeuge.
  26. * Paketrichtlinien:: Die Distribution wachsen lassen.
  27. * Code-Stil:: Wie Mitwirkende hygienisch arbeiten.
  28. * Einreichen von Patches:: Teilen Sie Ihre Arbeit.
  29. @end menu
  30. @node Erstellung aus dem Git
  31. @section Erstellung aus dem Git
  32. Wenn Sie an Guix selbst hacken wollen, ist es empfehlenswert, dass Sie die
  33. neueste Version aus dem Git-Softwarebestand verwenden:
  34. @example
  35. git clone https://git.savannah.gnu.org/git/guix.git
  36. @end example
  37. Wenn Sie Guix aus einem Checkout erstellen, sind außer den bereits in den
  38. Installationsanweisungen genannten Paketen weitere nötig (siehe
  39. @ref{Voraussetzungen}).
  40. @itemize
  41. @item @url{http://gnu.org/software/autoconf/, GNU Autoconf};
  42. @item @url{http://gnu.org/software/automake/, GNU Automake};
  43. @item @url{http://gnu.org/software/gettext/, GNU Gettext};
  44. @item @url{http://gnu.org/software/texinfo/, GNU Texinfo};
  45. @item @url{http://www.graphviz.org/, Graphviz};
  46. @item @url{http://www.gnu.org/software/help2man/, GNU Help2man (optional)}.
  47. @end itemize
  48. Der einfachste Weg, eine Entwicklungsumgebung für Guix einzurichten, ist
  49. natürlich, Guix zu benutzen! Der folgende Befehl startet eine neue Shell, in
  50. der alle Abhängigkeiten und Umgebungsvariablen bereits eingerichtet sind, um
  51. an Guix zu arbeiten:
  52. @example
  53. guix environment guix
  54. @end example
  55. In @ref{Aufruf von guix environment} finden Sie weitere Informationen zu
  56. diesem Befehl. Zusätzliche Abhängigkeiten können mit @option{--ad-hoc}
  57. hinzugefügt werden:
  58. @example
  59. guix environment guix --ad-hoc help2man git strace
  60. @end example
  61. Führen Sie @command{./bootstrap} aus, um die Infrastruktur des
  62. Erstellungssystems mit Autoconf und Automake zu erzeugen. Möglicherweise
  63. erhalten Sie eine Fehlermeldung wie diese:
  64. @example
  65. configure.ac:46: error: possibly undefined macro: PKG_CHECK_MODULES
  66. @end example
  67. @noindent
  68. Das bedeutet wahrscheinlich, dass Autoconf @file{pkg.m4} nicht finden
  69. konnte, welches von pkg-config bereitgestellt wird. Stellen Sie sicher, dass
  70. @file{pkg.m4} verfügbar ist. Gleiches gilt für den von Guile
  71. bereitgestellten Makrosatz @file{guile.m4}. Wenn Sie beispielsweise Automake
  72. in @file{/usr/local} installiert haben, würde in @file{/usr/share} nicht
  73. nach @file{.m4}-Dateien geschaut. In einem solchen Fall müssen Sie folgenden
  74. Befehl aufrufen:
  75. @example
  76. export ACLOCAL_PATH=/usr/share/aclocal
  77. @end example
  78. In @ref{Macro Search Path,,, automake, The GNU Automake Manual} finden Sie
  79. weitere Informationen.
  80. Dann führen Sie wie gewohnt @command{./configure} aus. Achten Sie darauf,
  81. @code{--localstatedir=@var{Verzeichnis}} zu übergeben, wobei
  82. @var{Verzeichnis} der von Ihrer aktuellen Installation verwendete
  83. @code{localstatedir}-Wert ist (weitere Informationen siehe @ref{Der Store}).
  84. Zum Schluss müssen Sie @code{make check} aufrufen, um die Tests auszuführen
  85. (siehe @ref{Den Testkatalog laufen lassen}). Falls etwas fehlschlägt, werfen Sie
  86. einen Blick auf die Installationsanweisungen (siehe @ref{Installation}) oder
  87. senden Sie eine E-Mail an die @email{guix-devel@@gnu.org, Mailingliste}.
  88. @node Guix vor der Installation ausführen
  89. @section Guix vor der Installation ausführen
  90. Um eine gesunde Arbeitsumgebung zu erhalten, ist es hilfreich, die im
  91. lokalen Quellbaum vorgenommenen Änderungen zunächst zu testen, ohne sie
  92. tatsächlich zu installieren. So können Sie zwischen Ihrem
  93. Endnutzer-»Straßenanzug« und Ihrem »Faschingskostüm« unterscheiden.
  94. Zu diesem Zweck können alle Befehlszeilenwerkzeuge auch schon benutzt
  95. werden, ohne dass Sie @code{make install} laufen lassen. Dazu müssen Sie
  96. sich in einer Umgebung befinden, in der alle Abhängigkeiten von Guix
  97. verfügbar sind (siehe @ref{Erstellung aus dem Git}) und darin einfach vor jeden
  98. Befehl @command{./pre-inst-env} schreiben (das Skript @file{pre-inst-env}
  99. befindet sich auf oberster Ebene im Verzeichnis, wo Guix erstellt wird, wo
  100. es durch @command{./configure} erzeugt wird), zum Beispiel so@footnote{Die
  101. Befehlszeilenoption @option{-E} von @command{sudo} stellt sicher, dass
  102. @code{GUILE_LOAD_PATH} richtig gesetzt wird, damit @command{guix-daemon} und
  103. die davon benutzten Werkzeuge die von ihnen benötigten Guile-Module finden
  104. können.}:
  105. @example
  106. $ sudo -E ./pre-inst-env guix-daemon --build-users-group=guixbuild
  107. $ ./pre-inst-env guix build hello
  108. @end example
  109. @noindent
  110. Entsprechend, um eine Guile-Sitzung zu öffnen, die die Guix-Module benutzt:
  111. @example
  112. $ ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))'
  113. ;;; ("x86_64-linux")
  114. @end example
  115. @noindent
  116. @cindex REPL
  117. @cindex Lese-Auswerten-Schreiben-Schleife
  118. @dots{} und auf einer REPL (siehe @ref{Using Guile Interactively,,, guile,
  119. Guile Reference Manual}):
  120. @example
  121. $ ./pre-inst-env guile
  122. scheme@@(guile-user)> ,use(guix)
  123. scheme@@(guile-user)> ,use(gnu)
  124. scheme@@(guile-user)> (define snakes
  125. (fold-packages
  126. (lambda (package lst)
  127. (if (string-prefix? "python"
  128. (package-name package))
  129. (cons package lst)
  130. lst))
  131. '()))
  132. scheme@@(guile-user)> (length snakes)
  133. $1 = 361
  134. @end example
  135. Das @command{pre-inst-env}-Skript richtet alle Umgebungsvariablen ein, die
  136. nötig sind, um dies zu ermöglichen, einschließlich @env{PATH} und
  137. @env{GUILE_LOAD_PATH}.
  138. Beachten Sie, dass @command{./pre-inst-env guix pull} den lokalen Quellbaum
  139. @emph{nicht} aktualisiert; es aktualisiert lediglich die symbolische
  140. Verknüpfung @file{~/.config/guix/current} (siehe @ref{Aufruf von guix pull}). Um Ihren lokalen Quellbaum zu aktualisieren, müssen Sie stattdessen
  141. @command{git pull} benutzen.
  142. @node Perfekt eingerichtet
  143. @section Perfekt eingerichtet
  144. Um perfekt für das Hacken an Guix eingerichtet zu sein, brauchen Sie an sich
  145. dasselbe wie um perfekt für das Hacken mit Guile (siehe @ref{Using Guile in
  146. Emacs,,, guile, Guile Reference Manual}). Zunächst brauchen Sie mehr als ein
  147. Textverarbeitungsprogramm, Sie brauchen
  148. @url{http://www.gnu.org/software/emacs, Emacs} zusammen mit den vom
  149. wunderbaren @url{http://nongnu.org/geiser/, Geiser} verliehenen Kräften. Um
  150. diese zu installieren, können Sie Folgendes ausführen:
  151. @example
  152. guix package -i emacs guile emacs-geiser
  153. @end example
  154. Geiser ermöglicht interaktive und inkrementelle Entwicklung aus Emacs
  155. heraus: Code kann in Puffern kompiliert und ausgewertet werden. Zugang zu
  156. Online-Dokumentation (Docstrings) steht ebenso zur Verfügung wie
  157. kontextabhängige Vervollständigung, @kbd{M-.} um zu einer Objektdefinition
  158. zu springen, eine REPL, um Ihren Code auszuprobieren, und mehr (siehe
  159. @ref{Einführung,,, geiser, Geiser User Manual}). Zur bequemen
  160. Guix-Entwicklung sollten Sie Guiles Ladepfad so ergänzen, dass die
  161. Quelldateien in Ihrem Checkout gefunden werden.
  162. @lisp
  163. ;; @r{Angenommen das Guix-Checkout ist in ~/src/guix.}
  164. (with-eval-after-load 'geiser-guile
  165. (add-to-list 'geiser-guile-load-path "~/src/guix"))
  166. @end lisp
  167. Um den Code tatsächlich zu bearbeiten, bietet Emacs schon einen netten
  168. Scheme-Modus. Aber Sie dürfen auch
  169. @url{http://www.emacswiki.org/emacs/ParEdit, Paredit} nicht verpassen. Es
  170. bietet Hilfsmittel, um direkt mit dem Syntaxbaum zu arbeiten, und kann so
  171. zum Beispiel einen S-Ausdruck hochheben oder ihn umhüllen, ihn verschlucken
  172. oder den nachfolgenden S-Ausdruck verwerfen, etc.
  173. @cindex Code-Schnipsel
  174. @cindex Vorlagen
  175. @cindex Tipparbeit sparen
  176. Wir bieten auch Vorlagen für häufige Git-Commit-Nachrichten und
  177. Paketdefinitionen im Verzeichnis @file{etc/snippets}. Diese Vorlagen können
  178. mit @url{http://joaotavora.github.io/yasnippet/, YASnippet} zusammen benutzt
  179. werden, um kurze Auslöse-Zeichenketten zu interaktiven Textschnipseln
  180. umzuschreiben. Vielleicht möchten Sie das Schnipselverzeichnis zu Ihrer
  181. @var{yas-snippet-dirs}-Variablen in Emacs hinzufügen.
  182. @lisp
  183. ;; @r{Angenommen das Guix-Checkout ist in ~/src/guix.}
  184. (with-eval-after-load 'yasnippet
  185. (add-to-list 'yas-snippet-dirs "~/src/guix/etc/snippets"))
  186. @end lisp
  187. Die Schnipsel für Commit-Nachrichten setzen @url{https://magit.vc/, Magit}
  188. voraus, um zum Commit vorgemerkte Dateien anzuzeigen. Wenn Sie eine
  189. Commit-Nachricht bearbeiten, können Sie @code{add} gefolgt von @kbd{TAB}
  190. eintippen, um eine Commit-Nachrichten-Vorlage für das Hinzufügen eines
  191. Pakets zu erhalten; tippen Sie @code{update} gefolgt von @kbd{TAB} ein, um
  192. eine Vorlage zum Aktualisieren eines Pakets zu bekommen; tippen Sie
  193. @code{https} gefolgt von @kbd{TAB} ein, um eine Vorlage zum Ändern der
  194. Homepage-URI eines Pakets auf HTTPS einzufügen.
  195. Das Hauptschnipsel für @code{scheme-mode} wird ausgelöst, indem Sie
  196. @code{package...} gefolgt von @kbd{TAB} eintippen. Dieses Snippet fügt auch
  197. die Auslöse-Zeichenkette @code{origin...} ein, die danach weiter
  198. umgeschrieben werden kann. Das @code{origin}-Schnipsel kann wiederum andere
  199. Auslöse-Zeichenketten einfügen, die alle auf @code{...} enden, was selbst
  200. wieder weiter umgeschrieben werden kann.
  201. @node Paketrichtlinien
  202. @section Paketrichtlinien
  203. @cindex Pakete definieren
  204. Die GNU-Distribution ist noch sehr jung und einige Ihrer Lieblingspakete
  205. könnten noch fehlen. Dieser Abschnitt beschreibt, wie Sie dabei helfen
  206. können, die Distribution wachsen zu lassen.
  207. Pakete mit freier Software werden normalerweise in Form von @dfn{Tarballs
  208. mit dem Quellcode} angeboten — typischerweise in
  209. @file{tar.gz}-Archivdateien, in denen alle Quelldateien enthalten sind. Ein
  210. Paket zur Distribution hinzuzufügen, bedeutet also zweierlei Dinge: Zum
  211. einen fügt man ein @dfn{Rezept} ein, das beschreibt, wie das Paket erstellt
  212. werden kann, einschließlich einer Liste von anderen Paketen, die für diese
  213. Erstellung gebraucht werden, zum anderen fügt man @dfn{Paketmetadaten} zum
  214. Rezept hinzu, wie zum Beispiel eine Beschreibung und Lizenzinformationen.
  215. In Guix sind all diese Informationen ein Teil der
  216. @dfn{Paketdefinitionen}. In Paketdefinitionen hat man eine abstrahierte,
  217. hochsprachliche Sicht auf das Paket. Sie werden in der Syntax der
  218. Scheme-Programmiersprache verfasst; tatsächlich definieren wir für jedes
  219. Paket eine Variable und binden diese an dessen Definition, um die Variable
  220. anschließend aus einem Modul heraus zu exportieren (siehe @ref{Paketmodule}). Allerdings ist @emph{kein} tiefgehendes Wissen über Scheme
  221. erforderlich, um Pakete zu erstellen. Mehr Informationen über
  222. Paketdefinitionen finden Sie im Abschnitt @ref{Pakete definieren}.
  223. Eine fertige Paketdefinition kann, nachdem sie in eine Datei im
  224. Quell-Verzeichnisbaum von Guix eingesetzt wurde, mit Hilfe des Befehls
  225. @command{guix build} getestet werden (siehe @ref{Aufruf von guix build}). Wenn
  226. das Paket zum Beispiel den Namen @code{gnew} trägt, können Sie folgenden
  227. Befehl aus dem Erstellungs-Verzeichnisbaum von Guix heraus ausführen (siehe
  228. @ref{Guix vor der Installation ausführen}):
  229. @example
  230. ./pre-inst-env guix build gnew --keep-failed
  231. @end example
  232. Wenn Sie @code{--keep-failed} benutzen, ist es leichter, fehlgeschlagene
  233. Erstellungen zu untersuchen, weil dann der Verzeichnisbaum der
  234. fehlgeschlagenen Erstellung zugänglich bleibt. Eine andere nützliche
  235. Befehlszeilenoption bei der Fehlersuche ist @code{--log-file}, womit das
  236. Erstellungsprotokoll eingesehen werden kann.
  237. Wenn der @command{guix}-Befehl das Paket nicht erkennt, kann es daran
  238. liegen, dass die Quelldatei einen Syntaxfehler hat oder ihr eine
  239. @code{define-public}-Klausel fehlt, die die Paketvariable exportiert. Um das
  240. herauszufinden, können Sie das Modul aus Guile heraus laden, um mehr
  241. Informationen über den tatsächlichen Fehler zu bekommen:
  242. @example
  243. ./pre-inst-env guile -c '(use-modules (gnu packages gnew))'
  244. @end example
  245. Sobald Ihr Paket erfolgreich erstellt werden kann, schicken Sie uns bitte
  246. einen Patch (siehe @ref{Einreichen von Patches}). Wenn Sie dabei Hilfe brauchen
  247. sollten, helfen wir gerne. Ab dem Zeitpunkt, zu dem der Patch als Commit ins
  248. Guix-Repository eingepflegt wurde, wird das neue Paket automatisch durch
  249. @url{http://hydra.gnu.org/jobset/gnu/master, unser System zur
  250. Kontinuierlichen Integration} auf allen unterstützten Plattformen erstellt.
  251. @cindex Substituierer
  252. Benutzern steht die neue Paketdefinition zur Verfügung, nachdem sie das
  253. 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
  254. Paket zu erstellen, werden bei der Installation automatisch Binärdateien von
  255. dort heruntergeladen (siehe @ref{Substitute}). Menschliches Eingreifen muss
  256. nur stattfinden, um den Patch zu überprüfen und anzuwenden.
  257. @menu
  258. * Software-Freiheit:: Was in die Distribution aufgenommen werden
  259. darf.
  260. * Paketbenennung:: Was macht einen Namen aus?
  261. * Versionsnummern:: Wenn der Name noch nicht genug ist.
  262. * Zusammenfassungen und Beschreibungen:: Den Nutzern helfen, das richtige
  263. Paket zu finden.
  264. * Python-Module:: Ein Touch britischer Comedy.
  265. * Perl-Module:: Kleine Perlen.
  266. * Java-Pakete:: Kaffeepause.
  267. * Schriftarten:: Schriften verschriftlicht.
  268. @end menu
  269. @node Software-Freiheit
  270. @subsection Software-Freiheit
  271. @c ===========================================================================
  272. @c
  273. @c This file was generated with po4a. Translate the source file.
  274. @c
  275. @c ===========================================================================
  276. @c Adapted from http://www.gnu.org/philosophy/philosophy.html.
  277. @cindex freie Software
  278. Das GNU-Betriebssystem wurde entwickelt, um Menschen Freiheit bei der
  279. Nutzung ihrer Rechengeräte zu ermöglichen. GNU ist @dfn{freie Software}, was
  280. bedeutet, dass Benutzer die
  281. @url{http://www.gnu.org/philosophy/free-sw.de.html,vier wesentlichen
  282. Freiheiten} haben: das Programm auszuführen, es zu untersuchen, das Programm
  283. in Form seines Quellcodes anzupassen und exakte Kopien ebenso wie
  284. modifizierte Versionen davon an andere weiterzugeben. Die Pakete, die Sie in
  285. der GNU-Distribution finden, stellen ausschließlich solche Software zur
  286. Verfügung, die Ihnen diese vier Freiheiten gewährt.
  287. Außerdem befolgt die GNU-Distribution die
  288. @url{http://www.gnu.org/distros/free-system-distribution-guidelines.de.html,Richtlinien
  289. für freie Systemverteilungen}. Unter anderem werden unfreie Firmware sowie
  290. Empfehlungen von unfreier Software abgelehnt und Möglichkeiten zum Umgang
  291. mit Markenzeichen und Patenten werden diskutiert.
  292. Ansonsten freier Paketquellcode von manchen Anbietern enthält einen kleinen
  293. und optionalen Teil, der diese Richtlinien verletzt. Zum Beispiel kann
  294. dieser Teil selbst unfreier Code sein. Wenn das vorkommt, wird der sie
  295. verletzende Teil mit angemessenen Patches oder Code-Schnipseln innerhalb der
  296. @code{origin}-Form des Pakets entfernt (siehe @ref{Pakete definieren}). Dadurch liefert Ihnen @code{guix build --source} nur den
  297. »befreiten« Quellcode und nicht den unmodifizierten Quellcode des Anbieters.
  298. @node Paketbenennung
  299. @subsection Paketbenennung
  300. @cindex Paketname
  301. Tatsächlich sind mit jedem Paket zwei Namen assoziiert: Zum einen gibt es
  302. den Namen der @emph{Scheme-Variablen}, der direkt nach @code{define-public}
  303. im Code steht. Mit diesem Namen kann das Paket im Scheme-Code nutzbar
  304. gemacht und zum Beispiel als Eingabe eines anderen Pakets benannt
  305. werden. Zum anderen gibt es die Zeichenkette im @code{name}-Feld einer
  306. Paketdefinition. Dieser Name wird von Paketverwaltungsbefehlen wie
  307. @command{guix package} und @command{guix build} benutzt.
  308. Meistens sind die beiden identisch und ergeben sich aus einer Umwandlung des
  309. vom Anbieter verwendeten Projektnamens in Kleinbuchstaben, bei der
  310. Unterstriche durch Bindestriche ersetzt werden. Zum Beispiel wird GNUnet
  311. unter dem Paketnamen @code{gnunet} angeboten und SDL_net als @code{sdl-net}.
  312. An Bibliothekspakete hängen wir vorne kein @code{lib} als Präfix an, solange
  313. es nicht Teil des offiziellen Projektnamens ist. Beachten Sie aber die
  314. Abschnitte @ref{Python-Module} und @ref{Perl-Module}, in denen
  315. Sonderregeln für Module der Programmiersprachen Python und Perl beschrieben
  316. sind.
  317. Auch Pakete mit Schriftarten werden anders behandelt, siehe @ref{Schriftarten}.
  318. @node Versionsnummern
  319. @subsection Versionsnummern
  320. @cindex Paketversion
  321. Normalerweise stellen wir nur für die neueste Version eines
  322. Freie-Software-Projekts ein Paket bereit. Manchmal gibt es allerdings Fälle
  323. wie zum Beispiel untereinander inkompatible Bibliotheksversionen, so dass
  324. zwei (oder mehr) Versionen desselben Pakets angeboten werden müssen. In
  325. diesem Fall müssen wir verschiedene Scheme-Variablennamen benutzen. Wir
  326. benutzen dann für die neueste Version den Namen, wie er im Abschnitt
  327. @ref{Paketbenennung} festgelegt wird, und geben vorherigen Versionen
  328. denselben Namen mit einem zusätzlichen Suffix aus @code{-} gefolgt vom
  329. kürzesten Präfix der Versionsnummer, mit dem noch immer zwei Versionen
  330. unterschieden werden können.
  331. Der Name innerhalb der Paketdefinition ist hingegen derselbe für alle
  332. Versionen eines Pakets und enthält keine Versionsnummer.
  333. Zum Beispiel können für GTK in den Versionen 2.24.20 und 3.9.12 Pakete wie
  334. folgt geschrieben werden:
  335. @example
  336. (define-public gtk+
  337. (package
  338. (name "gtk+")
  339. (version "3.9.12")
  340. ...))
  341. (define-public gtk+-2
  342. (package
  343. (name "gtk+")
  344. (version "2.24.20")
  345. ...))
  346. @end example
  347. Wenn wir auch GTK 3.8.2 wollten, würden wir das Paket schreiben als
  348. @example
  349. (define-public gtk+-3.8
  350. (package
  351. (name "gtk+")
  352. (version "3.8.2")
  353. ...))
  354. @end example
  355. @c See <https://lists.gnu.org/archive/html/guix-devel/2016-01/msg00425.html>,
  356. @c for a discussion of what follows.
  357. @cindex Versionsnummer, bei Snapshots aus Versionskontrolle
  358. Gelegentlich fügen wir auch Pakete für Snapshots aus dem
  359. Versionskontrollsystem des Anbieters statt formaler Veröffentlichungen zur
  360. Distribution hinzu. Das sollte die Ausnahme bleiben, weil die Entwickler
  361. selbst klarstellen sollten, welche Version als die stabile Veröffentlichung
  362. gelten sollte, ab und zu ist es jedoch notwendig. Was also sollten wir dann
  363. im @code{version}-Feld eintragen?
  364. Offensichtlich muss der Bezeichner des Commits, den wir als Snapshot aus dem
  365. Versionskontrollsystem nehmen, in der Versionszeichenkette zu erkennen sein,
  366. aber wir müssen auch sicherstellen, dass die Version monoton steigend ist,
  367. damit @command{guix package --upgrade} feststellen kann, welche Version die
  368. neuere ist. Weil Commit-Bezeichner, insbesondere bei Git, nicht monoton
  369. steigen, müssen wir eine Revisionsnummer hinzufügen, die wir jedes Mal
  370. erhöhen, wenn wir das Paket auf einen neueren Snapshot aktualisieren. Die
  371. sich ergebende Versionszeichenkette sieht dann so aus:
  372. @example
  373. 2.0.11-3.cabba9e
  374. ^ ^ ^
  375. | | `-- Commit-ID beim Anbieter
  376. | |
  377. | `--- Revisionsnummer des Guix-Pakets
  378. |
  379. die neueste Version, die der Anbieter veröffentlicht hat
  380. @end example
  381. Es ist eine gute Idee, die Commit-Bezeichner im @code{version}-Feld auf,
  382. sagen wir, 7 Ziffern zu beschränken. Das sieht besser aus (angenommen, das
  383. sollte hier eine Rolle spielen) und vermeidet Probleme, die mit der
  384. maximalen Länge von Shebangs zu tun haben (127 Bytes beim Linux-Kernel). Am
  385. besten benutzt man jedoch den vollständigen Commit-Bezeichner in
  386. @code{origin}s, um Mehrdeutigkeiten zu vermeiden. Eine typische
  387. Paketdefinition könnte so aussehen:
  388. @example
  389. (define mein-paket
  390. (let ((commit "c3f29bc928d5900971f65965feaae59e1272a3f7")
  391. (revision "1")) ;Guix-Paketrevision
  392. (package
  393. (version (git-version "0.9" revision commit))
  394. (source (origin
  395. (method git-fetch)
  396. (uri (git-reference
  397. (url "git://example.org/mein-paket.git")
  398. (commit commit)))
  399. (sha256 (base32 "1mbikn@dots{}"))
  400. (file-name (git-file-name name version))))
  401. ;; @dots{}
  402. )))
  403. @end example
  404. @node Zusammenfassungen und Beschreibungen
  405. @subsection Zusammenfassungen und Beschreibungen
  406. @cindex Paketbeschreibung
  407. @cindex Paketzusammenfassung
  408. Wie wir bereits gesehen haben, enthält jedes Paket in GNU@tie{}Guix eine (im
  409. Code englischsprachige) Zusammenfassung (englisch: Synopsis) und eine
  410. Beschreibung (englisch: Description; siehe @ref{Pakete definieren}). Zusammenfassungen und Beschreibungen sind wichtig: Sie werden
  411. mit @command{guix package --search} durchsucht und stellen eine
  412. entscheidende Informationsquelle für Nutzer dar, die entscheiden wollen, ob
  413. das Paket Ihren Bedürfnissen entspricht, daher sollten Paketentwickler Acht
  414. geben, was sie dort eintragen.
  415. Zusammenfassungen müssen mit einem Großbuchstaben beginnen und dürfen nicht
  416. mit einem Punkt enden. Sie dürfen nicht mit den Artikeln »a« oder »the«
  417. beginnen, die meistens ohnehin nichts zum Verständnis beitragen. Zum
  418. Beispiel sollte »File-frobbing tool« gegenüber »A tool that frobs files«
  419. vorgezogen werden. Die Zusammenfassung sollte aussagen, um was es sich beim
  420. Paket handelt — z.B.@: »Core GNU utilities (file, text, shell)« —, oder
  421. aussagen, wofür es benutzt wird — z.B.@: ist die Zusammenfassung für
  422. GNU@tie{}grep »Print lines matching a pattern«.
  423. Beachten Sie, dass die Zusammenfassung für eine sehr große Leserschaft einen
  424. Sinn ergeben muss. Zum Beispiel würde »Manipulate alignments in the SAM
  425. format« vielleicht von einem erfahrenen Forscher in der Bioinformatik
  426. verstanden, könnte für die Nicht-Spezialisten in Guix’ Zielgruppe aber wenig
  427. hilfreich sein oder würde diesen sogar eine falsche Vorstellung geben. Es
  428. ist eine gute Idee, sich eine Zusammenfassung zu überlegen, die eine
  429. Vorstellung von der Anwendungsdomäne des Pakets vermittelt. Im Beispiel hier
  430. würden sich die Nutzer mit »Manipulate nucleotide sequence alignments«
  431. hoffentlich ein besseres Bild davon machen können, ob das Paket ist, wonach
  432. sie suchen.
  433. Beschreibungen sollten zwischen fünf und zehn Zeilen lang sein. Benutzen Sie
  434. vollständige Sätze und vermeiden Sie Abkürzungen, die Sie nicht zuvor
  435. eingeführt haben. Vermeiden Sie bitte Marketing-Phrasen wie »world-leading«
  436. (»weltweit führend«), »industrial-strength« (»industrietauglich«) und
  437. »next-generation« (»der nächsten Generation«) ebenso wie Superlative wie
  438. »the most advanced« (»das fortgeschrittenste«) — davon haben Nutzer nichts,
  439. wenn sie ein Paket suchen, und es könnte sogar verdächtig klingen. Versuchen
  440. Sie stattdessen, bei den Fakten zu bleiben und dabei Anwendungszwecke und
  441. Funktionalitäten zu erwähnen.
  442. @cindex Texinfo-Auszeichnungen, in Paketbeschreibungen
  443. Beschreibungen können wie bei Texinfo ausgezeichneten Text enthalten. Das
  444. bedeutet, Text kann Verzierungen wie @code{@@code} oder @code{@@dfn},
  445. Auflistungen oder Hyperlinks enthalten (siehe @ref{Overview,,, texinfo, GNU
  446. Texinfo}). Sie sollten allerdings vorsichtig sein, wenn Sie bestimmte
  447. Zeichen wie @samp{@@} und geschweifte Klammern schreiben, weil es sich dabei
  448. um die grundlegenden Sonderzeichen in Texinfo handelt (siehe @ref{Special
  449. Characters,,, texinfo, GNU Texinfo}). Benutzungsschnittstellen wie
  450. @command{guix package --show} kümmern sich darum, solche Auszeichnungen
  451. angemessen darzustellen.
  452. Zusammenfassungen und Beschreibungen werden von Freiwilligen
  453. @uref{http://translationproject.org/domain/guix-packages.html, beim
  454. Translation Project} übersetzt, damit so viele Nutzer wie möglich sie in
  455. ihrer Muttersprache lesen können. Mit Schnittstellen für Benutzer können sie
  456. in der von der aktuell eingestellten Locale festgelegten Sprache durchsucht
  457. und angezeigt werden.
  458. Damit @command{xgettext} sie als übersetzbare Zeichenketten extrahieren
  459. kann, @emph{müssen} Zusammenfassungen und Beschreibungen einfache
  460. Zeichenketten-Literale sein. Das bedeutet, dass Sie diese Zeichenketten
  461. nicht mit Prozeduren wie @code{string-append} oder @code{format}
  462. konstruieren können:
  463. @lisp
  464. (package
  465. ;; @dots{}
  466. (synopsis "This is translatable")
  467. (description (string-append "This is " "*not*" " translatable.")))
  468. @end lisp
  469. Übersetzen ist viel Arbeit, also passen Sie als Paketentwickler bitte umso
  470. mehr auf, wenn Sie Ihre Zusammenfassungen und Beschreibungen formulieren,
  471. weil jede Änderung zusätzliche Arbeit für Übersetzer bedeutet. Um den
  472. Übersetzern zu helfen, können Sie Empfehlungen und Anweisungen für diese
  473. sichtbar machen, indem Sie spezielle Kommentare wie in diesem Beispiel
  474. einfügen (siehe @ref{xgettext Invocation,,, gettext, GNU Gettext}):
  475. @example
  476. ;; TRANSLATORS: "X11 resize-and-rotate" should not be translated.
  477. (description "ARandR is designed to provide a simple visual front end
  478. for the X11 resize-and-rotate (RandR) extension. @dots{}")
  479. @end example
  480. @node Python-Module
  481. @subsection Python-Module
  482. @cindex python
  483. Zur Zeit stellen wir ein Paket für Python 2 und eines für Python 3 jeweils
  484. über die Scheme-Variablen mit den Namen @code{python-2} und @code{python}
  485. zur Verfügung, entsprechend der Erklärungen im Abschnitt @ref{Versionsnummern}. Um Verwirrungen und Namenskollisionen mit anderen
  486. Programmiersprachen zu vermeiden, erscheint es als wünschenswert, dass der
  487. Name eines Pakets für ein Python-Modul auch das Wort @code{python} enthält.
  488. Manche Module sind nur mit einer Version von Python kompatibel, andere mit
  489. beiden. Wenn das Paket Foo nur mit Python 3 kompiliert werden kann, geben
  490. wir ihm den Namen @code{python-foo}, wenn es nur mit Python 2 kompilierbar
  491. ist, wählen wir den Namen @code{python2-foo}. Ist es mit beiden Versionen
  492. kompatibel, erstellen wir zwei Pakete jeweils mit dem entsprechenden Namen.
  493. Wenn ein Projekt bereits das Wort @code{python} im Namen hat, lassen wir es
  494. weg; zum Beispiel ist das Modul python-dateutil unter den Namen
  495. @code{python-dateutil} und @code{python2-dateutil} verfügbar. Wenn der
  496. Projektname mit @code{py} beginnt (z.B.@: @code{pytz}), behalten wir ihn bei
  497. und stellen das oben beschriebene Präfix voran.
  498. @subsubsection Abhängigkeiten angeben
  499. @cindex Eingaben, für Python-Pakete
  500. Informationen über Abhängigkeiten von Python-Paketen, welche mal mehr und
  501. mal weniger stimmen, finden sich normalerweise im Verzeichnisbaum des
  502. Paketquellcodes: in der Datei @file{setup.py}, in @file{requirements.txt}
  503. oder in @file{tox.ini}.
  504. Wenn Sie ein Rezept für ein Python-Paket schreiben, lautet Ihr Auftrag,
  505. diese Abhängigkeiten auf angemessene Arten von »Eingaben« abzubilden (siehe
  506. @ref{»package«-Referenz, inputs}). Obwohl der @code{pypi}-Importer hier
  507. normalerweise eine gute Arbeit leistet (siehe @ref{Aufruf von guix import}),
  508. könnten Sie die folgende Prüfliste durchgehen wollen, um zu bestimmen, wo
  509. welche Abhängigkeit eingeordnet werden sollte.
  510. @itemize
  511. @item
  512. Derzeit ist unser Python-2-Paket so geschrieben, dass es @code{setuptools}
  513. und @code{pip} installiert, wie es auch in den Vorgaben zu Python 3.4
  514. gemacht wird. Sie müssen also keines der beiden als Eingabe angeben. Wenn
  515. Sie es doch tun, wird @command{guix lint} Sie darauf mit einer Warnung
  516. aufmerksam machen.
  517. @item
  518. Python-Abhängigkeiten, die zur Laufzeit gebraucht werden, stehen im
  519. @code{propagated-inputs}-Feld. Solche werden typischerweise mit dem
  520. Schlüsselwort @code{install_requires} in @file{setup.py} oder in der Datei
  521. @file{requirements.txt} definiert.
  522. @item
  523. Python-Pakete, die nur zur Erstellungszeit gebraucht werden — z.B.@: jene,
  524. die mit dem Schlüsselwort @code{setup_requires} in @file{setup.py}
  525. aufgeführt sind — oder die nur zum Testen gebraucht werden — also die in
  526. @code{tests_require} —, stehen in @code{native-inputs}. Die Begründung ist,
  527. dass (1) sie nicht propagiert werden müssen, weil sie zur Laufzeit nicht
  528. gebraucht werden, und (2) wir beim Cross-Kompilieren die »native« Eingabe
  529. des Wirtssystems wollen.
  530. Beispiele sind die Testrahmen @code{pytest}, @code{mock} und
  531. @code{nose}. Wenn natürlich irgendeines dieser Pakete auch zur Laufzeit
  532. benötigt wird, muss es doch in @code{propagated-inputs} stehen.
  533. @item
  534. Alles, was nicht in die bisher genannten Kategorien fällt, steht in
  535. @code{inputs}, zum Beispiel Programme oder C-Bibliotheken, die zur
  536. Erstellung von Python-Paketen mit enthaltenen C-Erweiterungen gebraucht
  537. werden.
  538. @item
  539. Wenn ein Python-Paket optionale Abhängigkeiten hat (@code{extras_require}),
  540. ist es Ihnen überlassen, sie hinzuzufügen oder nicht hinzuzufügen, je
  541. nachdem wie es um deren Verhältnis von Nützlichkeit zu anderen Nachteilen
  542. steht (siehe @ref{Einreichen von Patches, @command{guix size}}).
  543. @end itemize
  544. @node Perl-Module
  545. @subsection Perl-Module
  546. @cindex perl
  547. Eigenständige Perl-Programme bekommen einen Namen wie jedes andere Paket,
  548. unter Nutzung des Namens beim Anbieter in Kleinbuchstaben. Für Perl-Pakete,
  549. die eine einzelne Klasse enthalten, ersetzen wir alle Vorkommen von
  550. @code{::} durch Striche und hängen davor das Präfix @code{perl-} an. Die
  551. Klasse @code{XML::Parser} wird also zu @code{perl-xml-parser}. Module, die
  552. mehrere Klassen beinhalten, behalten ihren Namen beim Anbieter, in
  553. Kleinbuchstaben gesetzt, und auch an sie wird vorne das Präfix @code{perl-}
  554. angehängt. Es gibt die Tendenz, solche Module mit dem Wort @code{perl}
  555. irgendwo im Namen zu versehen, das wird zu Gunsten des Präfixes
  556. weggelassen. Zum Beispiel wird aus @code{libwww-perl} bei uns
  557. @code{perl-libwww}.
  558. @node Java-Pakete
  559. @subsection Java-Pakete
  560. @cindex java
  561. Eigenständige Java-Programme werden wie jedes andere Paket benannt, d.h.@:
  562. mit ihrem in Kleinbuchstaben geschriebenen Namen beim Anbieter.
  563. Um Verwirrungen und Namenskollisionen mit anderen Programmiersprachen zu
  564. vermeiden, ist es wünschenswert, dass dem Namem eines Pakets zu einem
  565. Java-Paket das Präfix @code{java-} vorangestellt wird. Wenn ein Projekt
  566. bereits das Wort @code{java} im Namen trägt, lassen wir es weg; zum Beispiel
  567. befindet sich das Java-Paket @code{ngsjava} in einem Paket namens
  568. @code{java-ngs}.
  569. Bei Java-Paketen, die eine einzelne Klasse oder eine kleine
  570. Klassenhierarchie enthalten, benutzen wir den Klassennamen in
  571. Kleinbuchstaben und ersetzen dabei alle Vorkommen von @code{.} durch Striche
  572. und setzen das Präfix @code{java-} davor. Die Klasse
  573. @code{apache.commons.cli} wird also zum Paket
  574. @code{java-apache-commons-cli}.
  575. @node Schriftarten
  576. @subsection Schriftarten
  577. @cindex Schriftarten
  578. Wenn Schriftarten in der Regel nicht von Nutzern zur Textbearbeitung
  579. installiert werden oder als Teil eines größeren Software-Pakets mitgeliefert
  580. werden, gelten dafür die allgemeinen Paketrichtlinien für Software. Zum
  581. Beispiel trifft das auf als Teil des X.Org-Systems ausgelieferte
  582. Schriftarten zu, oder auf Schriftarten, die ein Teil von TeX Live sind.
  583. Damit es Nutzer leichter haben, nach Schriftarten zu suchen, konstruieren
  584. wir die Namen von anderen Paketen, die nur Schriftarten enthalten, nach dem
  585. folgenden Schema, egal was der Paketname beim Anbieter ist.
  586. Der Name eines Pakets, das nur eine Schriftfamilie enthält, beginnt mit
  587. @code{font-}. Darauf folgt der Name des Schriftenherstellers und ein Strich
  588. @code{-}, sofern bekannt ist, wer der Schriftenhersteller ist, und dann der
  589. Name der Schriftfamilie, in dem Leerzeichen durch Striche ersetzt werden
  590. (und wie immer mit Großbuchstaben statt Kleinbuchstaben). Zum Beispiel
  591. befindet sich die von SIL hergestellte Gentium-Schriftfamilie im Paket mit
  592. dem Namen @code{font-sil-gentium}.
  593. Wenn ein Paket mehrere Schriftfamilien enthält, wird der Name der Sammlung
  594. anstelle des Schriftfamiliennamens benutzt. Zum Beispiel umfassen die
  595. Liberation-Schriftarten drei Familien: Liberation Sans, Liberation Serif und
  596. Liberation Mono. Man könnte sie getrennt voneinander mit den Namen
  597. @code{font-liberation-sans} und so weiter in Pakete einteilen, da sie aber
  598. unter einem gemeinsamen Namen angeboten werden, packen wir sie lieber
  599. zusammen in ein Paket mit dem Namen @code{font-liberation}.
  600. Für den Fall, dass mehrere Formate derselben Schriftfamilie oder
  601. Schriftartensammlung in separate Pakete kommen, wird ein Kurzname für das
  602. Format mit einem Strich vorne zum Paketnamen hinzugefügt. Wir benutzen
  603. @code{-ttf} für TrueType-Schriftarten, @code{-otf} für OpenType-Schriftarten
  604. und @code{-type1} für PostScript-Typ-1-Schriftarten.
  605. @node Code-Stil
  606. @section Code-Stil
  607. Im Allgemeinen folgt unser Code den GNU Coding Standards (siehe @ref{Top,,,
  608. standards, GNU Coding Standards}). Da diese aber nicht viel über Scheme zu
  609. sagen haben, folgen hier einige zusätzliche Regeln.
  610. @menu
  611. * Programmierparadigmen:: Wie Sie Ihre Elemente zusammenstellen.
  612. * Module:: Wo Sie Ihren Code unterbringen.
  613. * Datentypen und Mustervergleich:: Implementierung von Datenstrukturen.
  614. * Formatierung von Code:: Schreibkonventionen.
  615. @end menu
  616. @node Programmierparadigmen
  617. @subsection Programmierparadigmen
  618. Scheme-Code wird in Guix auf rein funktionale Weise geschrieben. Eine
  619. Ausnahme ist Code, der mit Ein- und Ausgabe zu tun hat, und Prozeduren, die
  620. grundlegende Konzepte implementieren, wie zum Beispiel die Prozedur
  621. @code{memoize}.
  622. @node Module
  623. @subsection Module
  624. Guile-Module, die beim Erstellen nutzbar sein sollen, müssen im Namensraum
  625. @code{(guix build @dots{})} leben. Sie dürfen auf keine anderen Guix- oder
  626. GNU-Module Bezug nehmen. Jedoch ist es in Ordnung, wenn ein »wirtsseitiges«
  627. Modul ein erstellungsseitiges Modul benutzt.
  628. Module, die mit dem weiteren GNU-System zu tun haben, sollten im Namensraum
  629. @code{(gnu @dots{})} und nicht in @code{(guix @dots{})} stehen.
  630. @node Datentypen und Mustervergleich
  631. @subsection Datentypen und Mustervergleich
  632. Im klassischen Lisp gibt es die Tendenz, Listen zur Darstellung von allem zu
  633. benutzen, und diese dann »händisch« zu durchlaufen mit @code{car},
  634. @code{cdr}, @code{cadr} und so weiter. Dieser Stil ist aus verschiedenen
  635. Gründen problematisch, insbesondere wegen der Tatsache, dass er schwer zu
  636. lesen, schnell fehlerbehaftet und ein Hindernis beim Melden von Typfehlern
  637. ist.
  638. Guix-Code sollte angemessene Datentypen definieren (zum Beispiel mit
  639. @code{define-record-type*}) statt Listen zu missbrauchen. Außerdem sollte er
  640. das @code{(ice-9 match)}-Modul von Guile zum Mustervergleich benutzen,
  641. besonders mit Listen.
  642. @node Formatierung von Code
  643. @subsection Formatierung von Code
  644. @cindex Formatierung von Code
  645. @cindex Code-Stil
  646. Beim Schreiben von Scheme-Code halten wir uns an die üblichen
  647. Gepflogenheiten unter Scheme-Programmierern. Im Allgemeinen bedeutet das,
  648. dass wir uns an @url{http://mumble.net/~campbell/scheme/style.txt,
  649. Riastradh's Lisp Style Rules} halten. Es hat sich ergeben, dass dieses
  650. Dokument auch die Konventionen beschreibt, die im Code von Guile
  651. hauptsächlich verwendet werden. Es ist gut durchdacht und schön geschrieben,
  652. also lesen Sie es bitte.
  653. Ein paar in Guix eingeführte Sonderformen, wie zum Beispiel das
  654. @code{substitute*}-Makro, haben abweichende Regeln für die Einrückung. Diese
  655. sind in der Datei @file{.dir-locals.el} definiert, die Emacs automatisch
  656. benutzt. Beachten Sie auch, dass Emacs-Guix einen Modus namens
  657. @code{guix-devel-mode} bereitstellt, der Guix-Code richtig einrückt und
  658. hervorhebt (siehe @ref{Entwicklung,,, emacs-guix, The Emacs-Guix Reference
  659. Manual}).
  660. @cindex Einrückung, Code-
  661. @cindex Formatierung, Code-
  662. Falls Sie nicht Emacs verwenden, sollten Sie sicherstellen, dass Ihr Editor
  663. diese Regeln kennt. Um eine Paketdefinition automatisch einzurücken, können
  664. Sie auch Folgendes ausführen:
  665. @example
  666. ./etc/indent-code.el gnu/packages/@var{Datei}.scm @var{Paket}
  667. @end example
  668. @noindent
  669. Dadurch wird die Definition von @var{Paket} in
  670. @file{gnu/packages/@var{Datei}.scm} automatisch eingerückt, indem Emacs im
  671. Batch-Modus läuft. Um die Einrückung in einer gesamten Datei vorzunehmen,
  672. lassen Sie das zweite Argument weg:
  673. @example
  674. ./etc/indent-code.el gnu/services/@var{Datei}.scm
  675. @end example
  676. @cindex Vim, zum Editieren von Scheme-Code
  677. Wenn Sie Code mit Vim bearbeiten, empfehlen wir, dass Sie @code{:set
  678. autoindent} ausführen, damit Ihr Code automatisch eingerückt wird, während
  679. Sie ihn schreiben. Außerdem könnte Ihnen
  680. @uref{https://www.vim.org/scripts/script.php?script_id=3998,
  681. @code{paredit.vim}} dabei helfen, mit all diesen Klammern fertigzuwerden.
  682. Wir fordern von allen Prozeduren auf oberster Ebene, dass sie über einen
  683. Docstring verfügen. Diese Voraussetzung kann jedoch bei einfachen, privaten
  684. Prozeduren im Namensraum @code{(guix build @dots{})} aufgeweicht werden.
  685. Prozeduren sollten nicht mehr als vier positionsbestimmte Parameter
  686. haben. Benutzen Sie Schlüsselwort-Parameter für Prozeduren, die mehr als
  687. vier Parameter entgegennehmen.
  688. @node Einreichen von Patches
  689. @section Einreichen von Patches
  690. Die Entwicklung wird mit Hilfe des verteilten Versionskontrollsystems Git
  691. durchgeführt. Daher ist eine ständige Verbindung zum Repository nicht
  692. unbedingt erforderlich. Wir begrüßen Beiträge in Form von Patches, die
  693. mittels @code{git format-patch} erstellt und an die Mailingliste
  694. @email{guix-patches@@gnu.org} geschickt werden.
  695. Diese Mailing-Liste setzt auf einer Debbugs-Instanz auf, die zugänglich ist
  696. unter @uref{https://bugs.gnu.org/guix-patches}, wodurch wir den Überblick
  697. über Eingereichtes behalten können. Jede an diese Mailing-Liste gesendete
  698. Nachricht bekommt eine neue Folgenummer zugewiesen, so dass man eine
  699. Folge-Email zur Einreichung an @code{@var{NNN}@@debbugs.gnu.org} senden
  700. kann, wobei @var{NNN} für die Folgenummer steht (siehe @ref{Senden einer Patch-Reihe}).
  701. Bitte schreiben Sie Commit-Logs im ChangeLog-Format (siehe @ref{Change
  702. Logs,,, standards, GNU Coding Standards}); dazu finden Sie Beispiele unter
  703. den bisherigen Commits.
  704. Bevor Sie einen Patch einreichen, der eine Paketdefinition hinzufügt oder
  705. verändert, gehen Sie bitte diese Prüfliste durch:
  706. @enumerate
  707. @item
  708. Wenn die Autoren der verpackten Software eine kryptografische Signatur
  709. bzw. Beglaubigung für den Tarball der Veröffentlichung anbieten, so machen
  710. Sie sich bitte die Mühe, die Echtheit des Archivs zu überprüfen. Für eine
  711. abgetrennte GPG-Signaturdatei würden Sie das mit dem Befehl @code{gpg
  712. --verify} tun.
  713. @item
  714. Nehmen Sie sich die Zeit, eine passende Zusammenfassung und Beschreibung für
  715. das Paket zu verfassen. Unter @ref{Zusammenfassungen und Beschreibungen} finden Sie
  716. dazu einige Richtlinien.
  717. @item
  718. Verwenden Sie @code{guix lint @var{Paket}}, wobei @var{Paket} das neue oder
  719. geänderte Paket bezeichnet, und beheben Sie alle gemeldeten Fehler (siehe
  720. @ref{Aufruf von guix lint}).
  721. @item
  722. Stellen Sie sicher, dass das Paket auf Ihrer Plattform erstellt werden kann,
  723. indem Sie @code{guix build @var{Paket}} ausführen.
  724. @item
  725. Wir empfehlen, dass Sie auch versuchen, das Paket auf anderen unterstützten
  726. Plattformen zu erstellen. Da Sie vielleicht keinen Zugang zu echter Hardware
  727. für diese Plattformen haben, empfehlen wir, den
  728. @code{qemu-binfmt-service-type} zu benutzen, um sie zu emulieren. Um ihn zu
  729. aktivieren, fügen Sie den folgenden Dienst in die Liste der Dienste
  730. (»services«) in Ihrer @code{operating-system}-Konfiguration ein:
  731. @example
  732. (service qemu-binfmt-service-type
  733. (qemu-binfmt-configuration
  734. (platforms (lookup-qemu-platforms "arm" "aarch64" "mips64el"))
  735. (guix-support? #t)))
  736. @end example
  737. Rekonfigurieren Sie anschließend Ihr System.
  738. Sie können Pakete für andere Plattformen erstellen lassen, indem Sie die
  739. Befehlszeilenoption @code{--system} angeben. Um zum Beispiel das Paket
  740. »hello« für die Architekturen armhf, aarch64 oder mips64 erstellen zu
  741. lassen, würden Sie jeweils die folgenden Befehle angeben:
  742. @example
  743. guix build --system=armhf-linux --rounds=2 hello
  744. guix build --system=aarch64-linux --rounds=2 hello
  745. guix build --system=mips64el-linux --rounds=2 hello
  746. @end example
  747. @item
  748. @cindex gebündelt
  749. Achten Sie darauf, dass im Paket keine Software gebündelt mitgeliefert wird,
  750. die bereits in separaten Paketen zur Verfügung steht.
  751. Manchmal enthalten Pakete Kopien des Quellcodes ihrer Abhängigkeiten, um
  752. Nutzern die Installation zu erleichtern. Als eine Distribution wollen wir
  753. jedoch sicherstellen, dass solche Pakete die schon in der Distribution
  754. verfügbare Fassung benutzen, sofern es eine gibt. Dadurch wird sowohl der
  755. Ressourcenverbrauch optimiert (die Abhängigkeit wird so nur einmal erstellt
  756. und gespeichert) als auch der Distribution die Möglichkeit gegeben,
  757. ergänzende Änderungen durchzuführen, um beispielsweise
  758. Sicherheitsaktualisierungen für ein bestimmtes Paket an nur einem Ort
  759. einzuspielen, die aber das gesamte System betreffen — gebündelt
  760. mitgelieferte Kopien würden dies verhindern.
  761. @item
  762. Schauen Sie sich das von @command{guix size} ausgegebene Profil an (siehe
  763. @ref{Aufruf von guix size}). Dadurch können Sie Referenzen auf andere Pakete
  764. finden, die ungewollt vorhanden sind. Dies kann auch dabei helfen, zu
  765. entscheiden, ob das Paket aufgespalten werden sollte (siehe @ref{Pakete mit mehreren Ausgaben.}) und welche optionalen Abhängigkeiten verwendet
  766. werden sollten. Dabei sollten Sie es wegen seiner enormen Größe insbesondere
  767. vermeiden, @code{texlive} als eine Abhängigkeit hinzuzufügen; benutzen Sie
  768. stattdessen @code{texlive-tiny} oder @code{texlive-union}.
  769. @item
  770. Achten Sie bei wichtigen Änderungen darauf, dass abhängige Pakete (falls
  771. vorhanden) nicht von der Änderung beeinträchtigt werden; @code{guix refresh
  772. --list-dependent @var{Paket}} hilft Ihnen dabei (siehe @ref{Aufruf von guix refresh}).
  773. @c See <https://lists.gnu.org/archive/html/guix-devel/2016-10/msg00933.html>.
  774. @cindex Branching-Strategie
  775. @cindex Neuerstellungs-Zeitplan
  776. Je nachdem, wieviele abhängige Pakete es gibt, und entsprechend wieviele
  777. Neuerstellungen dadurch nötig würden, finden Commits auf anderen Branches
  778. statt, nach ungefähr diesen Regeln:
  779. @table @asis
  780. @item 300 abhängige Pakete oder weniger
  781. @code{master}-Branch (störfreie Änderungen).
  782. @item zwischen 300 und 1200 abhängige Pakete
  783. @code{staging}-Branch (störfreie Änderungen). Dieser Branch wird circa alle
  784. 3 Wochen mit @code{master} zusammengeführt. Themenbezogene Änderungen
  785. (z.B.@: eine Aktualisierung der GNOME-Plattform) können stattdessen auch auf
  786. einem eigenen Branch umgesetzt werden (wie @code{gnome-updates}).
  787. @item mehr als 1200 abhängige Pakete
  788. @code{core-updates}-Branch (kann auch größere und womöglich andere Software
  789. beeinträchtigende Änderungen umfassen). Dieser Branch wird planmäßig in
  790. @code{master} alle 2,5 Monate oder so gemerget.
  791. @end table
  792. All diese Branches werden kontinuierlich
  793. @uref{https://hydra.gnu.org/project/gnu, auf unserer Build-Farm} erstellt
  794. und in @code{master} gemerget, sobald alles erfolgreich erstellt worden
  795. ist. Dadurch können wir Probleme beheben, bevor sie bei Nutzern auftreten,
  796. und zudem das Zeitfenster, während dessen noch keine vorerstellten
  797. Binärdateien verfügbar sind, verkürzen.
  798. @c TODO: It would be good with badges on the website that tracks these
  799. @c branches. Or maybe even a status page.
  800. Im Allgemeinen werden Branches außer @code{master} als @emph{unveränderlich}
  801. angesehen, wenn sie kürzlich ausgewertet wurden oder ein entsprechender
  802. @code{-next}-Branch existiert. Bitte fragen Sie auf der Mailing-Liste oder
  803. IRC, wenn Sie sich nicht sicher sind, wo ein Patch eingespielt werden
  804. sollte.
  805. @item
  806. @cindex Determinismus, von Erstellungsprozessen
  807. @cindex Reproduzierbare Erstellungen, Überprüfung
  808. Überprüfen Sie, ob der Erstellungsprozess deterministisch ist. Dazu prüfen
  809. Sie typischerweise, ob eine unabhängige Erstellung des Pakets genau dasselbe
  810. Ergebnis wie Ihre Erstellung hat, Bit für Bit.
  811. Dies können Sie leicht tun, indem Sie dasselbe Paket mehrere Male
  812. hintereinander auf Ihrer Maschine erstellen (siehe @ref{Aufruf von guix build}):
  813. @example
  814. guix build --rounds=2 mein-paket
  815. @end example
  816. Dies reicht aus, um eine ganze Klasse häufiger Ursachen von
  817. Nichtdeterminismus zu finden, wie zum Beispiel Zeitstempel oder
  818. zufallsgenerierte Ausgaben im Ergebnis der Erstellung.
  819. 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
  820. commitet und von @code{@value{SUBSTITUTE-SERVER}} erstellt wurde, um zu
  821. sehen, ob dort dasselbe Ergebnis wie bei Ihnen geliefert wurde. Noch besser:
  822. Finden Sie eine andere Maschine, die das Paket erstellen kann, und führen
  823. Sie @command{guix publish} aus. Da sich die entfernte Erstellungsmaschine
  824. wahrscheinlich von Ihrer unterscheidet, können Sie auf diese Weise Probleme
  825. durch Nichtdeterminismus erkennen, die mit der Hardware zu tun haben — zum
  826. Beispiel die Nutzung anderer Befehlssatzerweiterungen — oder mit dem
  827. Betriebssystem-Kernel — zum Beispiel, indem @code{uname} oder
  828. @file{/proc}-Dateien verwendet werden.
  829. @item
  830. Beim Schreiben von Dokumentation achten Sie bitte auf eine
  831. geschlechtsneutrale Wortwahl, wenn Sie sich auf Personen beziehen, wie
  832. @uref{https://en.wikipedia.org/wiki/Singular_they, »they«@comma{}
  833. »their«@comma{} »them« im Singular} und so weiter.
  834. @item
  835. Stelllen Sie sicher, dass Ihr Patch nur einen Satz zusammengehöriger
  836. Änderungen umfasst. Das Zusammenfassen nicht zusammengehöriger Änderungen
  837. erschwert und bremst das Durchsehen Ihres Patches.
  838. Beispiele für nicht zusammengehörige Änderungen sind das Hinzufügen mehrerer
  839. Pakete auf einmal, oder das Aktualisieren eines Pakets auf eine neue Version
  840. zusammen mit Fehlerbehebungen für das Paket.
  841. @item
  842. Bitte befolgen Sie unsere Richtlinien für die Code-Formatierung, womöglich
  843. wollen Sie dies automatisch tun lassen durch das Skript
  844. @command{etc/indent-code.el} (siehe @ref{Formatierung von Code}).
  845. @item
  846. Benutzen Sie, wenn möglich, Spiegelserver (Mirrors) in der Quell-URL (siehe
  847. @ref{Aufruf von guix download}). Verwenden Sie verlässliche URLs, keine
  848. automatisch generierten. Zum Beispiel sind Archive von GitHub nicht immer
  849. identisch von einer Generation auf die nächste, daher ist es in diesem Fall
  850. besser, als Quelle einen Klon des Repositorys zu verwenden. Benutzen Sie
  851. @emph{nicht} das @command{name}-Feld beim Angeben der URL; er hilft nicht
  852. wirklich und wenn sich der Name ändert, stimmt die URL nicht mehr.
  853. @end enumerate
  854. Bitte benutzen Sie @samp{[PATCH] @dots{}} als Betreff, wenn Sie einen Patch
  855. an die Mailing-Liste schicken. Sie können dazu Ihr E-Mail-Programm oder den
  856. Befehl @command{git send-email} benutzen (siehe @ref{Senden einer Patch-Reihe}). Wir bevorzugen es, Patches als reine Textnachrichten zu erhalten,
  857. entweder eingebettet (inline) oder als MIME-Anhänge. Sie sind dazu
  858. angehalten, zu überprüfen, ob Ihr Mail-Programm solche Dinge wie
  859. Zeilenumbrüche oder die Einrückung verändert, wodurch die Patches womöglich
  860. nicht mehr funktionieren.
  861. Wenn dadurch ein Fehler behoben wurde, schließen Sie bitte den Thread, indem
  862. Sie eine E-Mail an @email{@var{NNN}-done@@debbugs.gnu.org} senden.
  863. @unnumberedsubsec Senden einer Patch-Reihe
  864. @anchor{Senden einer Patch-Reihe}
  865. @cindex Patch-Reihe
  866. @cindex @code{git send-email}
  867. @cindex @code{git-send-email}
  868. @c Debbugs bug: https://debbugs.gnu.org/db/15/15361.html
  869. Wenn Sie eine Patch-Reihe senden (z.B.@: mit @code{git send-email}),
  870. schicken Sie bitte als Erstes eine Nachricht an
  871. @email{guix-patches@@gnu.org} und dann nachfolgende Patches an
  872. @email{@var{NNN}@@debbugs.gnu.org}, um sicherzustellen, dass sie zusammen
  873. bearbeitet werden. Siehe @uref{https://debbugs.gnu.org/Advanced.html, die
  874. Debbugs-Dokumentation} für weitere Informationen.