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.
 
 
 
 
 
 

1272 lines
51 KiB

  1. @node Contributing
  2. @chapter Contributing
  3. This project is a cooperative effort, and we need your help to make it
  4. grow! Please get in touch with us on @email{guix-devel@@gnu.org} and
  5. @code{#guix} on the Freenode IRC network. We welcome ideas, bug
  6. reports, patches, and anything that may be helpful to the project. We
  7. particularly welcome help on packaging (@pxref{Packaging Guidelines}).
  8. @cindex code of conduct, of contributors
  9. @cindex contributor covenant
  10. We want to provide a warm, friendly, and harassment-free environment, so
  11. that anyone can contribute to the best of their abilities. To this end
  12. our project uses a ``Contributor Covenant'', which was adapted from
  13. @url{https://contributor-covenant.org/}. You can find a local version in
  14. the @file{CODE-OF-CONDUCT} file in the source tree.
  15. Contributors are not required to use their legal name in patches and
  16. on-line communication; they can use any name or pseudonym of their
  17. choice.
  18. @menu
  19. * Building from Git:: The latest and greatest.
  20. * Running Guix Before It Is Installed:: Hacker tricks.
  21. * The Perfect Setup:: The right tools.
  22. * Packaging Guidelines:: Growing the distribution.
  23. * Coding Style:: Hygiene of the contributor.
  24. * Submitting Patches:: Share your work.
  25. * Tracking Bugs and Patches:: Using Debbugs.
  26. * Commit Access:: Pushing to the official repository.
  27. @end menu
  28. @node Building from Git
  29. @section Building from Git
  30. If you want to hack Guix itself, it is recommended to use the latest
  31. version from the Git repository:
  32. @example
  33. git clone https://git.savannah.gnu.org/git/guix.git
  34. @end example
  35. @cindex authentication, of a Guix checkout
  36. How do you ensure that you obtained a genuine copy of the repository?
  37. Guix itself provides a tool to @dfn{authenticate} your checkout, but you
  38. must first make sure this tool is genuine in order to ``bootstrap'' the
  39. trust chain. To do that, run:
  40. @c XXX: Adjust instructions when there's a known tag to start from.
  41. @example
  42. git verify-commit `git log --format=%H build-aux/git-authenticate.scm`
  43. @end example
  44. The output must look something like:
  45. @example
  46. gpg: Signature made Fri 27 Dec 2019 01:27:41 PM CET
  47. gpg: using RSA key 3CE464558A84FDC69DB40CFB090B11993D9AEBB5
  48. @dots{}
  49. gpg: Signature made Fri 27 Dec 2019 01:25:22 PM CET
  50. gpg: using RSA key 3CE464558A84FDC69DB40CFB090B11993D9AEBB5
  51. @dots{}
  52. @end example
  53. @noindent
  54. ... meaning that changes to this file are all signed with key
  55. @code{3CE464558A84FDC69DB40CFB090B11993D9AEBB5} (you may need to fetch
  56. this key from a key server, if you have not done it yet).
  57. From there on, you can authenticate all the commits included in your
  58. checkout by running:
  59. @example
  60. make authenticate
  61. @end example
  62. The first run takes a couple of minutes, but subsequent runs are faster.
  63. @quotation Note
  64. You are advised to run @command{make authenticate} after every
  65. @command{git pull} invocation. This ensures you keep receiving valid
  66. changes to the repository
  67. @end quotation
  68. The easiest way to set up a development environment for Guix is, of
  69. course, by using Guix! The following command starts a new shell where
  70. all the dependencies and appropriate environment variables are set up to
  71. hack on Guix:
  72. @example
  73. guix environment guix --pure
  74. @end example
  75. @xref{Invoking guix environment}, for more information on that command.
  76. If you are unable to use Guix when building Guix from a checkout, the
  77. following are the required packages in addition to those mentioned in the
  78. installation instructions (@pxref{Requirements}).
  79. @itemize
  80. @item @url{https://gnu.org/software/autoconf/, GNU Autoconf};
  81. @item @url{https://gnu.org/software/automake/, GNU Automake};
  82. @item @url{https://gnu.org/software/gettext/, GNU Gettext};
  83. @item @url{https://gnu.org/software/texinfo/, GNU Texinfo};
  84. @item @url{https://www.graphviz.org/, Graphviz};
  85. @item @url{https://www.gnu.org/software/help2man/, GNU Help2man (optional)}.
  86. @end itemize
  87. On Guix, extra dependencies can be added by instead running @command{guix
  88. environment} with @option{--ad-hoc}:
  89. @example
  90. guix environment guix --pure --ad-hoc help2man git strace
  91. @end example
  92. Run @command{./bootstrap} to generate the build system infrastructure
  93. using Autoconf and Automake. If you get an error like this one:
  94. @example
  95. configure.ac:46: error: possibly undefined macro: PKG_CHECK_MODULES
  96. @end example
  97. @noindent
  98. it probably means that Autoconf couldn’t find @file{pkg.m4}, which is
  99. provided by pkg-config. Make sure that @file{pkg.m4} is available. The
  100. same holds for the @file{guile.m4} set of macros provided by Guile. For
  101. instance, if you installed Automake in @file{/usr/local}, it wouldn’t
  102. look for @file{.m4} files in @file{/usr/share}. In that case, you have
  103. to invoke the following command:
  104. @example
  105. export ACLOCAL_PATH=/usr/share/aclocal
  106. @end example
  107. @xref{Macro Search Path,,, automake, The GNU Automake Manual}, for
  108. more information.
  109. Then, run @command{./configure} as usual. Make sure to pass
  110. @code{--localstatedir=@var{directory}} where @var{directory} is the
  111. @code{localstatedir} value used by your current installation (@pxref{The
  112. Store}, for information about this). We recommend to use the value
  113. @code{/var}.
  114. Finally, you have to invoke @code{make check} to run tests
  115. (@pxref{Running the Test Suite}). If anything
  116. fails, take a look at installation instructions (@pxref{Installation})
  117. or send a message to the @email{guix-devel@@gnu.org, mailing list}.
  118. @node Running Guix Before It Is Installed
  119. @section Running Guix Before It Is Installed
  120. In order to keep a sane working environment, you will find it useful to
  121. test the changes made in your local source tree checkout without
  122. actually installing them. So that you can distinguish between your
  123. ``end-user'' hat and your ``motley'' costume.
  124. To that end, all the command-line tools can be used even if you have not
  125. run @code{make install}. To do that, you first need to have an environment
  126. with all the dependencies available (@pxref{Building from Git}), and then
  127. simply prefix each command with
  128. @command{./pre-inst-env} (the @file{pre-inst-env} script lives in the
  129. top build tree of Guix; it is generated by @command{./configure}).
  130. An example@footnote{The @option{-E} flag to
  131. @command{sudo} guarantees that @code{GUILE_LOAD_PATH} is correctly set
  132. such that @command{guix-daemon} and the tools it uses can find the Guile
  133. modules they need.}:
  134. @example
  135. $ sudo -E ./pre-inst-env guix-daemon --build-users-group=guixbuild
  136. $ ./pre-inst-env guix build hello
  137. @end example
  138. @noindent
  139. Similarly, an example for a Guile session using the Guix modules:
  140. @example
  141. $ ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))'
  142. ;;; ("x86_64-linux")
  143. @end example
  144. @noindent
  145. @cindex REPL
  146. @cindex read-eval-print loop
  147. @dots{} and for a REPL (@pxref{Using Guile Interactively,,, guile, Guile
  148. Reference Manual}):
  149. @example
  150. $ ./pre-inst-env guile
  151. scheme@@(guile-user)> ,use(guix)
  152. scheme@@(guile-user)> ,use(gnu)
  153. scheme@@(guile-user)> (define snakes
  154. (fold-packages
  155. (lambda (package lst)
  156. (if (string-prefix? "python"
  157. (package-name package))
  158. (cons package lst)
  159. lst))
  160. '()))
  161. scheme@@(guile-user)> (length snakes)
  162. $1 = 361
  163. @end example
  164. The @command{pre-inst-env} script sets up all the environment variables
  165. necessary to support this, including @env{PATH} and @env{GUILE_LOAD_PATH}.
  166. Note that @command{./pre-inst-env guix pull} does @emph{not} upgrade the
  167. local source tree; it simply updates the @file{~/.config/guix/current}
  168. symlink (@pxref{Invoking guix pull}). Run @command{git pull} instead if
  169. you want to upgrade your local source tree.
  170. @node The Perfect Setup
  171. @section The Perfect Setup
  172. The Perfect Setup to hack on Guix is basically the perfect setup used
  173. for Guile hacking (@pxref{Using Guile in Emacs,,, guile, Guile Reference
  174. Manual}). First, you need more than an editor, you need
  175. @url{https://www.gnu.org/software/emacs, Emacs}, empowered by the
  176. wonderful @url{https://nongnu.org/geiser/, Geiser}. To set that up, run:
  177. @example
  178. guix package -i emacs guile emacs-geiser
  179. @end example
  180. Geiser allows for interactive and incremental development from within
  181. Emacs: code compilation and evaluation from within buffers, access to
  182. on-line documentation (docstrings), context-sensitive completion,
  183. @kbd{M-.} to jump to an object definition, a REPL to try out your code,
  184. and more (@pxref{Introduction,,, geiser, Geiser User Manual}). For
  185. convenient Guix development, make sure to augment Guile’s load path so
  186. that it finds source files from your checkout:
  187. @lisp
  188. ;; @r{Assuming the Guix checkout is in ~/src/guix.}
  189. (with-eval-after-load 'geiser-guile
  190. (add-to-list 'geiser-guile-load-path "~/src/guix"))
  191. @end lisp
  192. To actually edit the code, Emacs already has a neat Scheme mode. But in
  193. addition to that, you must not miss
  194. @url{https://www.emacswiki.org/emacs/ParEdit, Paredit}. It provides
  195. facilities to directly operate on the syntax tree, such as raising an
  196. s-expression or wrapping it, swallowing or rejecting the following
  197. s-expression, etc.
  198. @cindex code snippets
  199. @cindex templates
  200. @cindex reducing boilerplate
  201. We also provide templates for common git commit messages and package
  202. definitions in the @file{etc/snippets} directory. These templates can
  203. be used with @url{https://joaotavora.github.io/yasnippet/, YASnippet} to
  204. expand short trigger strings to interactive text snippets. You may want
  205. to add the snippets directory to the @var{yas-snippet-dirs} variable in
  206. Emacs.
  207. @lisp
  208. ;; @r{Assuming the Guix checkout is in ~/src/guix.}
  209. (with-eval-after-load 'yasnippet
  210. (add-to-list 'yas-snippet-dirs "~/src/guix/etc/snippets"))
  211. @end lisp
  212. The commit message snippets depend on @url{https://magit.vc/, Magit} to
  213. display staged files. When editing a commit message type @code{add}
  214. followed by @kbd{TAB} to insert a commit message template for adding a
  215. package; type @code{update} followed by @kbd{TAB} to insert a template
  216. for updating a package; type @code{https} followed by @kbd{TAB} to
  217. insert a template for changing the home page URI of a package to HTTPS.
  218. The main snippet for @code{scheme-mode} is triggered by typing
  219. @code{package...} followed by @kbd{TAB}. This snippet also inserts the
  220. trigger string @code{origin...}, which can be expanded further. The
  221. @code{origin} snippet in turn may insert other trigger strings ending on
  222. @code{...}, which also can be expanded further.
  223. @cindex insert or update copyright
  224. @cindex @code{M-x guix-copyright}
  225. @cindex @code{M-x copyright-update}
  226. Additionaly we provide insertion and automatic update of a copyright in
  227. @file{etc/copyright.el}. You may want to set your full name, mail, and
  228. load a file.
  229. @lisp
  230. (setq user-full-name "Alice Doe")
  231. (setq user-mail-address "alice@@mail.org")
  232. ;; @r{Assuming the Guix checkout is in ~/src/guix.}
  233. (load-file "~/src/guix/etc/copyright.el")
  234. @end lisp
  235. To insert a copyright at the current line invoke @code{M-x guix-copyright}.
  236. To update a copyright you need to specify a @code{copyright-names-regexp}.
  237. @lisp
  238. (setq copyright-names-regexp
  239. (format "%s <%s>" user-full-name user-mail-address))
  240. @end lisp
  241. You can check if your copyright is up to date by evaluating @code{M-x
  242. copyright-update}. If you want to do it automatically after each buffer
  243. save then add @code{(add-hook 'after-save-hook 'copyright-update)} in
  244. Emacs.
  245. @node Packaging Guidelines
  246. @section Packaging Guidelines
  247. @cindex packages, creating
  248. The GNU distribution is nascent and may well lack some of your favorite
  249. packages. This section describes how you can help make the distribution
  250. grow.
  251. Free software packages are usually distributed in the form of
  252. @dfn{source code tarballs}---typically @file{tar.gz} files that contain
  253. all the source files. Adding a package to the distribution means
  254. essentially two things: adding a @dfn{recipe} that describes how to
  255. build the package, including a list of other packages required to build
  256. it, and adding @dfn{package metadata} along with that recipe, such as a
  257. description and licensing information.
  258. In Guix all this information is embodied in @dfn{package definitions}.
  259. Package definitions provide a high-level view of the package. They are
  260. written using the syntax of the Scheme programming language; in fact,
  261. for each package we define a variable bound to the package definition,
  262. and export that variable from a module (@pxref{Package Modules}).
  263. However, in-depth Scheme knowledge is @emph{not} a prerequisite for
  264. creating packages. For more information on package definitions,
  265. @pxref{Defining Packages}.
  266. Once a package definition is in place, stored in a file in the Guix
  267. source tree, it can be tested using the @command{guix build} command
  268. (@pxref{Invoking guix build}). For example, assuming the new package is
  269. called @code{gnew}, you may run this command from the Guix build tree
  270. (@pxref{Running Guix Before It Is Installed}):
  271. @example
  272. ./pre-inst-env guix build gnew --keep-failed
  273. @end example
  274. Using @code{--keep-failed} makes it easier to debug build failures since
  275. it provides access to the failed build tree. Another useful
  276. command-line option when debugging is @code{--log-file}, to access the
  277. build log.
  278. If the package is unknown to the @command{guix} command, it may be that
  279. the source file contains a syntax error, or lacks a @code{define-public}
  280. clause to export the package variable. To figure it out, you may load
  281. the module from Guile to get more information about the actual error:
  282. @example
  283. ./pre-inst-env guile -c '(use-modules (gnu packages gnew))'
  284. @end example
  285. Once your package builds correctly, please send us a patch
  286. (@pxref{Submitting Patches}). Well, if you need help, we will be happy to
  287. help you too. Once the patch is committed in the Guix repository, the
  288. new package automatically gets built on the supported platforms by
  289. @url{@value{SUBSTITUTE-SERVER}, our continuous integration system}.
  290. @cindex substituter
  291. Users can obtain the new package definition simply by running
  292. @command{guix pull} (@pxref{Invoking guix pull}). When
  293. @code{@value{SUBSTITUTE-SERVER}} is done building the package, installing the
  294. package automatically downloads binaries from there
  295. (@pxref{Substitutes}). The only place where human intervention is
  296. needed is to review and apply the patch.
  297. @menu
  298. * Software Freedom:: What may go into the distribution.
  299. * Package Naming:: What's in a name?
  300. * Version Numbers:: When the name is not enough.
  301. * Synopses and Descriptions:: Helping users find the right package.
  302. * Python Modules:: A touch of British comedy.
  303. * Perl Modules:: Little pearls.
  304. * Java Packages:: Coffee break.
  305. * Rust Crates:: Beware of oxidation.
  306. * Fonts:: Fond of fonts.
  307. @end menu
  308. @node Software Freedom
  309. @subsection Software Freedom
  310. @c Adapted from http://www.gnu.org/philosophy/philosophy.html.
  311. @cindex free software
  312. The GNU operating system has been developed so that users can have
  313. freedom in their computing. GNU is @dfn{free software}, meaning that
  314. users have the @url{https://www.gnu.org/philosophy/free-sw.html,four
  315. essential freedoms}: to run the program, to study and change the program
  316. in source code form, to redistribute exact copies, and to distribute
  317. modified versions. Packages found in the GNU distribution provide only
  318. software that conveys these four freedoms.
  319. In addition, the GNU distribution follow the
  320. @url{https://www.gnu.org/distros/free-system-distribution-guidelines.html,free
  321. software distribution guidelines}. Among other things, these guidelines
  322. reject non-free firmware, recommendations of non-free software, and
  323. discuss ways to deal with trademarks and patents.
  324. Some otherwise free upstream package sources contain a small and optional
  325. subset that violates the above guidelines, for instance because this subset
  326. is itself non-free code. When that happens, the offending items are removed
  327. with appropriate patches or code snippets in the @code{origin} form of the
  328. package (@pxref{Defining Packages}). This way, @code{guix
  329. build --source} returns the ``freed'' source rather than the unmodified
  330. upstream source.
  331. @node Package Naming
  332. @subsection Package Naming
  333. @cindex package name
  334. A package has actually two names associated with it:
  335. First, there is the name of the @emph{Scheme variable}, the one following
  336. @code{define-public}. By this name, the package can be made known in the
  337. Scheme code, for instance as input to another package. Second, there is
  338. the string in the @code{name} field of a package definition. This name
  339. is used by package management commands such as
  340. @command{guix package} and @command{guix build}.
  341. Both are usually the same and correspond to the lowercase conversion of
  342. the project name chosen upstream, with underscores replaced with
  343. hyphens. For instance, GNUnet is available as @code{gnunet}, and
  344. SDL_net as @code{sdl-net}.
  345. We do not add @code{lib} prefixes for library packages, unless these are
  346. already part of the official project name. But @pxref{Python
  347. Modules} and @ref{Perl Modules} for special rules concerning modules for
  348. the Python and Perl languages.
  349. Font package names are handled differently, @pxref{Fonts}.
  350. @node Version Numbers
  351. @subsection Version Numbers
  352. @cindex package version
  353. We usually package only the latest version of a given free software
  354. project. But sometimes, for instance for incompatible library versions,
  355. two (or more) versions of the same package are needed. These require
  356. different Scheme variable names. We use the name as defined
  357. in @ref{Package Naming}
  358. for the most recent version; previous versions use the same name, suffixed
  359. by @code{-} and the smallest prefix of the version number that may
  360. distinguish the two versions.
  361. The name inside the package definition is the same for all versions of a
  362. package and does not contain any version number.
  363. For instance, the versions 2.24.20 and 3.9.12 of GTK+ may be packaged as follows:
  364. @lisp
  365. (define-public gtk+
  366. (package
  367. (name "gtk+")
  368. (version "3.9.12")
  369. ...))
  370. (define-public gtk+-2
  371. (package
  372. (name "gtk+")
  373. (version "2.24.20")
  374. ...))
  375. @end lisp
  376. If we also wanted GTK+ 3.8.2, this would be packaged as
  377. @lisp
  378. (define-public gtk+-3.8
  379. (package
  380. (name "gtk+")
  381. (version "3.8.2")
  382. ...))
  383. @end lisp
  384. @c See <https://lists.gnu.org/archive/html/guix-devel/2016-01/msg00425.html>,
  385. @c for a discussion of what follows.
  386. @cindex version number, for VCS snapshots
  387. Occasionally, we package snapshots of upstream's version control system
  388. (VCS) instead of formal releases. This should remain exceptional,
  389. because it is up to upstream developers to clarify what the stable
  390. release is. Yet, it is sometimes necessary. So, what should we put in
  391. the @code{version} field?
  392. Clearly, we need to make the commit identifier of the VCS snapshot
  393. visible in the version string, but we also need to make sure that the
  394. version string is monotonically increasing so that @command{guix package
  395. --upgrade} can determine which version is newer. Since commit
  396. identifiers, notably with Git, are not monotonically increasing, we add
  397. a revision number that we increase each time we upgrade to a newer
  398. snapshot. The resulting version string looks like this:
  399. @example
  400. 2.0.11-3.cabba9e
  401. ^ ^ ^
  402. | | `-- upstream commit ID
  403. | |
  404. | `--- Guix package revision
  405. |
  406. latest upstream version
  407. @end example
  408. It is a good idea to strip commit identifiers in the @code{version}
  409. field to, say, 7 digits. It avoids an aesthetic annoyance (assuming
  410. aesthetics have a role to play here) as well as problems related to OS
  411. limits such as the maximum shebang length (127 bytes for the Linux
  412. kernel.) It is best to use the full commit identifiers in
  413. @code{origin}s, though, to avoid ambiguities. A typical package
  414. definition may look like this:
  415. @lisp
  416. (define my-package
  417. (let ((commit "c3f29bc928d5900971f65965feaae59e1272a3f7")
  418. (revision "1")) ;Guix package revision
  419. (package
  420. (version (git-version "0.9" revision commit))
  421. (source (origin
  422. (method git-fetch)
  423. (uri (git-reference
  424. (url "git://example.org/my-package.git")
  425. (commit commit)))
  426. (sha256 (base32 "1mbikn@dots{}"))
  427. (file-name (git-file-name name version))))
  428. ;; @dots{}
  429. )))
  430. @end lisp
  431. @node Synopses and Descriptions
  432. @subsection Synopses and Descriptions
  433. @cindex package description
  434. @cindex package synopsis
  435. As we have seen before, each package in GNU@tie{}Guix includes a
  436. synopsis and a description (@pxref{Defining Packages}). Synopses and
  437. descriptions are important: They are what @command{guix package
  438. --search} searches, and a crucial piece of information to help users
  439. determine whether a given package suits their needs. Consequently,
  440. packagers should pay attention to what goes into them.
  441. Synopses must start with a capital letter and must not end with a
  442. period. They must not start with ``a'' or ``the'', which usually does
  443. not bring anything; for instance, prefer ``File-frobbing tool'' over ``A
  444. tool that frobs files''. The synopsis should say what the package
  445. is---e.g., ``Core GNU utilities (file, text, shell)''---or what it is
  446. used for---e.g., the synopsis for GNU@tie{}grep is ``Print lines
  447. matching a pattern''.
  448. Keep in mind that the synopsis must be meaningful for a very wide
  449. audience. For example, ``Manipulate alignments in the SAM format''
  450. might make sense for a seasoned bioinformatics researcher, but might be
  451. fairly unhelpful or even misleading to a non-specialized audience. It
  452. is a good idea to come up with a synopsis that gives an idea of the
  453. application domain of the package. In this example, this might give
  454. something like ``Manipulate nucleotide sequence alignments'', which
  455. hopefully gives the user a better idea of whether this is what they are
  456. looking for.
  457. Descriptions should take between five and ten lines. Use full
  458. sentences, and avoid using acronyms without first introducing them.
  459. Please avoid marketing phrases such as ``world-leading'',
  460. ``industrial-strength'', and ``next-generation'', and avoid superlatives
  461. like ``the most advanced''---they are not helpful to users looking for a
  462. package and may even sound suspicious. Instead, try to be factual,
  463. mentioning use cases and features.
  464. @cindex Texinfo markup, in package descriptions
  465. Descriptions can include Texinfo markup, which is useful to introduce
  466. ornaments such as @code{@@code} or @code{@@dfn}, bullet lists, or
  467. hyperlinks (@pxref{Overview,,, texinfo, GNU Texinfo}). However you
  468. should be careful when using some characters for example @samp{@@} and
  469. curly braces which are the basic special characters in Texinfo
  470. (@pxref{Special Characters,,, texinfo, GNU Texinfo}). User interfaces
  471. such as @command{guix package --show} take care of rendering it
  472. appropriately.
  473. Synopses and descriptions are translated by volunteers
  474. @uref{https://translationproject.org/domain/guix-packages.html, at the
  475. Translation Project} so that as many users as possible can read them in
  476. their native language. User interfaces search them and display them in
  477. the language specified by the current locale.
  478. To allow @command{xgettext} to extract them as translatable strings,
  479. synopses and descriptions @emph{must be literal strings}. This means
  480. that you cannot use @code{string-append} or @code{format} to construct
  481. these strings:
  482. @lisp
  483. (package
  484. ;; @dots{}
  485. (synopsis "This is translatable")
  486. (description (string-append "This is " "*not*" " translatable.")))
  487. @end lisp
  488. Translation is a lot of work so, as a packager, please pay even more
  489. attention to your synopses and descriptions as every change may entail
  490. additional work for translators. In order to help them, it is possible
  491. to make recommendations or instructions visible to them by inserting
  492. special comments like this (@pxref{xgettext Invocation,,, gettext, GNU
  493. Gettext}):
  494. @example
  495. ;; TRANSLATORS: "X11 resize-and-rotate" should not be translated.
  496. (description "ARandR is designed to provide a simple visual front end
  497. for the X11 resize-and-rotate (RandR) extension. @dots{}")
  498. @end example
  499. @node Python Modules
  500. @subsection Python Modules
  501. @cindex python
  502. We currently package Python 2 and Python 3, under the Scheme variable names
  503. @code{python-2} and @code{python} as explained in @ref{Version Numbers}.
  504. To avoid confusion and naming clashes with other programming languages, it
  505. seems desirable that the name of a package for a Python module contains
  506. the word @code{python}.
  507. Some modules are compatible with only one version of Python, others with
  508. both. If the package Foo is compiled with Python 3, we name it
  509. @code{python-foo}. If it is compiled with Python 2, we name it
  510. @code{python2-foo}. Packages should be added when they are necessary;
  511. we don't add Python 2 variants of the package unless we are going to use
  512. them.
  513. If a project already contains the word @code{python}, we drop this;
  514. for instance, the module python-dateutil is packaged under the names
  515. @code{python-dateutil} and @code{python2-dateutil}. If the project name
  516. starts with @code{py} (e.g.@: @code{pytz}), we keep it and prefix it as
  517. described above.
  518. @subsubsection Specifying Dependencies
  519. @cindex inputs, for Python packages
  520. Dependency information for Python packages is usually available in the
  521. package source tree, with varying degrees of accuracy: in the
  522. @file{setup.py} file, in @file{requirements.txt}, or in @file{tox.ini}.
  523. Your mission, when writing a recipe for a Python package, is to map
  524. these dependencies to the appropriate type of ``input'' (@pxref{package
  525. Reference, inputs}). Although the @code{pypi} importer normally does a
  526. good job (@pxref{Invoking guix import}), you may want to check the
  527. following check list to determine which dependency goes where.
  528. @itemize
  529. @item
  530. We currently package Python 2 with @code{setuptools} and @code{pip}
  531. installed like Python 3.4 has per default. Thus you don't need to
  532. specify either of these as an input. @command{guix lint} will warn you
  533. if you do.
  534. @item
  535. Python dependencies required at run time go into
  536. @code{propagated-inputs}. They are typically defined with the
  537. @code{install_requires} keyword in @file{setup.py}, or in the
  538. @file{requirements.txt} file.
  539. @item
  540. Python packages required only at build time---e.g., those listed with
  541. the @code{setup_requires} keyword in @file{setup.py}---or only for
  542. testing---e.g., those in @code{tests_require}---go into
  543. @code{native-inputs}. The rationale is that (1) they do not need to be
  544. propagated because they are not needed at run time, and (2) in a
  545. cross-compilation context, it's the ``native'' input that we'd want.
  546. Examples are the @code{pytest}, @code{mock}, and @code{nose} test
  547. frameworks. Of course if any of these packages is also required at
  548. run-time, it needs to go to @code{propagated-inputs}.
  549. @item
  550. Anything that does not fall in the previous categories goes to
  551. @code{inputs}, for example programs or C libraries required for building
  552. Python packages containing C extensions.
  553. @item
  554. If a Python package has optional dependencies (@code{extras_require}),
  555. it is up to you to decide whether to add them or not, based on their
  556. usefulness/overhead ratio (@pxref{Submitting Patches, @command{guix
  557. size}}).
  558. @end itemize
  559. @node Perl Modules
  560. @subsection Perl Modules
  561. @cindex perl
  562. Perl programs standing for themselves are named as any other package,
  563. using the lowercase upstream name.
  564. For Perl packages containing a single class, we use the lowercase class name,
  565. replace all occurrences of @code{::} by dashes and prepend the prefix
  566. @code{perl-}.
  567. So the class @code{XML::Parser} becomes @code{perl-xml-parser}.
  568. Modules containing several classes keep their lowercase upstream name and
  569. are also prepended by @code{perl-}. Such modules tend to have the word
  570. @code{perl} somewhere in their name, which gets dropped in favor of the
  571. prefix. For instance, @code{libwww-perl} becomes @code{perl-libwww}.
  572. @node Java Packages
  573. @subsection Java Packages
  574. @cindex java
  575. Java programs standing for themselves are named as any other package,
  576. using the lowercase upstream name.
  577. To avoid confusion and naming clashes with other programming languages,
  578. it is desirable that the name of a package for a Java package is
  579. prefixed with @code{java-}. If a project already contains the word
  580. @code{java}, we drop this; for instance, the package @code{ngsjava} is
  581. packaged under the name @code{java-ngs}.
  582. For Java packages containing a single class or a small class hierarchy,
  583. we use the lowercase class name, replace all occurrences of @code{.} by
  584. dashes and prepend the prefix @code{java-}. So the class
  585. @code{apache.commons.cli} becomes package
  586. @code{java-apache-commons-cli}.
  587. @node Rust Crates
  588. @subsection Rust Crates
  589. @cindex rust
  590. Rust programs standing for themselves are named as any other package, using the
  591. lowercase upstream name.
  592. To prevent namespace collisions we prefix all other Rust packages with the
  593. @code{rust-} prefix. The name should be changed to lowercase as appropriate and
  594. dashes should remain in place.
  595. In the rust ecosystem it is common for multiple incompatible versions of a
  596. package to be used at any given time, so all packages should have a versioned
  597. suffix. If a package has passed version 1.0.0 then just the major version
  598. number is sufficient (e.g.@: @code{rust-clap-2}), otherwise the version suffix
  599. should contain both the major and minor version (e.g.@: @code{rust-rand-0.6}).
  600. Because of the difficulty in reusing rust packages as pre-compiled inputs for
  601. other packages the Cargo build system (@pxref{Build Systems,
  602. @code{cargo-build-system}}) presents the @code{#:cargo-inputs} and
  603. @code{cargo-development-inputs} keywords as build system arguments. It would be
  604. helpful to think of these as similar to @code{propagated-inputs} and
  605. @code{native-inputs}. Rust @code{dependencies} and @code{build-dependencies}
  606. should go in @code{#:cargo-inputs}, and @code{dev-dependencies} should go in
  607. @code{#:cargo-development-inputs}. If a Rust package links to other libraries
  608. then the standard placement in @code{inputs} and the like should be used.
  609. Care should be taken to ensure the correct version of dependencies are used; to
  610. this end we try to refrain from skipping the tests or using @code{#:skip-build?}
  611. when possible. Of course this is not always possible, as the package may be
  612. developed for a different Operating System, depend on features from the Nightly
  613. Rust compiler, or the test suite may have atrophied since it was released.
  614. @node Fonts
  615. @subsection Fonts
  616. @cindex fonts
  617. For fonts that are in general not installed by a user for typesetting
  618. purposes, or that are distributed as part of a larger software package,
  619. we rely on the general packaging rules for software; for instance, this
  620. applies to the fonts delivered as part of the X.Org system or fonts that
  621. are part of TeX Live.
  622. To make it easier for a user to search for fonts, names for other packages
  623. containing only fonts are constructed as follows, independently of the
  624. upstream package name.
  625. The name of a package containing only one font family starts with
  626. @code{font-}; it is followed by the foundry name and a dash @code{-}
  627. if the foundry is known, and the font family name, in which spaces are
  628. replaced by dashes (and as usual, all upper case letters are transformed
  629. to lower case).
  630. For example, the Gentium font family by SIL is packaged under the name
  631. @code{font-sil-gentium}.
  632. For a package containing several font families, the name of the collection
  633. is used in the place of the font family name.
  634. For instance, the Liberation fonts consist of three families,
  635. Liberation Sans, Liberation Serif and Liberation Mono.
  636. These could be packaged separately under the names
  637. @code{font-liberation-sans} and so on; but as they are distributed together
  638. under a common name, we prefer to package them together as
  639. @code{font-liberation}.
  640. In the case where several formats of the same font family or font collection
  641. are packaged separately, a short form of the format, prepended by a dash,
  642. is added to the package name. We use @code{-ttf} for TrueType fonts,
  643. @code{-otf} for OpenType fonts and @code{-type1} for PostScript Type 1
  644. fonts.
  645. @node Coding Style
  646. @section Coding Style
  647. In general our code follows the GNU Coding Standards (@pxref{Top,,,
  648. standards, GNU Coding Standards}). However, they do not say much about
  649. Scheme, so here are some additional rules.
  650. @menu
  651. * Programming Paradigm:: How to compose your elements.
  652. * Modules:: Where to store your code?
  653. * Data Types and Pattern Matching:: Implementing data structures.
  654. * Formatting Code:: Writing conventions.
  655. @end menu
  656. @node Programming Paradigm
  657. @subsection Programming Paradigm
  658. Scheme code in Guix is written in a purely functional style. One
  659. exception is code that involves input/output, and procedures that
  660. implement low-level concepts, such as the @code{memoize} procedure.
  661. @node Modules
  662. @subsection Modules
  663. Guile modules that are meant to be used on the builder side must live in
  664. the @code{(guix build @dots{})} name space. They must not refer to
  665. other Guix or GNU modules. However, it is OK for a ``host-side'' module
  666. to use a build-side module.
  667. Modules that deal with the broader GNU system should be in the
  668. @code{(gnu @dots{})} name space rather than @code{(guix @dots{})}.
  669. @node Data Types and Pattern Matching
  670. @subsection Data Types and Pattern Matching
  671. The tendency in classical Lisp is to use lists to represent everything,
  672. and then to browse them ``by hand'' using @code{car}, @code{cdr},
  673. @code{cadr}, and co. There are several problems with that style,
  674. notably the fact that it is hard to read, error-prone, and a hindrance
  675. to proper type error reports.
  676. Guix code should define appropriate data types (for instance, using
  677. @code{define-record-type*}) rather than abuse lists. In addition, it
  678. should use pattern matching, via Guile’s @code{(ice-9 match)} module,
  679. especially when matching lists.
  680. @node Formatting Code
  681. @subsection Formatting Code
  682. @cindex formatting code
  683. @cindex coding style
  684. When writing Scheme code, we follow common wisdom among Scheme
  685. programmers. In general, we follow the
  686. @url{https://mumble.net/~campbell/scheme/style.txt, Riastradh's Lisp
  687. Style Rules}. This document happens to describe the conventions mostly
  688. used in Guile’s code too. It is very thoughtful and well written, so
  689. please do read it.
  690. Some special forms introduced in Guix, such as the @code{substitute*}
  691. macro, have special indentation rules. These are defined in the
  692. @file{.dir-locals.el} file, which Emacs automatically uses. Also note
  693. that Emacs-Guix provides @code{guix-devel-mode} mode that indents and
  694. highlights Guix code properly (@pxref{Development,,, emacs-guix, The
  695. Emacs-Guix Reference Manual}).
  696. @cindex indentation, of code
  697. @cindex formatting, of code
  698. If you do not use Emacs, please make sure to let your editor knows these
  699. rules. To automatically indent a package definition, you can also run:
  700. @example
  701. ./etc/indent-code.el gnu/packages/@var{file}.scm @var{package}
  702. @end example
  703. @noindent
  704. This automatically indents the definition of @var{package} in
  705. @file{gnu/packages/@var{file}.scm} by running Emacs in batch mode. To
  706. indent a whole file, omit the second argument:
  707. @example
  708. ./etc/indent-code.el gnu/services/@var{file}.scm
  709. @end example
  710. @cindex Vim, Scheme code editing
  711. If you are editing code with Vim, we recommend that you run @code{:set
  712. autoindent} so that your code is automatically indented as you type.
  713. Additionally,
  714. @uref{https://www.vim.org/scripts/script.php?script_id=3998,
  715. @code{paredit.vim}} may help you deal with all these parentheses.
  716. We require all top-level procedures to carry a docstring. This
  717. requirement can be relaxed for simple private procedures in the
  718. @code{(guix build @dots{})} name space, though.
  719. Procedures should not have more than four positional parameters. Use
  720. keyword parameters for procedures that take more than four parameters.
  721. @node Submitting Patches
  722. @section Submitting Patches
  723. Development is done using the Git distributed version control system.
  724. Thus, access to the repository is not strictly necessary. We welcome
  725. contributions in the form of patches as produced by @code{git
  726. format-patch} sent to the @email{guix-patches@@gnu.org} mailing list.
  727. Seasoned Guix developers may also want to look at the section on commit
  728. access (@pxref{Commit Access}).
  729. This mailing list is backed by a Debbugs instance, which allows us to
  730. keep track of submissions (@pxref{Tracking Bugs and Patches}). Each
  731. message sent to that mailing list gets a new tracking number assigned;
  732. people can then follow up on the submission by sending email to
  733. @code{@var{NNN}@@debbugs.gnu.org}, where @var{NNN} is the tracking
  734. number (@pxref{Sending a Patch Series}).
  735. Please write commit logs in the ChangeLog format (@pxref{Change Logs,,,
  736. standards, GNU Coding Standards}); you can check the commit history for
  737. examples.
  738. Before submitting a patch that adds or modifies a package definition,
  739. please run through this check list:
  740. @enumerate
  741. @item
  742. If the authors of the packaged software provide a cryptographic
  743. signature for the release tarball, make an effort to verify the
  744. authenticity of the archive. For a detached GPG signature file this
  745. would be done with the @code{gpg --verify} command.
  746. @item
  747. Take some time to provide an adequate synopsis and description for the
  748. package. @xref{Synopses and Descriptions}, for some guidelines.
  749. @item
  750. Run @code{guix lint @var{package}}, where @var{package} is the
  751. name of the new or modified package, and fix any errors it reports
  752. (@pxref{Invoking guix lint}).
  753. @item
  754. Make sure the package builds on your platform, using @code{guix build
  755. @var{package}}.
  756. @item
  757. We recommend you also try building the package on other supported
  758. platforms. As you may not have access to actual hardware platforms, we
  759. recommend using the @code{qemu-binfmt-service-type} to emulate them. In
  760. order to enable it, add the following service to the list of services in
  761. your @code{operating-system} configuration:
  762. @lisp
  763. (service qemu-binfmt-service-type
  764. (qemu-binfmt-configuration
  765. (platforms (lookup-qemu-platforms "arm" "aarch64" "mips64el"))
  766. (guix-support? #t)))
  767. @end lisp
  768. Then reconfigure your system.
  769. You can then build packages for different platforms by specifying the
  770. @code{--system} option. For example, to build the "hello" package for
  771. the armhf, aarch64, or mips64 architectures, you would run the following
  772. commands, respectively:
  773. @example
  774. guix build --system=armhf-linux --rounds=2 hello
  775. guix build --system=aarch64-linux --rounds=2 hello
  776. guix build --system=mips64el-linux --rounds=2 hello
  777. @end example
  778. @item
  779. @cindex bundling
  780. Make sure the package does not use bundled copies of software already
  781. available as separate packages.
  782. Sometimes, packages include copies of the source code of their
  783. dependencies as a convenience for users. However, as a distribution, we
  784. want to make sure that such packages end up using the copy we already
  785. have in the distribution, if there is one. This improves resource usage
  786. (the dependency is built and stored only once), and allows the
  787. distribution to make transverse changes such as applying security
  788. updates for a given software package in a single place and have them
  789. affect the whole system---something that bundled copies prevent.
  790. @item
  791. Take a look at the profile reported by @command{guix size}
  792. (@pxref{Invoking guix size}). This will allow you to notice references
  793. to other packages unwillingly retained. It may also help determine
  794. whether to split the package (@pxref{Packages with Multiple Outputs}),
  795. and which optional dependencies should be used. In particular, avoid adding
  796. @code{texlive} as a dependency: because of its extreme size, use
  797. @code{texlive-tiny} or @code{texlive-union} instead.
  798. @item
  799. For important changes, check that dependent package (if applicable) are
  800. not affected by the change; @code{guix refresh --list-dependent
  801. @var{package}} will help you do that (@pxref{Invoking guix refresh}).
  802. @c See <https://lists.gnu.org/archive/html/guix-devel/2016-10/msg00933.html>.
  803. @cindex branching strategy
  804. @cindex rebuild scheduling strategy
  805. Depending on the number of dependent packages and thus the amount of
  806. rebuilding induced, commits go to different branches, along these lines:
  807. @table @asis
  808. @item 300 dependent packages or less
  809. @code{master} branch (non-disruptive changes).
  810. @item between 300 and 1,200 dependent packages
  811. @code{staging} branch (non-disruptive changes). This branch is intended
  812. to be merged in @code{master} every 3 weeks or so. Topical changes
  813. (e.g., an update of the GNOME stack) can instead go to a specific branch
  814. (say, @code{gnome-updates}).
  815. @item more than 1,200 dependent packages
  816. @code{core-updates} branch (may include major and potentially disruptive
  817. changes). This branch is intended to be merged in @code{master} every
  818. 2.5 months or so.
  819. @end table
  820. All these branches are @uref{@value{SUBSTITUTE-SERVER},
  821. tracked by our build farm} and merged into @code{master} once
  822. everything has been successfully built. This allows us to fix issues
  823. before they hit users, and to reduce the window during which pre-built
  824. binaries are not available.
  825. Generally, branches other than @code{master} are considered
  826. @emph{frozen} if there has been a recent evaluation, or there is a
  827. corresponding @code{-next} branch. Please ask on the mailing list or
  828. IRC if unsure where to place a patch.
  829. @c TODO: It would be good with badges on the website that tracks these
  830. @c branches. Or maybe even a status page.
  831. @item
  832. @cindex determinism, of build processes
  833. @cindex reproducible builds, checking
  834. Check whether the package's build process is deterministic. This
  835. typically means checking whether an independent build of the package
  836. yields the exact same result that you obtained, bit for bit.
  837. A simple way to do that is by building the same package several times in
  838. a row on your machine (@pxref{Invoking guix build}):
  839. @example
  840. guix build --rounds=2 my-package
  841. @end example
  842. This is enough to catch a class of common non-determinism issues, such
  843. as timestamps or randomly-generated output in the build result.
  844. Another option is to use @command{guix challenge} (@pxref{Invoking guix
  845. challenge}). You may run it once the package has been committed and
  846. built by @code{@value{SUBSTITUTE-SERVER}} to check whether it obtains the same
  847. result as you did. Better yet: Find another machine that can build it
  848. and run @command{guix publish}. Since the remote build machine is
  849. likely different from yours, this can catch non-determinism issues
  850. related to the hardware---e.g., use of different instruction set
  851. extensions---or to the operating system kernel---e.g., reliance on
  852. @code{uname} or @file{/proc} files.
  853. @item
  854. When writing documentation, please use gender-neutral wording when
  855. referring to people, such as
  856. @uref{https://en.wikipedia.org/wiki/Singular_they, singular
  857. ``they''@comma{} ``their''@comma{} ``them''}, and so forth.
  858. @item
  859. Verify that your patch contains only one set of related changes.
  860. Bundling unrelated changes together makes reviewing harder and slower.
  861. Examples of unrelated changes include the addition of several packages,
  862. or a package update along with fixes to that package.
  863. @item
  864. Please follow our code formatting rules, possibly running the
  865. @command{etc/indent-code.el} script to do that automatically for you
  866. (@pxref{Formatting Code}).
  867. @item
  868. When possible, use mirrors in the source URL (@pxref{Invoking guix download}).
  869. Use reliable URLs, not generated ones. For instance, GitHub archives are not
  870. necessarily identical from one generation to the next, so in this case it's
  871. often better to clone the repository. Don't use the @command{name} field in
  872. the URL: it is not very useful and if the name changes, the URL will probably
  873. be wrong.
  874. @item
  875. Check if Guix builds (@pxref{Building from Git}) and address the
  876. warnings, especially those about use of undefined symbols.
  877. @item
  878. Make sure your changes do not break Guix and simulate a @code{guix pull} with:
  879. @example
  880. guix pull --url=/path/to/your/checkout --profile=/tmp/guix.master
  881. @end example
  882. @end enumerate
  883. When posting a patch to the mailing list, use @samp{[PATCH] @dots{}} as
  884. a subject. You may use your email client or the @command{git
  885. send-email} command (@pxref{Sending a Patch Series}). We prefer to get
  886. patches in plain text messages, either inline or as MIME attachments.
  887. You are advised to pay attention if your email client changes anything
  888. like line breaks or indentation which could potentially break the
  889. patches.
  890. When a bug is resolved, please close the thread by sending an email to
  891. @email{@var{NNN}-done@@debbugs.gnu.org}.
  892. @unnumberedsubsec Sending a Patch Series
  893. @anchor{Sending a Patch Series}
  894. @cindex patch series
  895. @cindex @code{git send-email}
  896. @cindex @code{git-send-email}
  897. When sending a patch series (e.g., using @code{git send-email}), please
  898. first send one message to @email{guix-patches@@gnu.org}, and then send
  899. subsequent patches to @email{@var{NNN}@@debbugs.gnu.org} to make sure
  900. they are kept together. See
  901. @uref{https://debbugs.gnu.org/Advanced.html, the Debbugs documentation}
  902. for more information. You can install @command{git send-email} with
  903. @command{guix install git:send-email}.
  904. @c Debbugs bug: https://debbugs.gnu.org/db/15/15361.html
  905. @node Tracking Bugs and Patches
  906. @section Tracking Bugs and Patches
  907. @cindex bug reports, tracking
  908. @cindex patch submissions, tracking
  909. @cindex issue tracking
  910. @cindex Debbugs, issue tracking system
  911. Bug reports and patch submissions are currently tracked using the
  912. Debbugs instance at @uref{https://bugs.gnu.org}. Bug reports are filed
  913. against the @code{guix} ``package'' (in Debbugs parlance), by sending
  914. email to @email{bug-guix@@gnu.org}, while patch submissions are filed
  915. against the @code{guix-patches} package by sending email to
  916. @email{guix-patches@@gnu.org} (@pxref{Submitting Patches}).
  917. A web interface (actually @emph{two} web interfaces!) are available to
  918. browse issues:
  919. @itemize
  920. @item
  921. @url{https://bugs.gnu.org/guix} lists bug reports;
  922. @item
  923. @url{https://bugs.gnu.org/guix-patches} lists patch submissions.
  924. @end itemize
  925. You can also access both of these @i{via} the (nicer)
  926. @url{https://issues.guix.gnu.org} interface@footnote{The web interface
  927. at @url{https://issues.guix.gnu.org} is powered by Mumi, a nice piece of
  928. software written in Guile, and you can help! See
  929. @url{https://git.elephly.net/gitweb.cgi?p=software/mumi.git}.}. To view
  930. discussions related to issue number @var{n}, go to
  931. @indicateurl{https://issues.guix.gnu.org/issue/@var{n}} or
  932. @indicateurl{https://bugs.gnu.org/@var{n}}.
  933. If you use Emacs, you may find it more convenient to interact with
  934. issues using @file{debbugs.el}, which you can install with:
  935. @example
  936. guix install emacs-debbugs
  937. @end example
  938. For example, to list all open issues on @code{guix-patches}, hit:
  939. @example
  940. @kbd{C-u} @kbd{M-x} debbugs-gnu @kbd{RET} @kbd{RET} guix-patches @kbd{RET} n y
  941. @end example
  942. @xref{Top,,, debbugs-ug, Debbugs User Guide}, for more information on
  943. this nifty tool!
  944. @node Commit Access
  945. @section Commit Access
  946. @cindex commit access, for developers
  947. For frequent contributors, having write access to the repository is
  948. convenient. When you deem it necessary, consider applying for commit
  949. access by following these steps:
  950. @enumerate
  951. @item
  952. Find three committers who would vouch for you. You can view the list of
  953. committers at
  954. @url{https://savannah.gnu.org/project/memberlist.php?group=guix}. Each
  955. of them should email a statement to @email{guix-maintainers@@gnu.org} (a
  956. private alias for the collective of maintainers), signed with their
  957. OpenPGP key.
  958. Committers are expected to have had some interactions with you as a
  959. contributor and to be able to judge whether you are sufficiently
  960. familiar with the project's practices. It is @emph{not} a judgment on
  961. the value of your work, so a refusal should rather be interpreted as
  962. ``let's try again later''.
  963. @item
  964. Send @email{guix-maintainers@@gnu.org} a message stating your intent,
  965. listing the three committers who support your application, signed with
  966. the OpenPGP key you will use to sign commits, and giving its fingerprint
  967. (see below). See @uref{https://emailselfdefense.fsf.org/en/}, for an
  968. introduction to public-key cryptography with GnuPG.
  969. @item
  970. Maintainers ultimately decide whether to grant you commit access,
  971. usually following your referrals' recommendation.
  972. @item
  973. If and once you've been given access, please send a message to
  974. @email{guix-devel@@gnu.org} to say so, again signed with the OpenPGP key
  975. you will use to sign commits (do that before pushing your first commit).
  976. That way, everyone can notice and ensure you control that OpenPGP key.
  977. @c TODO: Add note about adding the fingerprint to the list of authorized
  978. @c keys once that has stabilized.
  979. @item
  980. Make sure to read the rest of this section and... profit!
  981. @end enumerate
  982. @quotation Note
  983. Maintainers are happy to give commit access to people who have been
  984. contributing for some time and have a track record---don't be shy and
  985. don't underestimate your work!
  986. However, note that the project is working towards a more automated patch
  987. review and merging system, which, as a consequence, may lead us to have
  988. fewer people with commit access to the main repository. Stay tuned!
  989. @end quotation
  990. If you get commit access, please make sure to follow
  991. the policy below (discussions of the policy can take place on
  992. @email{guix-devel@@gnu.org}).
  993. Non-trivial patches should always be posted to
  994. @email{guix-patches@@gnu.org} (trivial patches include fixing typos,
  995. etc.). This mailing list fills the patch-tracking database
  996. (@pxref{Tracking Bugs and Patches}).
  997. For patches that just add a new package, and a simple one, it's OK to
  998. commit, if you're confident (which means you successfully built it in a
  999. chroot setup, and have done a reasonable copyright and license
  1000. auditing). Likewise for package upgrades, except upgrades that trigger
  1001. a lot of rebuilds (for example, upgrading GnuTLS or GLib). We have a
  1002. mailing list for commit notifications (@email{guix-commits@@gnu.org}),
  1003. so people can notice. Before pushing your changes, make sure to run
  1004. @code{git pull --rebase}.
  1005. All commits that are pushed to the central repository on Savannah must
  1006. be signed with an OpenPGP key, and the public key should be uploaded to
  1007. your user account on Savannah and to public key servers, such as
  1008. @code{keys.openpgp.org}. To configure Git to automatically sign
  1009. commits, run:
  1010. @example
  1011. git config commit.gpgsign true
  1012. git config user.signingkey CABBA6EA1DC0FF33
  1013. @end example
  1014. You can prevent yourself from accidentally pushing unsigned commits to
  1015. Savannah by using the pre-push Git hook called located at
  1016. @file{etc/git/pre-push}:
  1017. @example
  1018. cp etc/git/pre-push .git/hooks/pre-push
  1019. @end example
  1020. When pushing a commit on behalf of somebody else, please add a
  1021. @code{Signed-off-by} line at the end of the commit log message---e.g.,
  1022. with @command{git am --signoff}. This improves tracking of who did
  1023. what.
  1024. For anything else, please post to @email{guix-patches@@gnu.org} and
  1025. leave time for a review, without committing anything (@pxref{Submitting
  1026. Patches}). If you didn’t receive any reply after two weeks, and if
  1027. you're confident, it's OK to commit.
  1028. That last part is subject to being adjusted, allowing individuals to commit
  1029. directly on non-controversial changes on parts they’re familiar with.
  1030. One last thing: the project keeps moving forward because committers not
  1031. only push their own awesome changes, but also offer some of their time
  1032. @emph{reviewing} and pushing other people's changes. As a committer,
  1033. you're welcome to use your expertise and commit rights to help other
  1034. contributors, too!