4 This project is a cooperative effort, and we need your help to make it
5 grow! Please get in touch with us on @email{guix-devel@@gnu.org} and
6 @code{#guix} on the Freenode IRC network. We welcome ideas, bug
7 reports, patches, and anything that may be helpful to the project. We
8 particularly welcome help on packaging (@pxref{Packaging Guidelines}).
10 @cindex code of conduct, of contributors
11 @cindex contributor covenant
12 We want to provide a warm, friendly, and harassment-free environment, so
13 that anyone can contribute to the best of their abilities. To this end
14 our project uses a ``Contributor Covenant'', which was adapted from
15 @url{https://contributor-covenant.org/}. You can find a local version in
16 the @file{CODE-OF-CONDUCT} file in the source tree.
18 Contributors are not required to use their legal name in patches and
19 on-line communication; they can use any name or pseudonym of their
23 * Building from Git:: The latest and greatest.
24 * Running Guix Before It Is Installed:: Hacker tricks.
25 * The Perfect Setup:: The right tools.
26 * Packaging Guidelines:: Growing the distribution.
27 * Coding Style:: Hygiene of the contributor.
28 * Submitting Patches:: Share your work.
29 * Tracking Bugs and Patches:: Using Debbugs.
30 * Commit Access:: Pushing to the official repository.
31 * Updating the Guix Package:: Updating the Guix package definition.
34 @node Building from Git
35 @section Building from Git
37 If you want to hack Guix itself, it is recommended to use the latest
38 version from the Git repository:
41 git clone https://git.savannah.gnu.org/git/guix.git
44 @cindex authentication, of a Guix checkout
45 How do you ensure that you obtained a genuine copy of the repository?
46 To do that, run @command{guix git authenticate}, passing it the commit
47 and OpenPGP fingerprint of the @dfn{channel introduction}
48 (@pxref{Invoking guix git authenticate}):
50 @c The commit and fingerprint below must match those of the channel
51 @c introduction in '%default-channels'.
53 git fetch origin keyring:keyring
54 guix git authenticate 9edb3f66fd807b096b48283debdcddccfea34bad \
55 "BBB0 2DDF 2CEA F6A8 0D1D E643 A2A0 6DF2 A33A 54FA"
59 This command completes with exit code zero on success; it prints an
60 error message and exits with a non-zero code otherwise.
62 As you can see, there is a chicken-and-egg problem: you first need to
63 have Guix installed. Typically you would install Guix System
64 (@pxref{System Installation}) or Guix on top of another distro
65 (@pxref{Binary Installation}); in either case, you would verify the
66 OpenPGP signature on the installation medium. This ``bootstraps'' the
69 The easiest way to set up a development environment for Guix is, of
70 course, by using Guix! The following command starts a new shell where
71 all the dependencies and appropriate environment variables are set up to
75 guix environment guix --pure
78 @xref{Invoking guix environment}, for more information on that command.
80 If you are unable to use Guix when building Guix from a checkout, the
81 following are the required packages in addition to those mentioned in the
82 installation instructions (@pxref{Requirements}).
85 @item @url{https://gnu.org/software/autoconf/, GNU Autoconf};
86 @item @url{https://gnu.org/software/automake/, GNU Automake};
87 @item @url{https://gnu.org/software/gettext/, GNU Gettext};
88 @item @url{https://gnu.org/software/texinfo/, GNU Texinfo};
89 @item @url{https://www.graphviz.org/, Graphviz};
90 @item @url{https://www.gnu.org/software/help2man/, GNU Help2man (optional)}.
93 On Guix, extra dependencies can be added by instead running @command{guix
94 environment} with @option{--ad-hoc}:
97 guix environment guix --pure --ad-hoc help2man git strace
100 Run @command{./bootstrap} to generate the build system infrastructure
101 using Autoconf and Automake. If you get an error like this one:
104 configure.ac:46: error: possibly undefined macro: PKG_CHECK_MODULES
108 it probably means that Autoconf couldn’t find @file{pkg.m4}, which is
109 provided by pkg-config. Make sure that @file{pkg.m4} is available. The
110 same holds for the @file{guile.m4} set of macros provided by Guile. For
111 instance, if you installed Automake in @file{/usr/local}, it wouldn’t
112 look for @file{.m4} files in @file{/usr/share}. In that case, you have
113 to invoke the following command:
116 export ACLOCAL_PATH=/usr/share/aclocal
119 @xref{Macro Search Path,,, automake, The GNU Automake Manual}, for
122 Then, run @command{./configure} as usual. Make sure to pass
123 @code{--localstatedir=@var{directory}} where @var{directory} is the
124 @code{localstatedir} value used by your current installation (@pxref{The
125 Store}, for information about this), usually @file{/var}. Note that you
126 will probably not run @command{make install} at the end (you don't have
127 to) but it's still important to pass the right @code{localstatedir}.
129 Finally, you have to invoke @code{make check} to run tests
130 (@pxref{Running the Test Suite}). If anything
131 fails, take a look at installation instructions (@pxref{Installation})
132 or send a message to the @email{guix-devel@@gnu.org, mailing list}.
134 From there on, you can authenticate all the commits included in your
141 The first run takes a couple of minutes, but subsequent runs are faster.
143 Or, when your configuration for your local Git repository doesn't match
144 the default one, you can provide the reference for the @code{keyring}
145 branch through the variable @code{GUIX_GIT_KEYRING}. The following
146 example assumes that you have a Git remote called @samp{myremote}
147 pointing to the official repository:
150 make authenticate GUIX_GIT_KEYRING=myremote/keyring
154 You are advised to run @command{make authenticate} after every
155 @command{git pull} invocation. This ensures you keep receiving valid
156 changes to the repository.
160 @node Running Guix Before It Is Installed
161 @section Running Guix Before It Is Installed
163 In order to keep a sane working environment, you will find it useful to
164 test the changes made in your local source tree checkout without
165 actually installing them. So that you can distinguish between your
166 ``end-user'' hat and your ``motley'' costume.
168 To that end, all the command-line tools can be used even if you have not
169 run @code{make install}. To do that, you first need to have an
170 environment with all the dependencies available (@pxref{Building from
171 Git}), and then simply prefix each command with @command{./pre-inst-env}
172 (the @file{pre-inst-env} script lives in the top build tree of Guix; it
173 is generated by running @command{./bootstrap} followed by
174 @command{./configure}). As an example, here is how you would build the
175 @code{hello} package as defined in your working tree (this assumes
176 @command{guix-daemon} is already running on your system; it's OK if it's
177 a different version):
180 $ ./pre-inst-env guix build hello
184 Similarly, an example for a Guile session using the Guix modules:
187 $ ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))'
194 @cindex read-eval-print loop
195 @dots{} and for a REPL (@pxref{Using Guile Interactively,,, guile, Guile
199 $ ./pre-inst-env guile
200 scheme@@(guile-user)> ,use(guix)
201 scheme@@(guile-user)> ,use(gnu)
202 scheme@@(guile-user)> (define snakes
204 (lambda (package lst)
205 (if (string-prefix? "python"
206 (package-name package))
210 scheme@@(guile-user)> (length snakes)
214 If you are hacking on the daemon and its supporting code or if
215 @command{guix-daemon} is not already running on your system, you can
216 launch it straight from the build tree@footnote{The @option{-E} flag to
217 @command{sudo} guarantees that @code{GUILE_LOAD_PATH} is correctly set
218 such that @command{guix-daemon} and the tools it uses can find the Guile
222 $ sudo -E ./pre-inst-env guix-daemon --build-users-group=guixbuild
225 The @command{pre-inst-env} script sets up all the environment variables
226 necessary to support this, including @env{PATH} and @env{GUILE_LOAD_PATH}.
228 Note that @command{./pre-inst-env guix pull} does @emph{not} upgrade the
229 local source tree; it simply updates the @file{~/.config/guix/current}
230 symlink (@pxref{Invoking guix pull}). Run @command{git pull} instead if
231 you want to upgrade your local source tree.
234 @node The Perfect Setup
235 @section The Perfect Setup
237 The Perfect Setup to hack on Guix is basically the perfect setup used
238 for Guile hacking (@pxref{Using Guile in Emacs,,, guile, Guile Reference
239 Manual}). First, you need more than an editor, you need
240 @url{https://www.gnu.org/software/emacs, Emacs}, empowered by the
241 wonderful @url{https://nongnu.org/geiser/, Geiser}. To set that up, run:
244 guix package -i emacs guile emacs-geiser
247 Geiser allows for interactive and incremental development from within
248 Emacs: code compilation and evaluation from within buffers, access to
249 on-line documentation (docstrings), context-sensitive completion,
250 @kbd{M-.} to jump to an object definition, a REPL to try out your code,
251 and more (@pxref{Introduction,,, geiser, Geiser User Manual}). For
252 convenient Guix development, make sure to augment Guile’s load path so
253 that it finds source files from your checkout:
256 ;; @r{Assuming the Guix checkout is in ~/src/guix.}
257 (with-eval-after-load 'geiser-guile
258 (add-to-list 'geiser-guile-load-path "~/src/guix"))
261 To actually edit the code, Emacs already has a neat Scheme mode. But in
262 addition to that, you must not miss
263 @url{https://www.emacswiki.org/emacs/ParEdit, Paredit}. It provides
264 facilities to directly operate on the syntax tree, such as raising an
265 s-expression or wrapping it, swallowing or rejecting the following
268 @cindex code snippets
270 @cindex reducing boilerplate
271 We also provide templates for common git commit messages and package
272 definitions in the @file{etc/snippets} directory. These templates can
273 be used with @url{https://joaotavora.github.io/yasnippet/, YASnippet} to
274 expand short trigger strings to interactive text snippets. You may want
275 to add the snippets directory to the @var{yas-snippet-dirs} variable in
279 ;; @r{Assuming the Guix checkout is in ~/src/guix.}
280 (with-eval-after-load 'yasnippet
281 (add-to-list 'yas-snippet-dirs "~/src/guix/etc/snippets"))
284 The commit message snippets depend on @url{https://magit.vc/, Magit} to
285 display staged files. When editing a commit message type @code{add}
286 followed by @kbd{TAB} to insert a commit message template for adding a
287 package; type @code{update} followed by @kbd{TAB} to insert a template
288 for updating a package; type @code{https} followed by @kbd{TAB} to
289 insert a template for changing the home page URI of a package to HTTPS.
291 The main snippet for @code{scheme-mode} is triggered by typing
292 @code{package...} followed by @kbd{TAB}. This snippet also inserts the
293 trigger string @code{origin...}, which can be expanded further. The
294 @code{origin} snippet in turn may insert other trigger strings ending on
295 @code{...}, which also can be expanded further.
297 @cindex insert or update copyright
298 @cindex @code{M-x guix-copyright}
299 @cindex @code{M-x copyright-update}
300 We additionally provide insertion and automatic update of a copyright in
301 @file{etc/copyright.el}. You may want to set your full name, mail, and
305 (setq user-full-name "Alice Doe")
306 (setq user-mail-address "alice@@mail.org")
307 ;; @r{Assuming the Guix checkout is in ~/src/guix.}
308 (load-file "~/src/guix/etc/copyright.el")
311 To insert a copyright at the current line invoke @code{M-x guix-copyright}.
313 To update a copyright you need to specify a @code{copyright-names-regexp}.
316 (setq copyright-names-regexp
317 (format "%s <%s>" user-full-name user-mail-address))
320 You can check if your copyright is up to date by evaluating @code{M-x
321 copyright-update}. If you want to do it automatically after each buffer
322 save then add @code{(add-hook 'after-save-hook 'copyright-update)} in
325 @node Packaging Guidelines
326 @section Packaging Guidelines
328 @cindex packages, creating
329 The GNU distribution is nascent and may well lack some of your favorite
330 packages. This section describes how you can help make the distribution
333 Free software packages are usually distributed in the form of
334 @dfn{source code tarballs}---typically @file{tar.gz} files that contain
335 all the source files. Adding a package to the distribution means
336 essentially two things: adding a @dfn{recipe} that describes how to
337 build the package, including a list of other packages required to build
338 it, and adding @dfn{package metadata} along with that recipe, such as a
339 description and licensing information.
341 In Guix all this information is embodied in @dfn{package definitions}.
342 Package definitions provide a high-level view of the package. They are
343 written using the syntax of the Scheme programming language; in fact,
344 for each package we define a variable bound to the package definition,
345 and export that variable from a module (@pxref{Package Modules}).
346 However, in-depth Scheme knowledge is @emph{not} a prerequisite for
347 creating packages. For more information on package definitions,
348 @pxref{Defining Packages}.
350 Once a package definition is in place, stored in a file in the Guix
351 source tree, it can be tested using the @command{guix build} command
352 (@pxref{Invoking guix build}). For example, assuming the new package is
353 called @code{gnew}, you may run this command from the Guix build tree
354 (@pxref{Running Guix Before It Is Installed}):
357 ./pre-inst-env guix build gnew --keep-failed
360 Using @code{--keep-failed} makes it easier to debug build failures since
361 it provides access to the failed build tree. Another useful
362 command-line option when debugging is @code{--log-file}, to access the
365 If the package is unknown to the @command{guix} command, it may be that
366 the source file contains a syntax error, or lacks a @code{define-public}
367 clause to export the package variable. To figure it out, you may load
368 the module from Guile to get more information about the actual error:
371 ./pre-inst-env guile -c '(use-modules (gnu packages gnew))'
374 Once your package builds correctly, please send us a patch
375 (@pxref{Submitting Patches}). Well, if you need help, we will be happy to
376 help you too. Once the patch is committed in the Guix repository, the
377 new package automatically gets built on the supported platforms by
378 @url{@value{SUBSTITUTE-URL}, our continuous integration system}.
381 Users can obtain the new package definition simply by running
382 @command{guix pull} (@pxref{Invoking guix pull}). When
383 @code{@value{SUBSTITUTE-SERVER}} is done building the package, installing the
384 package automatically downloads binaries from there
385 (@pxref{Substitutes}). The only place where human intervention is
386 needed is to review and apply the patch.
390 * Software Freedom:: What may go into the distribution.
391 * Package Naming:: What's in a name?
392 * Version Numbers:: When the name is not enough.
393 * Synopses and Descriptions:: Helping users find the right package.
394 * Snippets versus Phases:: Whether to use a snippet, or a build phase.
395 * Emacs Packages:: Your Elisp fix.
396 * Python Modules:: A touch of British comedy.
397 * Perl Modules:: Little pearls.
398 * Java Packages:: Coffee break.
399 * Rust Crates:: Beware of oxidation.
400 * Fonts:: Fond of fonts.
403 @node Software Freedom
404 @subsection Software Freedom
406 @c Adapted from http://www.gnu.org/philosophy/philosophy.html.
407 @cindex free software
408 The GNU operating system has been developed so that users can have
409 freedom in their computing. GNU is @dfn{free software}, meaning that
410 users have the @url{https://www.gnu.org/philosophy/free-sw.html,four
411 essential freedoms}: to run the program, to study and change the program
412 in source code form, to redistribute exact copies, and to distribute
413 modified versions. Packages found in the GNU distribution provide only
414 software that conveys these four freedoms.
416 In addition, the GNU distribution follow the
417 @url{https://www.gnu.org/distros/free-system-distribution-guidelines.html,free
418 software distribution guidelines}. Among other things, these guidelines
419 reject non-free firmware, recommendations of non-free software, and
420 discuss ways to deal with trademarks and patents.
422 Some otherwise free upstream package sources contain a small and optional
423 subset that violates the above guidelines, for instance because this subset
424 is itself non-free code. When that happens, the offending items are removed
425 with appropriate patches or code snippets in the @code{origin} form of the
426 package (@pxref{Defining Packages}). This way, @code{guix
427 build --source} returns the ``freed'' source rather than the unmodified
432 @subsection Package Naming
435 A package has actually two names associated with it:
436 First, there is the name of the @emph{Scheme variable}, the one following
437 @code{define-public}. By this name, the package can be made known in the
438 Scheme code, for instance as input to another package. Second, there is
439 the string in the @code{name} field of a package definition. This name
440 is used by package management commands such as
441 @command{guix package} and @command{guix build}.
443 Both are usually the same and correspond to the lowercase conversion of
444 the project name chosen upstream, with underscores replaced with
445 hyphens. For instance, GNUnet is available as @code{gnunet}, and
446 SDL_net as @code{sdl-net}.
448 We do not add @code{lib} prefixes for library packages, unless these are
449 already part of the official project name. But @pxref{Python
450 Modules} and @ref{Perl Modules} for special rules concerning modules for
451 the Python and Perl languages.
453 Font package names are handled differently, @pxref{Fonts}.
456 @node Version Numbers
457 @subsection Version Numbers
459 @cindex package version
460 We usually package only the latest version of a given free software
461 project. But sometimes, for instance for incompatible library versions,
462 two (or more) versions of the same package are needed. These require
463 different Scheme variable names. We use the name as defined
464 in @ref{Package Naming}
465 for the most recent version; previous versions use the same name, suffixed
466 by @code{-} and the smallest prefix of the version number that may
467 distinguish the two versions.
469 The name inside the package definition is the same for all versions of a
470 package and does not contain any version number.
472 For instance, the versions 2.24.20 and 3.9.12 of GTK+ may be packaged as follows:
480 (define-public gtk+-2
486 If we also wanted GTK+ 3.8.2, this would be packaged as
488 (define-public gtk+-3.8
495 @c See <https://lists.gnu.org/archive/html/guix-devel/2016-01/msg00425.html>,
496 @c for a discussion of what follows.
497 @cindex version number, for VCS snapshots
498 Occasionally, we package snapshots of upstream's version control system
499 (VCS) instead of formal releases. This should remain exceptional,
500 because it is up to upstream developers to clarify what the stable
501 release is. Yet, it is sometimes necessary. So, what should we put in
502 the @code{version} field?
504 Clearly, we need to make the commit identifier of the VCS snapshot
505 visible in the version string, but we also need to make sure that the
506 version string is monotonically increasing so that @command{guix package
507 --upgrade} can determine which version is newer. Since commit
508 identifiers, notably with Git, are not monotonically increasing, we add
509 a revision number that we increase each time we upgrade to a newer
510 snapshot. The resulting version string looks like this:
515 | | `-- upstream commit ID
517 | `--- Guix package revision
519 latest upstream version
522 It is a good idea to strip commit identifiers in the @code{version}
523 field to, say, 7 digits. It avoids an aesthetic annoyance (assuming
524 aesthetics have a role to play here) as well as problems related to OS
525 limits such as the maximum shebang length (127 bytes for the Linux
526 kernel). It is best to use the full commit identifiers in
527 @code{origin}s, though, to avoid ambiguities. A typical package
528 definition may look like this:
532 (let ((commit "c3f29bc928d5900971f65965feaae59e1272a3f7")
533 (revision "1")) ;Guix package revision
535 (version (git-version "0.9" revision commit))
539 (url "git://example.org/my-package.git")
541 (sha256 (base32 "1mbikn@dots{}"))
542 (file-name (git-file-name name version))))
547 @node Synopses and Descriptions
548 @subsection Synopses and Descriptions
550 @cindex package description
551 @cindex package synopsis
552 As we have seen before, each package in GNU@tie{}Guix includes a
553 synopsis and a description (@pxref{Defining Packages}). Synopses and
554 descriptions are important: They are what @command{guix package
555 --search} searches, and a crucial piece of information to help users
556 determine whether a given package suits their needs. Consequently,
557 packagers should pay attention to what goes into them.
559 Synopses must start with a capital letter and must not end with a
560 period. They must not start with ``a'' or ``the'', which usually does
561 not bring anything; for instance, prefer ``File-frobbing tool'' over ``A
562 tool that frobs files''. The synopsis should say what the package
563 is---e.g., ``Core GNU utilities (file, text, shell)''---or what it is
564 used for---e.g., the synopsis for GNU@tie{}grep is ``Print lines
565 matching a pattern''.
567 Keep in mind that the synopsis must be meaningful for a very wide
568 audience. For example, ``Manipulate alignments in the SAM format''
569 might make sense for a seasoned bioinformatics researcher, but might be
570 fairly unhelpful or even misleading to a non-specialized audience. It
571 is a good idea to come up with a synopsis that gives an idea of the
572 application domain of the package. In this example, this might give
573 something like ``Manipulate nucleotide sequence alignments'', which
574 hopefully gives the user a better idea of whether this is what they are
577 Descriptions should take between five and ten lines. Use full
578 sentences, and avoid using acronyms without first introducing them.
579 Please avoid marketing phrases such as ``world-leading'',
580 ``industrial-strength'', and ``next-generation'', and avoid superlatives
581 like ``the most advanced''---they are not helpful to users looking for a
582 package and may even sound suspicious. Instead, try to be factual,
583 mentioning use cases and features.
585 @cindex Texinfo markup, in package descriptions
586 Descriptions can include Texinfo markup, which is useful to introduce
587 ornaments such as @code{@@code} or @code{@@dfn}, bullet lists, or
588 hyperlinks (@pxref{Overview,,, texinfo, GNU Texinfo}). However you
589 should be careful when using some characters for example @samp{@@} and
590 curly braces which are the basic special characters in Texinfo
591 (@pxref{Special Characters,,, texinfo, GNU Texinfo}). User interfaces
592 such as @command{guix package --show} take care of rendering it
595 Synopses and descriptions are translated by volunteers
596 @uref{https://translate.fedoraproject.org/projects/guix/packages, at
597 Weblate} so that as many users as possible can read them in
598 their native language. User interfaces search them and display them in
599 the language specified by the current locale.
601 To allow @command{xgettext} to extract them as translatable strings,
602 synopses and descriptions @emph{must be literal strings}. This means
603 that you cannot use @code{string-append} or @code{format} to construct
609 (synopsis "This is translatable")
610 (description (string-append "This is " "*not*" " translatable.")))
613 Translation is a lot of work so, as a packager, please pay even more
614 attention to your synopses and descriptions as every change may entail
615 additional work for translators. In order to help them, it is possible
616 to make recommendations or instructions visible to them by inserting
617 special comments like this (@pxref{xgettext Invocation,,, gettext, GNU
621 ;; TRANSLATORS: "X11 resize-and-rotate" should not be translated.
622 (description "ARandR is designed to provide a simple visual front end
623 for the X11 resize-and-rotate (RandR) extension. @dots{}")
626 @node Snippets versus Phases
627 @subsection Snippets versus Phases
629 @cindex snippets, when to use
630 The boundary between using an origin snippet versus a build phase to
631 modify the sources of a package can be elusive. Origin snippets are
632 typically used to remove unwanted files such as bundled libraries,
633 nonfree sources, or to apply simple substitutions. The source derived
634 from an origin should produce a source that can be used to build the
635 package on any system that the upstream package supports (i.e., act as
636 the corresponding source). In particular, origin snippets must not
637 embed store items in the sources; such patching should rather be done
638 using build phases. Refer to the @code{origin} record documentation for
639 more information (@pxref{origin Reference}).
642 @subsection Emacs Packages
644 @cindex emacs, packaging
645 @cindex elisp, packaging
646 Emacs packages should preferably use the Emacs build system
647 (@pxref{emacs-build-system}), for uniformity and the benefits provided
648 by its build phases, such as the auto-generation of the autoloads file
649 and the byte compilation of the sources. Because there is no
650 standardized way to run a test suite for Emacs packages, tests are
651 disabled by default. When a test suite is available, it should be
652 enabled by setting the @code{#:tests?} argument to @code{#true}. By
653 default, the command to run the test is @command{make check}, but any
654 command can be specified via the @code{#:test-command} argument. The
655 @code{#:test-command} argument expects a list containing a command and
656 its arguments, to be invoked during the @code{check} phase.
658 The Elisp dependencies of Emacs packages are typically provided as
659 @code{propagated-inputs} when required at run time. As for other
660 packages, build or test dependencies should be specified as
661 @code{native-inputs}.
663 Emacs packages sometimes depend on resources directories that should be
664 installed along the Elisp files. The @code{#:include} argument can be
665 used for that purpose, by specifying a list of regexps to match. The
666 best practice when using the @code{#:include} argument is to extend
667 rather than override its default value (accessible via the
668 @code{%default-include} variable). As an example, a yasnippet extension
669 package typically include a @file{snippets} directory, which could be
670 copied to the installation directory using:
673 #:include (cons "^snippets/" %default-include))
676 When encountering problems, it is wise to check for the presence of the
677 @code{Package-Requires} extension header in the package main source
678 file, and whether any dependencies and their versions listed therein are
682 @subsection Python Modules
685 We currently package Python 2 and Python 3, under the Scheme variable names
686 @code{python-2} and @code{python} as explained in @ref{Version Numbers}.
687 To avoid confusion and naming clashes with other programming languages, it
688 seems desirable that the name of a package for a Python module contains
689 the word @code{python}.
691 Some modules are compatible with only one version of Python, others with
692 both. If the package Foo is compiled with Python 3, we name it
693 @code{python-foo}. If it is compiled with Python 2, we name it
694 @code{python2-foo}. Packages should be added when they are necessary;
695 we don't add Python 2 variants of the package unless we are going to use
698 If a project already contains the word @code{python}, we drop this;
699 for instance, the module python-dateutil is packaged under the names
700 @code{python-dateutil} and @code{python2-dateutil}. If the project name
701 starts with @code{py} (e.g.@: @code{pytz}), we keep it and prefix it as
704 @subsubsection Specifying Dependencies
705 @cindex inputs, for Python packages
707 Dependency information for Python packages is usually available in the
708 package source tree, with varying degrees of accuracy: in the
709 @file{setup.py} file, in @file{requirements.txt}, or in @file{tox.ini}.
711 Your mission, when writing a recipe for a Python package, is to map
712 these dependencies to the appropriate type of ``input'' (@pxref{package
713 Reference, inputs}). Although the @code{pypi} importer normally does a
714 good job (@pxref{Invoking guix import}), you may want to check the
715 following check list to determine which dependency goes where.
720 We currently package Python 2 with @code{setuptools} and @code{pip}
721 installed like Python 3.4 has per default. Thus you don't need to
722 specify either of these as an input. @command{guix lint} will warn you
726 Python dependencies required at run time go into
727 @code{propagated-inputs}. They are typically defined with the
728 @code{install_requires} keyword in @file{setup.py}, or in the
729 @file{requirements.txt} file.
732 Python packages required only at build time---e.g., those listed with
733 the @code{setup_requires} keyword in @file{setup.py}---or only for
734 testing---e.g., those in @code{tests_require}---go into
735 @code{native-inputs}. The rationale is that (1) they do not need to be
736 propagated because they are not needed at run time, and (2) in a
737 cross-compilation context, it's the ``native'' input that we'd want.
739 Examples are the @code{pytest}, @code{mock}, and @code{nose} test
740 frameworks. Of course if any of these packages is also required at
741 run-time, it needs to go to @code{propagated-inputs}.
744 Anything that does not fall in the previous categories goes to
745 @code{inputs}, for example programs or C libraries required for building
746 Python packages containing C extensions.
749 If a Python package has optional dependencies (@code{extras_require}),
750 it is up to you to decide whether to add them or not, based on their
751 usefulness/overhead ratio (@pxref{Submitting Patches, @command{guix
758 @subsection Perl Modules
761 Perl programs standing for themselves are named as any other package,
762 using the lowercase upstream name.
763 For Perl packages containing a single class, we use the lowercase class name,
764 replace all occurrences of @code{::} by dashes and prepend the prefix
766 So the class @code{XML::Parser} becomes @code{perl-xml-parser}.
767 Modules containing several classes keep their lowercase upstream name and
768 are also prepended by @code{perl-}. Such modules tend to have the word
769 @code{perl} somewhere in their name, which gets dropped in favor of the
770 prefix. For instance, @code{libwww-perl} becomes @code{perl-libwww}.
774 @subsection Java Packages
777 Java programs standing for themselves are named as any other package,
778 using the lowercase upstream name.
780 To avoid confusion and naming clashes with other programming languages,
781 it is desirable that the name of a package for a Java package is
782 prefixed with @code{java-}. If a project already contains the word
783 @code{java}, we drop this; for instance, the package @code{ngsjava} is
784 packaged under the name @code{java-ngs}.
786 For Java packages containing a single class or a small class hierarchy,
787 we use the lowercase class name, replace all occurrences of @code{.} by
788 dashes and prepend the prefix @code{java-}. So the class
789 @code{apache.commons.cli} becomes package
790 @code{java-apache-commons-cli}.
794 @subsection Rust Crates
797 Rust programs standing for themselves are named as any other package, using the
798 lowercase upstream name.
800 To prevent namespace collisions we prefix all other Rust packages with the
801 @code{rust-} prefix. The name should be changed to lowercase as appropriate and
802 dashes should remain in place.
804 In the rust ecosystem it is common for multiple incompatible versions of a
805 package to be used at any given time, so all package definitions should have a
806 versioned suffix. The versioned suffix is the left-most non-zero digit (and
807 any leading zeros, of course). This follows the ``caret'' version scheme
808 intended by Cargo. Examples@: @code{rust-clap-2}, @code{rust-rand-0.6}.
810 Because of the difficulty in reusing rust packages as pre-compiled inputs for
811 other packages the Cargo build system (@pxref{Build Systems,
812 @code{cargo-build-system}}) presents the @code{#:cargo-inputs} and
813 @code{cargo-development-inputs} keywords as build system arguments. It would be
814 helpful to think of these as similar to @code{propagated-inputs} and
815 @code{native-inputs}. Rust @code{dependencies} and @code{build-dependencies}
816 should go in @code{#:cargo-inputs}, and @code{dev-dependencies} should go in
817 @code{#:cargo-development-inputs}. If a Rust package links to other libraries
818 then the standard placement in @code{inputs} and the like should be used.
820 Care should be taken to ensure the correct version of dependencies are used; to
821 this end we try to refrain from skipping the tests or using @code{#:skip-build?}
822 when possible. Of course this is not always possible, as the package may be
823 developed for a different Operating System, depend on features from the Nightly
824 Rust compiler, or the test suite may have atrophied since it was released.
831 For fonts that are in general not installed by a user for typesetting
832 purposes, or that are distributed as part of a larger software package,
833 we rely on the general packaging rules for software; for instance, this
834 applies to the fonts delivered as part of the X.Org system or fonts that
835 are part of TeX Live.
837 To make it easier for a user to search for fonts, names for other packages
838 containing only fonts are constructed as follows, independently of the
839 upstream package name.
841 The name of a package containing only one font family starts with
842 @code{font-}; it is followed by the foundry name and a dash @code{-}
843 if the foundry is known, and the font family name, in which spaces are
844 replaced by dashes (and as usual, all upper case letters are transformed
846 For example, the Gentium font family by SIL is packaged under the name
847 @code{font-sil-gentium}.
849 For a package containing several font families, the name of the collection
850 is used in the place of the font family name.
851 For instance, the Liberation fonts consist of three families,
852 Liberation Sans, Liberation Serif and Liberation Mono.
853 These could be packaged separately under the names
854 @code{font-liberation-sans} and so on; but as they are distributed together
855 under a common name, we prefer to package them together as
856 @code{font-liberation}.
858 In the case where several formats of the same font family or font collection
859 are packaged separately, a short form of the format, prepended by a dash,
860 is added to the package name. We use @code{-ttf} for TrueType fonts,
861 @code{-otf} for OpenType fonts and @code{-type1} for PostScript Type 1
866 @section Coding Style
868 In general our code follows the GNU Coding Standards (@pxref{Top,,,
869 standards, GNU Coding Standards}). However, they do not say much about
870 Scheme, so here are some additional rules.
873 * Programming Paradigm:: How to compose your elements.
874 * Modules:: Where to store your code?
875 * Data Types and Pattern Matching:: Implementing data structures.
876 * Formatting Code:: Writing conventions.
879 @node Programming Paradigm
880 @subsection Programming Paradigm
882 Scheme code in Guix is written in a purely functional style. One
883 exception is code that involves input/output, and procedures that
884 implement low-level concepts, such as the @code{memoize} procedure.
889 Guile modules that are meant to be used on the builder side must live in
890 the @code{(guix build @dots{})} name space. They must not refer to
891 other Guix or GNU modules. However, it is OK for a ``host-side'' module
892 to use a build-side module.
894 Modules that deal with the broader GNU system should be in the
895 @code{(gnu @dots{})} name space rather than @code{(guix @dots{})}.
897 @node Data Types and Pattern Matching
898 @subsection Data Types and Pattern Matching
900 The tendency in classical Lisp is to use lists to represent everything,
901 and then to browse them ``by hand'' using @code{car}, @code{cdr},
902 @code{cadr}, and co. There are several problems with that style,
903 notably the fact that it is hard to read, error-prone, and a hindrance
904 to proper type error reports.
906 Guix code should define appropriate data types (for instance, using
907 @code{define-record-type*}) rather than abuse lists. In addition, it
908 should use pattern matching, via Guile’s @code{(ice-9 match)} module,
909 especially when matching lists (@pxref{Pattern Matching,,, guile, GNU
910 Guile Reference Manual}).
912 @node Formatting Code
913 @subsection Formatting Code
915 @cindex formatting code
917 When writing Scheme code, we follow common wisdom among Scheme
918 programmers. In general, we follow the
919 @url{https://mumble.net/~campbell/scheme/style.txt, Riastradh's Lisp
920 Style Rules}. This document happens to describe the conventions mostly
921 used in Guile’s code too. It is very thoughtful and well written, so
924 Some special forms introduced in Guix, such as the @code{substitute*}
925 macro, have special indentation rules. These are defined in the
926 @file{.dir-locals.el} file, which Emacs automatically uses. Also note
927 that Emacs-Guix provides @code{guix-devel-mode} mode that indents and
928 highlights Guix code properly (@pxref{Development,,, emacs-guix, The
929 Emacs-Guix Reference Manual}).
931 @cindex indentation, of code
932 @cindex formatting, of code
933 If you do not use Emacs, please make sure to let your editor knows these
934 rules. To automatically indent a package definition, you can also run:
937 ./etc/indent-code.el gnu/packages/@var{file}.scm @var{package}
941 This automatically indents the definition of @var{package} in
942 @file{gnu/packages/@var{file}.scm} by running Emacs in batch mode. To
943 indent a whole file, omit the second argument:
946 ./etc/indent-code.el gnu/services/@var{file}.scm
949 @cindex Vim, Scheme code editing
950 If you are editing code with Vim, we recommend that you run @code{:set
951 autoindent} so that your code is automatically indented as you type.
953 @uref{https://www.vim.org/scripts/script.php?script_id=3998,
954 @code{paredit.vim}} may help you deal with all these parentheses.
956 We require all top-level procedures to carry a docstring. This
957 requirement can be relaxed for simple private procedures in the
958 @code{(guix build @dots{})} name space, though.
960 Procedures should not have more than four positional parameters. Use
961 keyword parameters for procedures that take more than four parameters.
964 @node Submitting Patches
965 @section Submitting Patches
967 Development is done using the Git distributed version control system.
968 Thus, access to the repository is not strictly necessary. We welcome
969 contributions in the form of patches as produced by @code{git
970 format-patch} sent to the @email{guix-patches@@gnu.org} mailing list.
971 Seasoned Guix developers may also want to look at the section on commit
972 access (@pxref{Commit Access}).
974 This mailing list is backed by a Debbugs instance, which allows us to
975 keep track of submissions (@pxref{Tracking Bugs and Patches}). Each
976 message sent to that mailing list gets a new tracking number assigned;
977 people can then follow up on the submission by sending email to
978 @code{@var{NNN}@@debbugs.gnu.org}, where @var{NNN} is the tracking
979 number (@pxref{Sending a Patch Series}).
981 Please write commit logs in the ChangeLog format (@pxref{Change Logs,,,
982 standards, GNU Coding Standards}); you can check the commit history for
985 Before submitting a patch that adds or modifies a package definition,
986 please run through this check list:
990 If the authors of the packaged software provide a cryptographic
991 signature for the release tarball, make an effort to verify the
992 authenticity of the archive. For a detached GPG signature file this
993 would be done with the @code{gpg --verify} command.
996 Take some time to provide an adequate synopsis and description for the
997 package. @xref{Synopses and Descriptions}, for some guidelines.
1000 Run @code{guix lint @var{package}}, where @var{package} is the
1001 name of the new or modified package, and fix any errors it reports
1002 (@pxref{Invoking guix lint}).
1005 Make sure the package builds on your platform, using @code{guix build
1009 We recommend you also try building the package on other supported
1010 platforms. As you may not have access to actual hardware platforms, we
1011 recommend using the @code{qemu-binfmt-service-type} to emulate them. In
1012 order to enable it, add the following service to the list of services in
1013 your @code{operating-system} configuration:
1016 (service qemu-binfmt-service-type
1017 (qemu-binfmt-configuration
1018 (platforms (lookup-qemu-platforms "arm" "aarch64"))
1019 (guix-support? #t)))
1022 Then reconfigure your system.
1024 You can then build packages for different platforms by specifying the
1025 @code{--system} option. For example, to build the "hello" package for
1026 the armhf, aarch64, or mips64 architectures, you would run the following
1027 commands, respectively:
1029 guix build --system=armhf-linux --rounds=2 hello
1030 guix build --system=aarch64-linux --rounds=2 hello
1035 Make sure the package does not use bundled copies of software already
1036 available as separate packages.
1038 Sometimes, packages include copies of the source code of their
1039 dependencies as a convenience for users. However, as a distribution, we
1040 want to make sure that such packages end up using the copy we already
1041 have in the distribution, if there is one. This improves resource usage
1042 (the dependency is built and stored only once), and allows the
1043 distribution to make transverse changes such as applying security
1044 updates for a given software package in a single place and have them
1045 affect the whole system---something that bundled copies prevent.
1048 Take a look at the profile reported by @command{guix size}
1049 (@pxref{Invoking guix size}). This will allow you to notice references
1050 to other packages unwillingly retained. It may also help determine
1051 whether to split the package (@pxref{Packages with Multiple Outputs}),
1052 and which optional dependencies should be used. In particular, avoid adding
1053 @code{texlive} as a dependency: because of its extreme size, use
1054 the @code{texlive-tiny} package or @code{texlive-union} procedure instead.
1057 For important changes, check that dependent package (if applicable) are
1058 not affected by the change; @code{guix refresh --list-dependent
1059 @var{package}} will help you do that (@pxref{Invoking guix refresh}).
1061 @c See <https://lists.gnu.org/archive/html/guix-devel/2016-10/msg00933.html>.
1062 @cindex branching strategy
1063 @cindex rebuild scheduling strategy
1064 Depending on the number of dependent packages and thus the amount of
1065 rebuilding induced, commits go to different branches, along these lines:
1068 @item 300 dependent packages or less
1069 @code{master} branch (non-disruptive changes).
1071 @item between 300 and 1,800 dependent packages
1072 @code{staging} branch (non-disruptive changes). This branch is intended
1073 to be merged in @code{master} every 6 weeks or so. Topical changes
1074 (e.g., an update of the GNOME stack) can instead go to a specific branch
1075 (say, @code{gnome-updates}).
1077 @item more than 1,800 dependent packages
1078 @code{core-updates} branch (may include major and potentially disruptive
1079 changes). This branch is intended to be merged in @code{master} every
1083 All these branches are @uref{@value{SUBSTITUTE-URL},
1084 tracked by our build farm} and merged into @code{master} once
1085 everything has been successfully built. This allows us to fix issues
1086 before they hit users, and to reduce the window during which pre-built
1087 binaries are not available.
1089 Generally, branches other than @code{master} are considered
1090 @emph{frozen} if there has been a recent evaluation, or there is a
1091 corresponding @code{-next} branch. Please ask on the mailing list or
1092 IRC if unsure where to place a patch.
1093 @c TODO: It would be good with badges on the website that tracks these
1094 @c branches. Or maybe even a status page.
1097 @cindex determinism, of build processes
1098 @cindex reproducible builds, checking
1099 Check whether the package's build process is deterministic. This
1100 typically means checking whether an independent build of the package
1101 yields the exact same result that you obtained, bit for bit.
1103 A simple way to do that is by building the same package several times in
1104 a row on your machine (@pxref{Invoking guix build}):
1107 guix build --rounds=2 my-package
1110 This is enough to catch a class of common non-determinism issues, such
1111 as timestamps or randomly-generated output in the build result.
1113 Another option is to use @command{guix challenge} (@pxref{Invoking guix
1114 challenge}). You may run it once the package has been committed and
1115 built by @code{@value{SUBSTITUTE-SERVER}} to check whether it obtains the same
1116 result as you did. Better yet: Find another machine that can build it
1117 and run @command{guix publish}. Since the remote build machine is
1118 likely different from yours, this can catch non-determinism issues
1119 related to the hardware---e.g., use of different instruction set
1120 extensions---or to the operating system kernel---e.g., reliance on
1121 @code{uname} or @file{/proc} files.
1124 When writing documentation, please use gender-neutral wording when
1125 referring to people, such as
1126 @uref{https://en.wikipedia.org/wiki/Singular_they, singular
1127 ``they''@comma{} ``their''@comma{} ``them''}, and so forth.
1130 Verify that your patch contains only one set of related changes.
1131 Bundling unrelated changes together makes reviewing harder and slower.
1133 Examples of unrelated changes include the addition of several packages,
1134 or a package update along with fixes to that package.
1137 Please follow our code formatting rules, possibly running the
1138 @command{etc/indent-code.el} script to do that automatically for you
1139 (@pxref{Formatting Code}).
1142 When possible, use mirrors in the source URL (@pxref{Invoking guix download}).
1143 Use reliable URLs, not generated ones. For instance, GitHub archives are not
1144 necessarily identical from one generation to the next, so in this case it's
1145 often better to clone the repository. Don't use the @command{name} field in
1146 the URL: it is not very useful and if the name changes, the URL will probably
1150 Check if Guix builds (@pxref{Building from Git}) and address the
1151 warnings, especially those about use of undefined symbols.
1154 Make sure your changes do not break Guix and simulate a @code{guix pull} with:
1156 guix pull --url=/path/to/your/checkout --profile=/tmp/guix.master
1161 When posting a patch to the mailing list, use @samp{[PATCH] @dots{}} as
1162 a subject, if your patch is to be applied on a branch other than
1163 @code{master}, say @code{core-updates}, specify it in the subject like
1164 @samp{[PATCH core-updates] @dots{}}. You may use your email client or
1165 the @command{git send-email} command (@pxref{Sending a Patch Series}).
1166 We prefer to get patches in plain text messages, either inline or as
1167 MIME attachments. You are advised to pay attention if your email client
1168 changes anything like line breaks or indentation which could potentially
1171 When a bug is resolved, please close the thread by sending an email to
1172 @email{@var{NNN}-done@@debbugs.gnu.org}.
1174 @unnumberedsubsec Sending a Patch Series
1175 @anchor{Sending a Patch Series}
1176 @cindex patch series
1177 @cindex @code{git send-email}
1178 @cindex @code{git-send-email}
1180 When sending a patch series (e.g., using @code{git send-email}), please
1181 first send one message to @email{guix-patches@@gnu.org}, and then send
1182 subsequent patches to @email{@var{NNN}@@debbugs.gnu.org} to make sure
1183 they are kept together. See
1184 @uref{https://debbugs.gnu.org/Advanced.html, the Debbugs documentation}
1185 for more information. You can install @command{git send-email} with
1186 @command{guix install git:send-email}.
1187 @c Debbugs bug: https://debbugs.gnu.org/db/15/15361.html
1189 @node Tracking Bugs and Patches
1190 @section Tracking Bugs and Patches
1192 @cindex bug reports, tracking
1193 @cindex patch submissions, tracking
1194 @cindex issue tracking
1195 @cindex Debbugs, issue tracking system
1196 Bug reports and patch submissions are currently tracked using the
1197 Debbugs instance at @uref{https://bugs.gnu.org}. Bug reports are filed
1198 against the @code{guix} ``package'' (in Debbugs parlance), by sending
1199 email to @email{bug-guix@@gnu.org}, while patch submissions are filed
1200 against the @code{guix-patches} package by sending email to
1201 @email{guix-patches@@gnu.org} (@pxref{Submitting Patches}).
1203 A web interface (actually @emph{two} web interfaces!) are available to
1208 @url{https://issues.guix.gnu.org} provides a pleasant
1209 interface@footnote{The web interface at
1210 @url{https://issues.guix.gnu.org} is powered by Mumi, a nice piece of
1211 software written in Guile, and you can help! See
1212 @url{https://git.elephly.net/gitweb.cgi?p=software/mumi.git}.} to browse
1213 bug reports and patches, and to participate in discussions;
1215 @url{https://bugs.gnu.org/guix} lists bug reports;
1217 @url{https://bugs.gnu.org/guix-patches} lists patch submissions.
1220 To view discussions related to issue number @var{n}, go to
1221 @indicateurl{https://issues.guix.gnu.org/@var{n}} or
1222 @indicateurl{https://bugs.gnu.org/@var{n}}.
1224 If you use Emacs, you may find it more convenient to interact with
1225 issues using @file{debbugs.el}, which you can install with:
1228 guix install emacs-debbugs
1231 For example, to list all open issues on @code{guix-patches}, hit:
1234 @kbd{C-u} @kbd{M-x} debbugs-gnu @kbd{RET} @kbd{RET} guix-patches @kbd{RET} n y
1237 @xref{Top,,, debbugs-ug, Debbugs User Guide}, for more information on
1241 @section Commit Access
1243 @cindex commit access, for developers
1244 For frequent contributors, having write access to the repository is
1245 convenient. When you deem it necessary, consider applying for commit
1246 access by following these steps:
1250 Find three committers who would vouch for you. You can view the list of
1252 @url{https://savannah.gnu.org/project/memberlist.php?group=guix}. Each
1253 of them should email a statement to @email{guix-maintainers@@gnu.org} (a
1254 private alias for the collective of maintainers), signed with their
1257 Committers are expected to have had some interactions with you as a
1258 contributor and to be able to judge whether you are sufficiently
1259 familiar with the project's practices. It is @emph{not} a judgment on
1260 the value of your work, so a refusal should rather be interpreted as
1261 ``let's try again later''.
1264 Send @email{guix-maintainers@@gnu.org} a message stating your intent,
1265 listing the three committers who support your application, signed with
1266 the OpenPGP key you will use to sign commits, and giving its fingerprint
1267 (see below). See @uref{https://emailselfdefense.fsf.org/en/}, for an
1268 introduction to public-key cryptography with GnuPG.
1270 @c See <https://sha-mbles.github.io/>.
1271 Set up GnuPG such that it never uses the SHA1 hash algorithm for digital
1272 signatures, which is known to be unsafe since 2019, for instance by
1273 adding the following line to @file{~/.gnupg/gpg.conf} (@pxref{GPG
1274 Esoteric Options,,, gnupg, The GNU Privacy Guard Manual}):
1281 Maintainers ultimately decide whether to grant you commit access,
1282 usually following your referrals' recommendation.
1285 @cindex OpenPGP, signed commits
1286 If and once you've been given access, please send a message to
1287 @email{guix-devel@@gnu.org} to say so, again signed with the OpenPGP key
1288 you will use to sign commits (do that before pushing your first commit).
1289 That way, everyone can notice and ensure you control that OpenPGP key.
1291 @quotation Important
1292 Before you can push for the first time, maintainers must:
1296 add your OpenPGP key to the @code{keyring} branch;
1298 add your OpenPGP fingerprint to the @file{.guix-authorizations} file of
1299 the branch(es) you will commit to.
1304 Make sure to read the rest of this section and... profit!
1308 Maintainers are happy to give commit access to people who have been
1309 contributing for some time and have a track record---don't be shy and
1310 don't underestimate your work!
1312 However, note that the project is working towards a more automated patch
1313 review and merging system, which, as a consequence, may lead us to have
1314 fewer people with commit access to the main repository. Stay tuned!
1317 If you get commit access, please make sure to follow
1318 the policy below (discussions of the policy can take place on
1319 @email{guix-devel@@gnu.org}).
1321 Non-trivial patches should always be posted to
1322 @email{guix-patches@@gnu.org} (trivial patches include fixing typos,
1323 etc.). This mailing list fills the patch-tracking database
1324 (@pxref{Tracking Bugs and Patches}).
1326 For patches that just add a new package, and a simple one, it's OK to
1327 commit, if you're confident (which means you successfully built it in a
1328 chroot setup, and have done a reasonable copyright and license
1329 auditing). Likewise for package upgrades, except upgrades that trigger
1330 a lot of rebuilds (for example, upgrading GnuTLS or GLib). We have a
1331 mailing list for commit notifications (@email{guix-commits@@gnu.org}),
1332 so people can notice. Before pushing your changes, make sure to run
1333 @code{git pull --rebase}.
1335 All commits that are pushed to the central repository on Savannah must
1336 be signed with an OpenPGP key, and the public key should be uploaded to
1337 your user account on Savannah and to public key servers, such as
1338 @code{keys.openpgp.org}. To configure Git to automatically sign
1342 git config commit.gpgsign true
1343 git config user.signingkey CABBA6EA1DC0FF33
1346 You can prevent yourself from accidentally pushing unsigned commits to
1347 Savannah by using the pre-push Git hook called located at
1348 @file{etc/git/pre-push}:
1351 cp etc/git/pre-push .git/hooks/pre-push
1354 When pushing a commit on behalf of somebody else, please add a
1355 @code{Signed-off-by} line at the end of the commit log message---e.g.,
1356 with @command{git am --signoff}. This improves tracking of who did
1359 When adding channel news entries (@pxref{Channels, Writing Channel
1360 News}), make sure they are well-formed by running the following command
1361 right before pushing:
1364 make check-channel-news
1367 For anything else, please post to @email{guix-patches@@gnu.org} and
1368 leave time for a review, without committing anything (@pxref{Submitting
1369 Patches}). If you didn’t receive any reply after two weeks, and if
1370 you're confident, it's OK to commit.
1372 That last part is subject to being adjusted, allowing individuals to commit
1373 directly on non-controversial changes on parts they’re familiar with.
1375 One last thing: the project keeps moving forward because committers not
1376 only push their own awesome changes, but also offer some of their time
1377 @emph{reviewing} and pushing other people's changes. As a committer,
1378 you're welcome to use your expertise and commit rights to help other
1381 @node Updating the Guix Package
1382 @section Updating the Guix Package
1384 @cindex update-guix-package, updating the guix package
1385 It is sometimes desirable to update the @code{guix} package itself (the
1386 package defined in @code{(gnu packages package-management)}), for
1387 example to make new daemon features available for use by the
1388 @code{guix-service-type} service type. In order to simplify this task,
1389 the following command can be used:
1392 make update-guix-package
1395 The @code{update-guix-package} make target will use the last known
1396 @emph{commit} corresponding to @code{HEAD} in your Guix checkout,
1397 compute the hash of the Guix sources corresponding to that commit and
1398 update the @code{commit}, @code{revision} and hash of the @code{guix}
1401 To validate that the updated @code{guix} package hashes are correct and
1402 that it can be built successfully, the following command can be run from
1403 the directory of your Guix checkout:
1406 ./pre-inst-env guix build guix
1409 To guard against accidentally updating the @code{guix} package to a
1410 commit that others can't refer to, a check is made that the commit used
1411 has already been pushed to the Savannah-hosted Guix git repository.
1413 This check can be disabled, @emph{at your own peril}, by setting the
1414 @code{GUIX_ALLOW_ME_TO_USE_PRIVATE_COMMIT} environment variable. When
1415 this variable is set, the updated package source is also added to the
1416 store. This is used as part of the release process of Guix.