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 Libera Chat 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:: Keeping it all organized.
30 * Commit Access:: Pushing to the official repository.
31 * Updating the Guix Package:: Updating the Guix package definition.
32 * Writing Documentation:: Improving documentation in GNU Guix.
33 * Translating Guix:: Make Guix speak your native language.
36 @node Building from Git
37 @section Building from Git
39 If you want to hack Guix itself, it is recommended to use the latest
40 version from the Git repository:
43 git clone https://git.savannah.gnu.org/git/guix.git
46 @cindex authentication, of a Guix checkout
47 How do you ensure that you obtained a genuine copy of the repository?
48 To do that, run @command{guix git authenticate}, passing it the commit
49 and OpenPGP fingerprint of the @dfn{channel introduction}
50 (@pxref{Invoking guix git authenticate}):
52 @c The commit and fingerprint below must match those of the channel
53 @c introduction in '%default-channels'.
55 git fetch origin keyring:keyring
56 guix git authenticate 9edb3f66fd807b096b48283debdcddccfea34bad \
57 "BBB0 2DDF 2CEA F6A8 0D1D E643 A2A0 6DF2 A33A 54FA"
61 This command completes with exit code zero on success; it prints an
62 error message and exits with a non-zero code otherwise.
64 As you can see, there is a chicken-and-egg problem: you first need to
65 have Guix installed. Typically you would install Guix System
66 (@pxref{System Installation}) or Guix on top of another distro
67 (@pxref{Binary Installation}); in either case, you would verify the
68 OpenPGP signature on the installation medium. This ``bootstraps'' the
71 The easiest way to set up a development environment for Guix is, of
72 course, by using Guix! The following command starts a new shell where
73 all the dependencies and appropriate environment variables are set up to
77 guix shell -D guix --pure
80 @xref{Invoking guix shell}, for more information on that command.
82 If you are unable to use Guix when building Guix from a checkout, the
83 following are the required packages in addition to those mentioned in the
84 installation instructions (@pxref{Requirements}).
87 @item @url{https://gnu.org/software/autoconf/, GNU Autoconf};
88 @item @url{https://gnu.org/software/automake/, GNU Automake};
89 @item @url{https://gnu.org/software/gettext/, GNU Gettext};
90 @item @url{https://gnu.org/software/texinfo/, GNU Texinfo};
91 @item @url{https://www.graphviz.org/, Graphviz};
92 @item @url{https://www.gnu.org/software/help2man/, GNU Help2man (optional)}.
95 On Guix, extra dependencies can be added by instead running @command{guix
99 guix shell -D guix help2man git strace --pure
102 From there you can generate the build system infrastructure
103 using Autoconf and Automake:
109 If you get an error like this one:
112 configure.ac:46: error: possibly undefined macro: PKG_CHECK_MODULES
116 it probably means that Autoconf couldn’t find @file{pkg.m4}, which is
117 provided by pkg-config. Make sure that @file{pkg.m4} is available. The
118 same holds for the @file{guile.m4} set of macros provided by Guile. For
119 instance, if you installed Automake in @file{/usr/local}, it wouldn’t
120 look for @file{.m4} files in @file{/usr/share}. In that case, you have
121 to invoke the following command:
124 export ACLOCAL_PATH=/usr/share/aclocal
127 @xref{Macro Search Path,,, automake, The GNU Automake Manual}, for
133 ./configure --localstatedir=/var
137 ... where @file{/var} is the normal @code{localstatedir} value
138 (@pxref{The Store}, for information about this). Note that you will
139 probably not run @command{make install} at the end (you don't have to)
140 but it's still important to pass the right @code{localstatedir}.
142 Finally, you can build Guix and, if you feel so inclined, run the tests
143 (@pxref{Running the Test Suite}):
151 If anything fails, take a look at installation instructions
152 (@pxref{Installation}) or send a message to the
153 @email{guix-devel@@gnu.org, mailing list}.
155 From there on, you can authenticate all the commits included in your
162 The first run takes a couple of minutes, but subsequent runs are faster.
164 Or, when your configuration for your local Git repository doesn't match
165 the default one, you can provide the reference for the @code{keyring}
166 branch through the variable @code{GUIX_GIT_KEYRING}. The following
167 example assumes that you have a Git remote called @samp{myremote}
168 pointing to the official repository:
171 make authenticate GUIX_GIT_KEYRING=myremote/keyring
175 You are advised to run @command{make authenticate} after every
176 @command{git pull} invocation. This ensures you keep receiving valid
177 changes to the repository.
180 After updating the repository, @command{make} might fail with an error
181 similar to the following example:
184 error: failed to load 'gnu/packages/dunst.scm':
185 ice-9/eval.scm:293:34: In procedure abi-check: #<record-type <origin>>: record ABI mismatch; recompilation needed
188 This means that one of the record types that Guix defines (in this
189 example, the @code{origin} record) has changed, and all of guix needs
190 to be recompiled to take that change into account. To do so, run
191 @command{make clean-go} followed by @command{make}.
193 @node Running Guix Before It Is Installed
194 @section Running Guix Before It Is Installed
196 In order to keep a sane working environment, you will find it useful to
197 test the changes made in your local source tree checkout without
198 actually installing them. So that you can distinguish between your
199 ``end-user'' hat and your ``motley'' costume.
201 To that end, all the command-line tools can be used even if you have not
202 run @code{make install}. To do that, you first need to have an
203 environment with all the dependencies available (@pxref{Building from
204 Git}), and then simply prefix each command with @command{./pre-inst-env}
205 (the @file{pre-inst-env} script lives in the top build tree of Guix; it
206 is generated by running @command{./bootstrap} followed by
207 @command{./configure}). As an example, here is how you would build the
208 @code{hello} package as defined in your working tree (this assumes
209 @command{guix-daemon} is already running on your system; it's OK if it's
210 a different version):
213 $ ./pre-inst-env guix build hello
217 Similarly, an example for a Guile session using the Guix modules:
220 $ ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))'
227 @cindex read-eval-print loop
228 @dots{} and for a REPL (@pxref{Using Guix Interactively}):
231 $ ./pre-inst-env guile
232 scheme@@(guile-user)> ,use(guix)
233 scheme@@(guile-user)> ,use(gnu)
234 scheme@@(guile-user)> (define snakes
236 (lambda (package lst)
237 (if (string-prefix? "python"
238 (package-name package))
242 scheme@@(guile-user)> (length snakes)
246 If you are hacking on the daemon and its supporting code or if
247 @command{guix-daemon} is not already running on your system, you can
248 launch it straight from the build tree@footnote{The @option{-E} flag to
249 @command{sudo} guarantees that @code{GUILE_LOAD_PATH} is correctly set
250 such that @command{guix-daemon} and the tools it uses can find the Guile
254 $ sudo -E ./pre-inst-env guix-daemon --build-users-group=guixbuild
257 The @command{pre-inst-env} script sets up all the environment variables
258 necessary to support this, including @env{PATH} and @env{GUILE_LOAD_PATH}.
260 Note that @command{./pre-inst-env guix pull} does @emph{not} upgrade the
261 local source tree; it simply updates the @file{~/.config/guix/current}
262 symlink (@pxref{Invoking guix pull}). Run @command{git pull} instead if
263 you want to upgrade your local source tree.
265 Sometimes, especially if you have recently updated your repository,
266 running @command{./pre-inst-env} will print a message similar to the
270 ;;; note: source file /home/user/projects/guix/guix/progress.scm
271 ;;; newer than compiled /home/user/projects/guix/guix/progress.go
274 This is only a note and you can safely ignore it. You can get rid of
275 the message by running @command{make -j4}. Until you do, Guile will run
276 slightly slower because it will interpret the code instead of using
277 prepared Guile object (@file{.go}) files.
279 You can run @command{make} automatically as you work using
280 @command{watchexec} from the @code{watchexec} package. For example,
281 to build again each time you update a package file, run
282 @samp{watchexec -w gnu/packages -- make -j4}.
284 @node The Perfect Setup
285 @section The Perfect Setup
287 The Perfect Setup to hack on Guix is basically the perfect setup used
288 for Guile hacking (@pxref{Using Guile in Emacs,,, guile, Guile Reference
289 Manual}). First, you need more than an editor, you need
290 @url{https://www.gnu.org/software/emacs, Emacs}, empowered by the
291 wonderful @url{https://nongnu.org/geiser/, Geiser}. To set that up, run:
294 guix install emacs guile emacs-geiser emacs-geiser-guile
297 Geiser allows for interactive and incremental development from within
298 Emacs: code compilation and evaluation from within buffers, access to
299 on-line documentation (docstrings), context-sensitive completion,
300 @kbd{M-.} to jump to an object definition, a REPL to try out your code,
301 and more (@pxref{Introduction,,, geiser, Geiser User Manual}). For
302 convenient Guix development, make sure to augment Guile’s load path so
303 that it finds source files from your checkout:
306 ;; @r{Assuming the Guix checkout is in ~/src/guix.}
307 (with-eval-after-load 'geiser-guile
308 (add-to-list 'geiser-guile-load-path "~/src/guix"))
311 To actually edit the code, Emacs already has a neat Scheme mode. But in
312 addition to that, you must not miss
313 @url{https://www.emacswiki.org/emacs/ParEdit, Paredit}. It provides
314 facilities to directly operate on the syntax tree, such as raising an
315 s-expression or wrapping it, swallowing or rejecting the following
318 @cindex code snippets
320 @cindex reducing boilerplate
321 We also provide templates for common git commit messages and package
322 definitions in the @file{etc/snippets} directory. These templates can
323 be used to expand short trigger strings to interactive text snippets. If
324 you use @url{https://joaotavora.github.io/yasnippet/, YASnippet}, you
325 may want to add the @file{etc/snippets/yas} snippets directory to the
326 @var{yas-snippet-dirs} variable. If you use
327 @url{https://github.com/minad/tempel/, Tempel}, you may want to add the
328 @file{etc/snippets/tempel/*} path to the @var{tempel-path} variable in
332 ;; @r{Assuming the Guix checkout is in ~/src/guix.}
333 ;; @r{Yasnippet configuration}
334 (with-eval-after-load 'yasnippet
335 (add-to-list 'yas-snippet-dirs "~/src/guix/etc/snippets/yas"))
336 ;; @r{Tempel configuration}
337 (with-eval-after-load 'tempel
338 ;; Ensure tempel-path is a list -- it may also be a string.
339 (unless (listp 'tempel-path)
340 (setq tempel-path (list tempel-path)))
341 (add-to-list 'tempel-path "~/src/guix/etc/snippets/tempel/*"))
344 The commit message snippets depend on @url{https://magit.vc/, Magit} to
345 display staged files. When editing a commit message type @code{add}
346 followed by @kbd{TAB} to insert a commit message template for adding a
347 package; type @code{update} followed by @kbd{TAB} to insert a template
348 for updating a package; type @code{https} followed by @kbd{TAB} to
349 insert a template for changing the home page URI of a package to HTTPS.
351 The main snippet for @code{scheme-mode} is triggered by typing
352 @code{package...} followed by @kbd{TAB}. This snippet also inserts the
353 trigger string @code{origin...}, which can be expanded further. The
354 @code{origin} snippet in turn may insert other trigger strings ending on
355 @code{...}, which also can be expanded further.
357 @cindex insert or update copyright
358 @cindex @code{M-x guix-copyright}
359 @cindex @code{M-x copyright-update}
360 We additionally provide insertion and automatic update of a copyright in
361 @file{etc/copyright.el}. You may want to set your full name, mail, and
365 (setq user-full-name "Alice Doe")
366 (setq user-mail-address "alice@@mail.org")
367 ;; @r{Assuming the Guix checkout is in ~/src/guix.}
368 (load-file "~/src/guix/etc/copyright.el")
371 To insert a copyright at the current line invoke @code{M-x guix-copyright}.
373 To update a copyright you need to specify a @code{copyright-names-regexp}.
376 (setq copyright-names-regexp
377 (format "%s <%s>" user-full-name user-mail-address))
380 You can check if your copyright is up to date by evaluating @code{M-x
381 copyright-update}. If you want to do it automatically after each buffer
382 save then add @code{(add-hook 'after-save-hook 'copyright-update)} in
385 @node Packaging Guidelines
386 @section Packaging Guidelines
388 @cindex packages, creating
389 The GNU distribution is nascent and may well lack some of your favorite
390 packages. This section describes how you can help make the distribution
393 Free software packages are usually distributed in the form of
394 @dfn{source code tarballs}---typically @file{tar.gz} files that contain
395 all the source files. Adding a package to the distribution means
396 essentially two things: adding a @dfn{recipe} that describes how to
397 build the package, including a list of other packages required to build
398 it, and adding @dfn{package metadata} along with that recipe, such as a
399 description and licensing information.
401 In Guix all this information is embodied in @dfn{package definitions}.
402 Package definitions provide a high-level view of the package. They are
403 written using the syntax of the Scheme programming language; in fact,
404 for each package we define a variable bound to the package definition,
405 and export that variable from a module (@pxref{Package Modules}).
406 However, in-depth Scheme knowledge is @emph{not} a prerequisite for
407 creating packages. For more information on package definitions,
408 @pxref{Defining Packages}.
410 Once a package definition is in place, stored in a file in the Guix
411 source tree, it can be tested using the @command{guix build} command
412 (@pxref{Invoking guix build}). For example, assuming the new package is
413 called @code{gnew}, you may run this command from the Guix build tree
414 (@pxref{Running Guix Before It Is Installed}):
417 ./pre-inst-env guix build gnew --keep-failed
420 Using @code{--keep-failed} makes it easier to debug build failures since
421 it provides access to the failed build tree. Another useful
422 command-line option when debugging is @code{--log-file}, to access the
425 If the package is unknown to the @command{guix} command, it may be that
426 the source file contains a syntax error, or lacks a @code{define-public}
427 clause to export the package variable. To figure it out, you may load
428 the module from Guile to get more information about the actual error:
431 ./pre-inst-env guile -c '(use-modules (gnu packages gnew))'
434 Once your package builds correctly, please send us a patch
435 (@pxref{Submitting Patches}). Well, if you need help, we will be happy to
436 help you too. Once the patch is committed in the Guix repository, the
437 new package automatically gets built on the supported platforms by
438 @url{https://@value{SUBSTITUTE-SERVER-1}, our continuous integration system}.
441 Users can obtain the new package definition simply by running
442 @command{guix pull} (@pxref{Invoking guix pull}). When
443 @code{@value{SUBSTITUTE-SERVER-1}} is done building the package, installing the
444 package automatically downloads binaries from there
445 (@pxref{Substitutes}). The only place where human intervention is
446 needed is to review and apply the patch.
450 * Software Freedom:: What may go into the distribution.
451 * Package Naming:: What's in a name?
452 * Version Numbers:: When the name is not enough.
453 * Synopses and Descriptions:: Helping users find the right package.
454 * Snippets versus Phases:: Whether to use a snippet, or a build phase.
455 * Emacs Packages:: Your Elisp fix.
456 * Python Modules:: A touch of British comedy.
457 * Perl Modules:: Little pearls.
458 * Java Packages:: Coffee break.
459 * Rust Crates:: Beware of oxidation.
460 * Elm Packages:: Trees of browser code
461 * Fonts:: Fond of fonts.
464 @node Software Freedom
465 @subsection Software Freedom
467 @c Adapted from http://www.gnu.org/philosophy/philosophy.html.
468 @cindex free software
469 The GNU operating system has been developed so that users can have
470 freedom in their computing. GNU is @dfn{free software}, meaning that
471 users have the @url{https://www.gnu.org/philosophy/free-sw.html,four
472 essential freedoms}: to run the program, to study and change the program
473 in source code form, to redistribute exact copies, and to distribute
474 modified versions. Packages found in the GNU distribution provide only
475 software that conveys these four freedoms.
477 In addition, the GNU distribution follow the
478 @url{https://www.gnu.org/distros/free-system-distribution-guidelines.html,free
479 software distribution guidelines}. Among other things, these guidelines
480 reject non-free firmware, recommendations of non-free software, and
481 discuss ways to deal with trademarks and patents.
483 Some otherwise free upstream package sources contain a small and optional
484 subset that violates the above guidelines, for instance because this subset
485 is itself non-free code. When that happens, the offending items are removed
486 with appropriate patches or code snippets in the @code{origin} form of the
487 package (@pxref{Defining Packages}). This way, @code{guix
488 build --source} returns the ``freed'' source rather than the unmodified
493 @subsection Package Naming
496 A package actually has two names associated with it.
497 First, there is the name of the @emph{Scheme variable}, the one following
498 @code{define-public}. By this name, the package can be made known in the
499 Scheme code, for instance as input to another package. Second, there is
500 the string in the @code{name} field of a package definition. This name
501 is used by package management commands such as
502 @command{guix package} and @command{guix build}.
504 Both are usually the same and correspond to the lowercase conversion of
505 the project name chosen upstream, with underscores replaced with
506 hyphens. For instance, GNUnet is available as @code{gnunet}, and
507 SDL_net as @code{sdl-net}.
509 A noteworthy exception to this rule is when the project name is only a
510 single character, or if an older maintained project with the same name
511 already exists---regardless of whether it has already been packaged for
512 Guix. Use common sense to make such names unambiguous and meaningful.
513 For example, Guix's package for the shell called ``s'' upstream is
514 @code{s-shell} and @emph{not} @code{s}. Feel free to ask your fellow
515 hackers for inspiration.
517 We do not add @code{lib} prefixes for library packages, unless these are
518 already part of the official project name. But @pxref{Python
519 Modules} and @ref{Perl Modules} for special rules concerning modules for
520 the Python and Perl languages.
522 Font package names are handled differently, @pxref{Fonts}.
525 @node Version Numbers
526 @subsection Version Numbers
528 @cindex package version
529 We usually package only the latest version of a given free software
530 project. But sometimes, for instance for incompatible library versions,
531 two (or more) versions of the same package are needed. These require
532 different Scheme variable names. We use the name as defined
533 in @ref{Package Naming}
534 for the most recent version; previous versions use the same name, suffixed
535 by @code{-} and the smallest prefix of the version number that may
536 distinguish the two versions.
538 The name inside the package definition is the same for all versions of a
539 package and does not contain any version number.
541 For instance, the versions 2.24.20 and 3.9.12 of GTK+ may be packaged as follows:
549 (define-public gtk+-2
555 If we also wanted GTK+ 3.8.2, this would be packaged as
557 (define-public gtk+-3.8
564 @c See <https://lists.gnu.org/archive/html/guix-devel/2016-01/msg00425.html>,
565 @c for a discussion of what follows.
566 @cindex version number, for VCS snapshots
567 Occasionally, we package snapshots of upstream's version control system
568 (VCS) instead of formal releases. This should remain exceptional,
569 because it is up to upstream developers to clarify what the stable
570 release is. Yet, it is sometimes necessary. So, what should we put in
571 the @code{version} field?
573 Clearly, we need to make the commit identifier of the VCS snapshot
574 visible in the version string, but we also need to make sure that the
575 version string is monotonically increasing so that @command{guix package
576 --upgrade} can determine which version is newer. Since commit
577 identifiers, notably with Git, are not monotonically increasing, we add
578 a revision number that we increase each time we upgrade to a newer
579 snapshot. The resulting version string looks like this:
584 | | `-- upstream commit ID
586 | `--- Guix package revision
588 latest upstream version
591 It is a good idea to strip commit identifiers in the @code{version}
592 field to, say, 7 digits. It avoids an aesthetic annoyance (assuming
593 aesthetics have a role to play here) as well as problems related to OS
594 limits such as the maximum shebang length (127 bytes for the Linux
595 kernel). There are helper functions for doing this for packages using
596 @code{git-fetch} or @code{hg-fetch} (see below). It is best to use the
597 full commit identifiers in @code{origin}s, though, to avoid ambiguities.
598 A typical package definition may look like this:
603 (let ((commit "c3f29bc928d5900971f65965feaae59e1272a3f7")
604 (revision "1")) ;Guix package revision
606 (version (git-version "0.9" revision commit))
610 (url "git://example.org/my-package.git")
612 (sha256 (base32 "1mbikn@dots{}"))
613 (file-name (git-file-name name version))))
618 @deffn {Scheme Procedure} git-version @var{VERSION} @var{REVISION} @var{COMMIT}
619 Return the version string for packages using @code{git-fetch}.
622 (git-version "0.2.3" "0" "93818c936ee7e2f1ba1b315578bde363a7d43d05")
623 @result{} "0.2.3-0.93818c9"
627 @deffn {Scheme Procedure} hg-version @var{VERSION} @var{REVISION} @var{CHANGESET}
628 Return the version string for packages using @code{hg-fetch}. It works
629 in the same way as @code{git-version}.
632 @node Synopses and Descriptions
633 @subsection Synopses and Descriptions
635 @cindex package description
636 @cindex package synopsis
637 As we have seen before, each package in GNU@tie{}Guix includes a
638 synopsis and a description (@pxref{Defining Packages}). Synopses and
639 descriptions are important: They are what @command{guix package
640 --search} searches, and a crucial piece of information to help users
641 determine whether a given package suits their needs. Consequently,
642 packagers should pay attention to what goes into them.
644 Synopses must start with a capital letter and must not end with a
645 period. They must not start with ``a'' or ``the'', which usually does
646 not bring anything; for instance, prefer ``File-frobbing tool'' over ``A
647 tool that frobs files''. The synopsis should say what the package
648 is---e.g., ``Core GNU utilities (file, text, shell)''---or what it is
649 used for---e.g., the synopsis for GNU@tie{}grep is ``Print lines
650 matching a pattern''.
652 Keep in mind that the synopsis must be meaningful for a very wide
653 audience. For example, ``Manipulate alignments in the SAM format''
654 might make sense for a seasoned bioinformatics researcher, but might be
655 fairly unhelpful or even misleading to a non-specialized audience. It
656 is a good idea to come up with a synopsis that gives an idea of the
657 application domain of the package. In this example, this might give
658 something like ``Manipulate nucleotide sequence alignments'', which
659 hopefully gives the user a better idea of whether this is what they are
662 Descriptions should take between five and ten lines. Use full
663 sentences, and avoid using acronyms without first introducing them.
664 Please avoid marketing phrases such as ``world-leading'',
665 ``industrial-strength'', and ``next-generation'', and avoid superlatives
666 like ``the most advanced''---they are not helpful to users looking for a
667 package and may even sound suspicious. Instead, try to be factual,
668 mentioning use cases and features.
670 @cindex Texinfo markup, in package descriptions
671 Descriptions can include Texinfo markup, which is useful to introduce
672 ornaments such as @code{@@code} or @code{@@dfn}, bullet lists, or
673 hyperlinks (@pxref{Overview,,, texinfo, GNU Texinfo}). However you
674 should be careful when using some characters for example @samp{@@} and
675 curly braces which are the basic special characters in Texinfo
676 (@pxref{Special Characters,,, texinfo, GNU Texinfo}). User interfaces
677 such as @command{guix show} take care of rendering it
680 Synopses and descriptions are translated by volunteers
681 @uref{https://translate.fedoraproject.org/projects/guix/packages, at
682 Weblate} so that as many users as possible can read them in
683 their native language. User interfaces search them and display them in
684 the language specified by the current locale.
686 To allow @command{xgettext} to extract them as translatable strings,
687 synopses and descriptions @emph{must be literal strings}. This means
688 that you cannot use @code{string-append} or @code{format} to construct
694 (synopsis "This is translatable")
695 (description (string-append "This is " "*not*" " translatable.")))
698 Translation is a lot of work so, as a packager, please pay even more
699 attention to your synopses and descriptions as every change may entail
700 additional work for translators. In order to help them, it is possible
701 to make recommendations or instructions visible to them by inserting
702 special comments like this (@pxref{xgettext Invocation,,, gettext, GNU
706 ;; TRANSLATORS: "X11 resize-and-rotate" should not be translated.
707 (description "ARandR is designed to provide a simple visual front end
708 for the X11 resize-and-rotate (RandR) extension. @dots{}")
711 @node Snippets versus Phases
712 @subsection Snippets versus Phases
714 @cindex snippets, when to use
715 The boundary between using an origin snippet versus a build phase to
716 modify the sources of a package can be elusive. Origin snippets are
717 typically used to remove unwanted files such as bundled libraries,
718 nonfree sources, or to apply simple substitutions. The source derived
719 from an origin should produce a source that can be used to build the
720 package on any system that the upstream package supports (i.e., act as
721 the corresponding source). In particular, origin snippets must not
722 embed store items in the sources; such patching should rather be done
723 using build phases. Refer to the @code{origin} record documentation for
724 more information (@pxref{origin Reference}).
727 @subsection Emacs Packages
729 @cindex emacs, packaging
730 @cindex elisp, packaging
731 Emacs packages should preferably use the Emacs build system
732 (@pxref{emacs-build-system}), for uniformity and the benefits provided
733 by its build phases, such as the auto-generation of the autoloads file
734 and the byte compilation of the sources. Because there is no
735 standardized way to run a test suite for Emacs packages, tests are
736 disabled by default. When a test suite is available, it should be
737 enabled by setting the @code{#:tests?} argument to @code{#true}. By
738 default, the command to run the test is @command{make check}, but any
739 command can be specified via the @code{#:test-command} argument. The
740 @code{#:test-command} argument expects a list containing a command and
741 its arguments, to be invoked during the @code{check} phase.
743 The Elisp dependencies of Emacs packages are typically provided as
744 @code{propagated-inputs} when required at run time. As for other
745 packages, build or test dependencies should be specified as
746 @code{native-inputs}.
748 Emacs packages sometimes depend on resources directories that should be
749 installed along the Elisp files. The @code{#:include} argument can be
750 used for that purpose, by specifying a list of regexps to match. The
751 best practice when using the @code{#:include} argument is to extend
752 rather than override its default value (accessible via the
753 @code{%default-include} variable). As an example, a yasnippet extension
754 package typically include a @file{snippets} directory, which could be
755 copied to the installation directory using:
758 #:include (cons "^snippets/" %default-include)
761 When encountering problems, it is wise to check for the presence of the
762 @code{Package-Requires} extension header in the package main source
763 file, and whether any dependencies and their versions listed therein are
767 @subsection Python Modules
770 We currently package Python 2 and Python 3, under the Scheme variable names
771 @code{python-2} and @code{python} as explained in @ref{Version Numbers}.
772 To avoid confusion and naming clashes with other programming languages, it
773 seems desirable that the name of a package for a Python module contains
774 the word @code{python}.
776 Some modules are compatible with only one version of Python, others with
777 both. If the package Foo is compiled with Python 3, we name it
778 @code{python-foo}. If it is compiled with Python 2, we name it
779 @code{python2-foo}. Packages should be added when they are necessary;
780 we don't add Python 2 variants of the package unless we are going to use
783 If a project already contains the word @code{python}, we drop this;
784 for instance, the module python-dateutil is packaged under the names
785 @code{python-dateutil} and @code{python2-dateutil}. If the project name
786 starts with @code{py} (e.g.@: @code{pytz}), we keep it and prefix it as
790 Currently there are two different build systems for Python packages in Guix:
791 @var{python-build-system} and @var{pyproject-build-system}. For the
792 longest time, Python packages were built from an informally specified
793 @file{setup.py} file. That worked amazingly well, considering Python's
794 success, but was difficult to build tooling around. As a result, a host
795 of alternative build systems emerged and the community eventually settled on a
796 @url{https://peps.python.org/pep-0517/, formal standard} for specifying build
797 requirements. @var{pyproject-build-system} is Guix's implementation of this
798 standard. It is considered ``experimental'' in that it does not yet support
799 all the various PEP-517 @emph{build backends}, but you are encouraged to try
800 it for new Python packages and report any problems. It will eventually be
801 deprecated and merged into @var{python-build-system}.
804 @subsubsection Specifying Dependencies
805 @cindex inputs, for Python packages
807 Dependency information for Python packages is usually available in the
808 package source tree, with varying degrees of accuracy: in the
809 @file{pyproject.toml} file, the @file{setup.py} file, in
810 @file{requirements.txt}, or in @file{tox.ini} (the latter mostly for
813 Your mission, when writing a recipe for a Python package, is to map
814 these dependencies to the appropriate type of ``input'' (@pxref{package
815 Reference, inputs}). Although the @code{pypi} importer normally does a
816 good job (@pxref{Invoking guix import}), you may want to check the
817 following check list to determine which dependency goes where.
822 We currently package Python with @code{setuptools} and @code{pip}
823 installed per default. This is about to change, and users are encouraged
824 to use @code{python-toolchain} if they want a build environment for Python.
826 @command{guix lint} will warn if @code{setuptools} or @code{pip} are
827 added as native-inputs because they are generally not necessary.
830 Python dependencies required at run time go into
831 @code{propagated-inputs}. They are typically defined with the
832 @code{install_requires} keyword in @file{setup.py}, or in the
833 @file{requirements.txt} file.
836 Python packages required only at build time---e.g., those listed under
837 @code{build-system.requires} in @file{pyproject.toml} or with the
838 @code{setup_requires} keyword in @file{setup.py}---or dependencies only
839 for testing---e.g., those in @code{tests_require} or @file{tox.ini}---go into
840 @code{native-inputs}. The rationale is that (1) they do not need to be
841 propagated because they are not needed at run time, and (2) in a
842 cross-compilation context, it's the ``native'' input that we'd want.
844 Examples are the @code{pytest}, @code{mock}, and @code{nose} test
845 frameworks. Of course if any of these packages is also required at
846 run-time, it needs to go to @code{propagated-inputs}.
849 Anything that does not fall in the previous categories goes to
850 @code{inputs}, for example programs or C libraries required for building
851 Python packages containing C extensions.
854 If a Python package has optional dependencies (@code{extras_require}),
855 it is up to you to decide whether to add them or not, based on their
856 usefulness/overhead ratio (@pxref{Submitting Patches, @command{guix
863 @subsection Perl Modules
866 Perl programs standing for themselves are named as any other package,
867 using the lowercase upstream name.
868 For Perl packages containing a single class, we use the lowercase class name,
869 replace all occurrences of @code{::} by dashes and prepend the prefix
871 So the class @code{XML::Parser} becomes @code{perl-xml-parser}.
872 Modules containing several classes keep their lowercase upstream name and
873 are also prepended by @code{perl-}. Such modules tend to have the word
874 @code{perl} somewhere in their name, which gets dropped in favor of the
875 prefix. For instance, @code{libwww-perl} becomes @code{perl-libwww}.
879 @subsection Java Packages
882 Java programs standing for themselves are named as any other package,
883 using the lowercase upstream name.
885 To avoid confusion and naming clashes with other programming languages,
886 it is desirable that the name of a package for a Java package is
887 prefixed with @code{java-}. If a project already contains the word
888 @code{java}, we drop this; for instance, the package @code{ngsjava} is
889 packaged under the name @code{java-ngs}.
891 For Java packages containing a single class or a small class hierarchy,
892 we use the lowercase class name, replace all occurrences of @code{.} by
893 dashes and prepend the prefix @code{java-}. So the class
894 @code{apache.commons.cli} becomes package
895 @code{java-apache-commons-cli}.
899 @subsection Rust Crates
902 Rust programs standing for themselves are named as any other package, using the
903 lowercase upstream name.
905 To prevent namespace collisions we prefix all other Rust packages with the
906 @code{rust-} prefix. The name should be changed to lowercase as appropriate and
907 dashes should remain in place.
909 In the rust ecosystem it is common for multiple incompatible versions of a
910 package to be used at any given time, so all package definitions should have a
911 versioned suffix. The versioned suffix is the left-most non-zero digit (and
912 any leading zeros, of course). This follows the ``caret'' version scheme
913 intended by Cargo. Examples@: @code{rust-clap-2}, @code{rust-rand-0.6}.
915 Because of the difficulty in reusing rust packages as pre-compiled inputs for
916 other packages the Cargo build system (@pxref{Build Systems,
917 @code{cargo-build-system}}) presents the @code{#:cargo-inputs} and
918 @code{cargo-development-inputs} keywords as build system arguments. It would be
919 helpful to think of these as similar to @code{propagated-inputs} and
920 @code{native-inputs}. Rust @code{dependencies} and @code{build-dependencies}
921 should go in @code{#:cargo-inputs}, and @code{dev-dependencies} should go in
922 @code{#:cargo-development-inputs}. If a Rust package links to other libraries
923 then the standard placement in @code{inputs} and the like should be used.
925 Care should be taken to ensure the correct version of dependencies are used; to
926 this end we try to refrain from skipping the tests or using @code{#:skip-build?}
927 when possible. Of course this is not always possible, as the package may be
928 developed for a different Operating System, depend on features from the Nightly
929 Rust compiler, or the test suite may have atrophied since it was released.
933 @subsection Elm Packages
936 Elm applications can be named like other software: their names need not
939 Packages in the Elm sense (see @code{elm-build-system} under @ref{Build
940 Systems}) are required use names of the format
941 @var{author}@code{/}@var{project}, where both the @var{author} and the
942 @var{project} may contain hyphens internally, and the @var{author} sometimes
943 contains uppercase letters.
945 To form the Guix package name from the upstream name, we follow a convention
946 similar to Python packages (@pxref{Python Modules}), adding an @code{elm-}
947 prefix unless the name would already begin with @code{elm-}.
949 In many cases we can reconstruct an Elm package's upstream name heuristically,
950 but, since conversion to a Guix-style name involves a loss of information,
951 this is not always possible. Care should be taken to add the
952 @code{'upstream-name} property when necessary so that @samp{guix import elm}
953 will work correctly (@pxref{Invoking guix import}). The most notable scenarios
954 when explicitly specifying the upstream name is necessary are:
958 When the @var{author} is @code{elm} and the @var{project} contains one or more
959 hyphens, as with @code{elm/virtual-dom}; and
962 When the @var{author} contains hyphens or uppercase letters, as with
963 @code{Elm-Canvas/raster-shapes}---unless the @var{author} is
964 @code{elm-explorations}, which is handled as a special case, so packages like
965 @code{elm-explorations/markdown} do @emph{not} need to use the
966 @code{'upstream-name} property.
969 The module @code{(guix build-system elm)} provides the following utilities for
970 working with names and related conventions:
972 @deffn {Scheme procedure} elm-package-origin @var{elm-name} @var{version} @
974 Returns a Git origin using the repository naming and tagging regime required
975 for a published Elm package with the upstream name @var{elm-name} at version
976 @var{version} with sha256 checksum @var{hash}.
987 (base32 "15k1679ja57vvlpinpv06znmrxy09lbhzfkzdc89i01qa8c4gb4a")))
992 @deffn {Scheme procedure} elm->package-name @var{elm-name}
993 Returns the Guix-style package name for an Elm package with upstream name
996 Note that there is more than one possible @var{elm-name} for which
997 @code{elm->package-name} will produce a given result.
1000 @deffn {Scheme procedure} guix-package->elm-name @var{package}
1001 Given an Elm @var{package}, returns the possibly-inferred upstream name, or
1002 @code{#f} the upstream name is not specified via the @code{'upstream-name}
1003 property and can not be inferred by @code{infer-elm-package-name}.
1006 @deffn {Scheme procedure} infer-elm-package-name @var{guix-name}
1007 Given the @var{guix-name} of an Elm package, returns the inferred upstream
1008 name, or @code{#f} if the upstream name can't be inferred. If the result is
1009 not @code{#f}, supplying it to @code{elm->package-name} would produce
1017 For fonts that are in general not installed by a user for typesetting
1018 purposes, or that are distributed as part of a larger software package,
1019 we rely on the general packaging rules for software; for instance, this
1020 applies to the fonts delivered as part of the X.Org system or fonts that
1021 are part of TeX Live.
1023 To make it easier for a user to search for fonts, names for other packages
1024 containing only fonts are constructed as follows, independently of the
1025 upstream package name.
1027 The name of a package containing only one font family starts with
1028 @code{font-}; it is followed by the foundry name and a dash @code{-}
1029 if the foundry is known, and the font family name, in which spaces are
1030 replaced by dashes (and as usual, all upper case letters are transformed
1032 For example, the Gentium font family by SIL is packaged under the name
1033 @code{font-sil-gentium}.
1035 For a package containing several font families, the name of the collection
1036 is used in the place of the font family name.
1037 For instance, the Liberation fonts consist of three families,
1038 Liberation Sans, Liberation Serif and Liberation Mono.
1039 These could be packaged separately under the names
1040 @code{font-liberation-sans} and so on; but as they are distributed together
1041 under a common name, we prefer to package them together as
1042 @code{font-liberation}.
1044 In the case where several formats of the same font family or font collection
1045 are packaged separately, a short form of the format, prepended by a dash,
1046 is added to the package name. We use @code{-ttf} for TrueType fonts,
1047 @code{-otf} for OpenType fonts and @code{-type1} for PostScript Type 1
1052 @section Coding Style
1054 In general our code follows the GNU Coding Standards (@pxref{Top,,,
1055 standards, GNU Coding Standards}). However, they do not say much about
1056 Scheme, so here are some additional rules.
1059 * Programming Paradigm:: How to compose your elements.
1060 * Modules:: Where to store your code?
1061 * Data Types and Pattern Matching:: Implementing data structures.
1062 * Formatting Code:: Writing conventions.
1065 @node Programming Paradigm
1066 @subsection Programming Paradigm
1068 Scheme code in Guix is written in a purely functional style. One
1069 exception is code that involves input/output, and procedures that
1070 implement low-level concepts, such as the @code{memoize} procedure.
1075 Guile modules that are meant to be used on the builder side must live in
1076 the @code{(guix build @dots{})} name space. They must not refer to
1077 other Guix or GNU modules. However, it is OK for a ``host-side'' module
1078 to use a build-side module.
1080 Modules that deal with the broader GNU system should be in the
1081 @code{(gnu @dots{})} name space rather than @code{(guix @dots{})}.
1083 @node Data Types and Pattern Matching
1084 @subsection Data Types and Pattern Matching
1086 The tendency in classical Lisp is to use lists to represent everything,
1087 and then to browse them ``by hand'' using @code{car}, @code{cdr},
1088 @code{cadr}, and co. There are several problems with that style,
1089 notably the fact that it is hard to read, error-prone, and a hindrance
1090 to proper type error reports.
1092 Guix code should define appropriate data types (for instance, using
1093 @code{define-record-type*}) rather than abuse lists. In addition, it
1094 should use pattern matching, via Guile’s @code{(ice-9 match)} module,
1095 especially when matching lists (@pxref{Pattern Matching,,, guile, GNU
1096 Guile Reference Manual}).
1098 @node Formatting Code
1099 @subsection Formatting Code
1101 @cindex formatting code
1102 @cindex coding style
1103 When writing Scheme code, we follow common wisdom among Scheme
1104 programmers. In general, we follow the
1105 @url{https://mumble.net/~campbell/scheme/style.txt, Riastradh's Lisp
1106 Style Rules}. This document happens to describe the conventions mostly
1107 used in Guile’s code too. It is very thoughtful and well written, so
1110 Some special forms introduced in Guix, such as the @code{substitute*}
1111 macro, have special indentation rules. These are defined in the
1112 @file{.dir-locals.el} file, which Emacs automatically uses. Also note
1113 that Emacs-Guix provides @code{guix-devel-mode} mode that indents and
1114 highlights Guix code properly (@pxref{Development,,, emacs-guix, The
1115 Emacs-Guix Reference Manual}).
1117 @cindex indentation, of code
1118 @cindex formatting, of code
1119 If you do not use Emacs, please make sure to let your editor knows these
1120 rules. To automatically indent a package definition, you can also run:
1123 ./pre-inst-env guix style @var{package}
1127 @xref{Invoking guix style}, for more information.
1129 @cindex Vim, Scheme code editing
1130 If you are editing code with Vim, we recommend that you run @code{:set
1131 autoindent} so that your code is automatically indented as you type.
1133 @uref{https://www.vim.org/scripts/script.php?script_id=3998,
1134 @code{paredit.vim}} may help you deal with all these parentheses.
1136 We require all top-level procedures to carry a docstring. This
1137 requirement can be relaxed for simple private procedures in the
1138 @code{(guix build @dots{})} name space, though.
1140 Procedures should not have more than four positional parameters. Use
1141 keyword parameters for procedures that take more than four parameters.
1144 @node Submitting Patches
1145 @section Submitting Patches
1147 Development is done using the Git distributed version control system.
1148 Thus, access to the repository is not strictly necessary. We welcome
1149 contributions in the form of patches as produced by @code{git
1150 format-patch} sent to the @email{guix-patches@@gnu.org} mailing list
1151 (@pxref{Submitting patches to a project,,, git, Git User Manual}).
1152 Contributors are encouraged to take a moment to set some Git repository
1153 options (@pxref{Configuring Git}) first, which can improve the
1154 readability of patches. Seasoned Guix developers may also want to look
1155 at the section on commit access (@pxref{Commit Access}).
1157 This mailing list is backed by a Debbugs instance, which allows us to
1158 keep track of submissions (@pxref{Tracking Bugs and Patches}). Each
1159 message sent to that mailing list gets a new tracking number assigned;
1160 people can then follow up on the submission by sending email to
1161 @code{@var{NNN}@@debbugs.gnu.org}, where @var{NNN} is the tracking
1162 number (@pxref{Sending a Patch Series}).
1164 Please write commit logs in the ChangeLog format (@pxref{Change Logs,,,
1165 standards, GNU Coding Standards}); you can check the commit history for
1168 Before submitting a patch that adds or modifies a package definition,
1169 please run through this check list:
1172 @cindex @code{git format-patch}
1173 @cindex @code{git-format-patch}
1175 When generating your patches with @code{git format-patch} or @code{git
1176 send-email}, we recommend using the option @code{--base=}, perhaps with
1177 the value @code{auto}. This option adds a note to the patch stating
1178 which commit the patch is based on. This helps reviewers understand how
1179 to apply and review your patches.
1182 If the authors of the packaged software provide a cryptographic
1183 signature for the release tarball, make an effort to verify the
1184 authenticity of the archive. For a detached GPG signature file this
1185 would be done with the @code{gpg --verify} command.
1188 Take some time to provide an adequate synopsis and description for the
1189 package. @xref{Synopses and Descriptions}, for some guidelines.
1192 Run @code{guix lint @var{package}}, where @var{package} is the
1193 name of the new or modified package, and fix any errors it reports
1194 (@pxref{Invoking guix lint}).
1197 Run @code{guix style @var{package}} to format the new package definition
1198 according to the project's conventions (@pxref{Invoking guix style}).
1201 Make sure the package builds on your platform, using @code{guix build
1205 We recommend you also try building the package on other supported
1206 platforms. As you may not have access to actual hardware platforms, we
1207 recommend using the @code{qemu-binfmt-service-type} to emulate them. In
1208 order to enable it, add the @code{virtualization} service module and the
1209 following service to the list of services in your @code{operating-system}
1213 (service qemu-binfmt-service-type
1214 (qemu-binfmt-configuration
1215 (platforms (lookup-qemu-platforms "arm" "aarch64"))))
1218 Then reconfigure your system.
1220 You can then build packages for different platforms by specifying the
1221 @code{--system} option. For example, to build the "hello" package for
1222 the armhf or aarch64 architectures, you would run the following
1223 commands, respectively:
1225 guix build --system=armhf-linux --rounds=2 hello
1226 guix build --system=aarch64-linux --rounds=2 hello
1231 Make sure the package does not use bundled copies of software already
1232 available as separate packages.
1234 Sometimes, packages include copies of the source code of their
1235 dependencies as a convenience for users. However, as a distribution, we
1236 want to make sure that such packages end up using the copy we already
1237 have in the distribution, if there is one. This improves resource usage
1238 (the dependency is built and stored only once), and allows the
1239 distribution to make transverse changes such as applying security
1240 updates for a given software package in a single place and have them
1241 affect the whole system---something that bundled copies prevent.
1244 Take a look at the profile reported by @command{guix size}
1245 (@pxref{Invoking guix size}). This will allow you to notice references
1246 to other packages unwillingly retained. It may also help determine
1247 whether to split the package (@pxref{Packages with Multiple Outputs}),
1248 and which optional dependencies should be used. In particular, avoid adding
1249 @code{texlive} as a dependency: because of its extreme size, use
1250 the @code{texlive-tiny} package or @code{texlive-union} procedure instead.
1253 For important changes, check that dependent packages (if applicable) are
1254 not affected by the change; @code{guix refresh --list-dependent
1255 @var{package}} will help you do that (@pxref{Invoking guix refresh}).
1257 @c See <https://lists.gnu.org/archive/html/guix-devel/2016-10/msg00933.html>.
1258 @cindex branching strategy
1259 @cindex rebuild scheduling strategy
1260 Depending on the number of dependent packages and thus the amount of
1261 rebuilding induced, commits go to different branches, along these lines:
1264 @item 300 dependent packages or less
1265 @code{master} branch (non-disruptive changes).
1267 @item between 300 and 1,800 dependent packages
1268 @code{staging} branch (non-disruptive changes). This branch is intended
1269 to be merged in @code{master} every 6 weeks or so. Topical changes
1270 (e.g., an update of the GNOME stack) can instead go to a specific branch
1271 (say, @code{gnome-updates}). This branch is not expected to be
1272 buildable or usable until late in its development process.
1274 @item more than 1,800 dependent packages
1275 @code{core-updates} branch (may include major and potentially disruptive
1276 changes). This branch is intended to be merged in @code{master} every
1277 6 months or so. This branch is not expected to be buildable or usable
1278 until late in its development process.
1281 All these branches are @uref{https://@value{SUBSTITUTE-SERVER-1},
1282 tracked by our build farm} and merged into @code{master} once
1283 everything has been successfully built. This allows us to fix issues
1284 before they hit users, and to reduce the window during which pre-built
1285 binaries are not available.
1287 When we decide to start building the @code{staging} or
1288 @code{core-updates} branches, they will be forked and renamed with the
1289 suffix @code{-frozen}, at which time only bug fixes may be pushed to the
1290 frozen branches. The @code{core-updates} and @code{staging} branches
1291 will remain open to accept patches for the next cycle. Please ask on
1292 the mailing list or IRC if unsure where to place a patch.
1293 @c TODO: It would be good with badges on the website that tracks these
1294 @c branches. Or maybe even a status page.
1297 @cindex determinism, of build processes
1298 @cindex reproducible builds, checking
1299 Check whether the package's build process is deterministic. This
1300 typically means checking whether an independent build of the package
1301 yields the exact same result that you obtained, bit for bit.
1303 A simple way to do that is by building the same package several times in
1304 a row on your machine (@pxref{Invoking guix build}):
1307 guix build --rounds=2 my-package
1310 This is enough to catch a class of common non-determinism issues, such
1311 as timestamps or randomly-generated output in the build result.
1313 Another option is to use @command{guix challenge} (@pxref{Invoking guix
1314 challenge}). You may run it once the package has been committed and
1315 built by @code{@value{SUBSTITUTE-SERVER-1}} to check whether it obtains the same
1316 result as you did. Better yet: Find another machine that can build it
1317 and run @command{guix publish}. Since the remote build machine is
1318 likely different from yours, this can catch non-determinism issues
1319 related to the hardware---e.g., use of different instruction set
1320 extensions---or to the operating system kernel---e.g., reliance on
1321 @code{uname} or @file{/proc} files.
1324 When writing documentation, please use gender-neutral wording when
1325 referring to people, such as
1326 @uref{https://en.wikipedia.org/wiki/Singular_they, singular
1327 ``they''@comma{} ``their''@comma{} ``them''}, and so forth.
1330 Verify that your patch contains only one set of related changes.
1331 Bundling unrelated changes together makes reviewing harder and slower.
1333 Examples of unrelated changes include the addition of several packages,
1334 or a package update along with fixes to that package.
1337 Please follow our code formatting rules, possibly running
1338 @command{guix style} script to do that automatically for you
1339 (@pxref{Formatting Code}).
1342 When possible, use mirrors in the source URL (@pxref{Invoking guix download}).
1343 Use reliable URLs, not generated ones. For instance, GitHub archives are not
1344 necessarily identical from one generation to the next, so in this case it's
1345 often better to clone the repository. Don't use the @command{name} field in
1346 the URL: it is not very useful and if the name changes, the URL will probably
1350 Check if Guix builds (@pxref{Building from Git}) and address the
1351 warnings, especially those about use of undefined symbols.
1354 Make sure your changes do not break Guix and simulate a @code{guix pull} with:
1356 guix pull --url=/path/to/your/checkout --profile=/tmp/guix.master
1361 When posting a patch to the mailing list, use @samp{[PATCH] @dots{}} as
1362 a subject, if your patch is to be applied on a branch other than
1363 @code{master}, say @code{core-updates}, specify it in the subject like
1364 @samp{[PATCH core-updates] @dots{}}.
1367 To add a prefix to the subject of your patch, you may use the
1368 @option{--subject-prefix} option of the @command{git format-patch} or
1369 @command{git send-email} commands, for example:
1371 git send-email --subject-prefix='PATCH core-updates' \
1372 --to=guix-patches@@gnu.org -1
1374 For more information, run @samp{man git-format-patch} and @samp{man
1378 You may use your email client or the @command{git send-email} command
1379 (@pxref{Sending a Patch Series}). We prefer to get patches in plain
1380 text messages, either inline or as MIME attachments. You are advised to
1381 pay attention if your email client changes anything like line breaks or
1382 indentation which could potentially break the patches.
1384 Expect some delay when you submit your very first patch to
1385 @email{guix-patches@@gnu.org}. You have to wait until you get an
1386 acknowledgement with the assigned tracking number. Future acknowledgements
1387 should not be delayed.
1389 When a bug is resolved, please close the thread by sending an email to
1390 @email{@var{NNN}-done@@debbugs.gnu.org}.
1392 @node Configuring Git
1393 @subsection Configuring Git
1394 @cindex git configuration
1395 @cindex @code{git format-patch}
1396 @cindex @code{git send-email}
1398 If you have not done so already, you may wish to set a name and email
1399 that will be associated with your commits (@pxref{telling git your name,
1400 , Telling Git your name, git, Git User Manual}). If you wish to use a
1401 different name or email just for commits in this repository, you can
1402 use @command{git config --local}, or edit @file{.git/config} in the
1403 repository instead of @file{~/.gitconfig}.
1405 We provide some default settings in @file{etc/git/gitconfig} which
1406 modify how patches are generated, making them easier to read and apply.
1407 These settings can be applied by manually copying them to
1408 @file{.git/config} in your checkout, or by telling Git to include the
1412 git config --local include.path ../etc/git/gitconfig
1415 From then on, any changes to @file{etc/git/gitconfig} would
1416 automatically take effect.
1418 Since the first patch in a series must be sent separately
1419 (@pxref{Sending a Patch Series}), it can also be helpful to tell
1420 @command{git format-patch} to handle the e-mail threading instead of
1421 @command{git send-email}:
1424 git config --local format.thread shallow
1425 git config --local sendemail.thread no
1428 @unnumberedsubsec Sending a Patch Series
1429 @anchor{Sending a Patch Series}
1430 @cindex patch series
1431 @cindex @code{git send-email}
1433 When sending a patch series (e.g., using @code{git send-email}), please
1434 first send one message to @email{guix-patches@@gnu.org}, and then send
1435 subsequent patches to @email{@var{NNN}@@debbugs.gnu.org} to make sure
1436 they are kept together. See
1437 @uref{https://debbugs.gnu.org/Advanced.html, the Debbugs documentation}
1438 for more information. You can install @command{git send-email} with
1439 @command{guix install git:send-email}.
1440 @c Debbugs bug: https://debbugs.gnu.org/db/15/15361.html
1442 To maximize the chances that you patch series is reviewed, the preferred
1443 submission way is to use the @code{etc/teams.scm} script to notify the
1444 appropriate team members (@pxref{Teams}).
1446 @unnumberedsubsec Teams
1450 There are several teams mentoring different parts of the Guix source
1451 code. To list all those teams, you can run from a Guix checkout:
1454 $ ./etc/teams.scm list-teams
1457 description: A group of mentors who chaperone contributions by newcomers.
1459 + Christopher Baines <mail@@cbaines.net>
1460 + Ricardo Wurmus <rekado@@elephly.net>
1461 + Mathieu Othacehe <othacehe@@gnu.org>
1462 + jgart <jgart@@dismail.de>
1463 + Ludovic Courtès <ludo@@gnu.org>
1467 You can run the following command to have the @code{Mentors} team put in
1468 CC of a patch series:
1471 $ git send-email --to XXX@@debbugs.gnu.org $(./etc/teams.scm cc mentors) *.patch
1474 The appropriate team or teams can also be inferred from the modified
1475 files. For instance, if you want to send the two latest commits of the
1476 current Git repository to review, you can run:
1479 $ guix shell -D guix
1480 [env]$ git send-email --to XXX@@debbugs.gnu.org $(./etc/teams.scm cc-members HEAD~2 HEAD) *.patch
1483 @node Tracking Bugs and Patches
1484 @section Tracking Bugs and Patches
1486 This section describes how the Guix project tracks its bug reports and
1490 * The Issue Tracker:: The official bug and patch tracker.
1491 * Debbugs User Interfaces:: Ways to interact with Debbugs.
1492 * Debbugs Usertags:: Tag reports with custom labels.
1495 @node The Issue Tracker
1496 @subsection The Issue Tracker
1498 @cindex bug reports, tracking
1499 @cindex patch submissions, tracking
1500 @cindex issue tracking
1501 @cindex Debbugs, issue tracking system
1502 Bug reports and patch submissions are currently tracked using the
1503 Debbugs instance at @uref{https://bugs.gnu.org}. Bug reports are filed
1504 against the @code{guix} ``package'' (in Debbugs parlance), by sending
1505 email to @email{bug-guix@@gnu.org}, while patch submissions are filed
1506 against the @code{guix-patches} package by sending email to
1507 @email{guix-patches@@gnu.org} (@pxref{Submitting Patches}).
1509 @node Debbugs User Interfaces
1510 @subsection Debbugs User Interfaces
1512 A web interface (actually @emph{two} web interfaces!) are available to
1517 @url{https://issues.guix.gnu.org} provides a pleasant
1518 interface@footnote{The web interface at
1519 @url{https://issues.guix.gnu.org} is powered by Mumi, a nice piece of
1520 software written in Guile, and you can help! See
1521 @url{https://git.elephly.net/gitweb.cgi?p=software/mumi.git}.} to browse
1522 bug reports and patches, and to participate in discussions;
1524 @url{https://bugs.gnu.org/guix} lists bug reports;
1526 @url{https://bugs.gnu.org/guix-patches} lists patch submissions.
1529 To view discussions related to issue number @var{n}, go to
1530 @indicateurl{https://issues.guix.gnu.org/@var{n}} or
1531 @indicateurl{https://bugs.gnu.org/@var{n}}.
1533 If you use Emacs, you may find it more convenient to interact with
1534 issues using @file{debbugs.el}, which you can install with:
1537 guix install emacs-debbugs
1540 For example, to list all open issues on @code{guix-patches}, hit:
1543 @kbd{C-u} @kbd{M-x} debbugs-gnu @kbd{RET} @kbd{RET} guix-patches @kbd{RET} n y
1546 @xref{Top,,, debbugs-ug, Debbugs User Guide}, for more information on
1549 @node Debbugs Usertags
1550 @subsection Debbugs Usertags
1552 @cindex usertags, for debbugs
1553 @cindex Debbugs usertags
1554 Debbugs provides a feature called @dfn{usertags} that allows any user to
1555 tag any bug with an arbitrary label. Bugs can be searched by usertag,
1556 so this is a handy way to organize bugs@footnote{The list of usertags is
1557 public information, and anyone can modify any user's list of usertags,
1558 so keep that in mind if you choose to use this feature.}.
1560 For example, to view all the bug reports (or patches, in the case of
1561 @code{guix-patches}) tagged with the usertag @code{powerpc64le-linux}
1562 for the user @code{guix}, open a URL like the following in a web
1564 @url{https://debbugs.gnu.org/cgi-bin/pkgreport.cgi?tag=powerpc64le-linux;users=guix}.
1566 For more information on how to use usertags, please refer to the
1567 documentation for Debbugs or the documentation for whatever tool you use
1568 to interact with Debbugs.
1570 In Guix, we are experimenting with usertags to keep track of
1571 architecture-specific issues. To facilitate collaboration, all our
1572 usertags are associated with the single user @code{guix}. The following
1573 usertags currently exist for that user:
1577 @item powerpc64le-linux
1578 The purpose of this usertag is to make it easy to find the issues that
1579 matter most for the @code{powerpc64le-linux} system type. Please assign
1580 this usertag to bugs or patches that affect @code{powerpc64le-linux} but
1581 not other system types. In addition, you may use it to identify issues
1582 that for some reason are particularly important for the
1583 @code{powerpc64le-linux} system type, even if the issue affects other
1586 @item reproducibility
1587 For issues related to reproducibility. For example, it would be
1588 appropriate to assign this usertag to a bug report for a package that
1589 fails to build reproducibly.
1593 If you're a committer and you want to add a usertag, just start using it
1594 with the @code{guix} user. If the usertag proves useful to you,
1595 consider updating this section of the manual so that others will know
1596 what your usertag means.
1599 @section Commit Access
1601 @cindex commit access, for developers
1602 Everyone can contribute to Guix without having commit access
1603 (@pxref{Submitting Patches}). However, for frequent contributors,
1604 having write access to the repository can be convenient. As a rule of
1605 thumb, a contributor should have accumulated fifty (50) reviewed commits
1606 to be considered as a committer and have sustained their activity in the
1607 project for at least 6 months. This ensures enough interactions with
1608 the contributor, which is essential for mentoring and assessing whether
1609 they are ready to become a committer. Commit access should not be
1610 thought of as a ``badge of honor'' but rather as a responsibility a
1611 contributor is willing to take to help the project.
1613 The following sections explain how to get commit access, how to be ready
1614 to push commits, and the policies and community expectations for commits
1617 @subsection Applying for Commit Access
1619 When you deem it necessary, consider applying for commit
1620 access by following these steps:
1624 Find three committers who would vouch for you. You can view the list of
1626 @url{https://savannah.gnu.org/project/memberlist.php?group=guix}. Each
1627 of them should email a statement to @email{guix-maintainers@@gnu.org} (a
1628 private alias for the collective of maintainers), signed with their
1631 Committers are expected to have had some interactions with you as a
1632 contributor and to be able to judge whether you are sufficiently
1633 familiar with the project's practices. It is @emph{not} a judgment on
1634 the value of your work, so a refusal should rather be interpreted as
1635 ``let's try again later''.
1638 Send @email{guix-maintainers@@gnu.org} a message stating your intent,
1639 listing the three committers who support your application, signed with
1640 the OpenPGP key you will use to sign commits, and giving its fingerprint
1641 (see below). See @uref{https://emailselfdefense.fsf.org/en/}, for an
1642 introduction to public-key cryptography with GnuPG.
1644 @c See <https://sha-mbles.github.io/>.
1645 Set up GnuPG such that it never uses the SHA1 hash algorithm for digital
1646 signatures, which is known to be unsafe since 2019, for instance by
1647 adding the following line to @file{~/.gnupg/gpg.conf} (@pxref{GPG
1648 Esoteric Options,,, gnupg, The GNU Privacy Guard Manual}):
1655 Maintainers ultimately decide whether to grant you commit access,
1656 usually following your referrals' recommendation.
1659 @cindex OpenPGP, signed commits
1660 If and once you've been given access, please send a message to
1661 @email{guix-devel@@gnu.org} to say so, again signed with the OpenPGP key
1662 you will use to sign commits (do that before pushing your first commit).
1663 That way, everyone can notice and ensure you control that OpenPGP key.
1665 @quotation Important
1666 Before you can push for the first time, maintainers must:
1670 add your OpenPGP key to the @code{keyring} branch;
1672 add your OpenPGP fingerprint to the @file{.guix-authorizations} file of
1673 the branch(es) you will commit to.
1678 Make sure to read the rest of this section and... profit!
1682 Maintainers are happy to give commit access to people who have been
1683 contributing for some time and have a track record---don't be shy and
1684 don't underestimate your work!
1686 However, note that the project is working towards a more automated patch
1687 review and merging system, which, as a consequence, may lead us to have
1688 fewer people with commit access to the main repository. Stay tuned!
1691 All commits that are pushed to the central repository on Savannah must
1692 be signed with an OpenPGP key, and the public key should be uploaded to
1693 your user account on Savannah and to public key servers, such as
1694 @code{keys.openpgp.org}. To configure Git to automatically sign
1698 git config commit.gpgsign true
1700 # Substitute the fingerprint of your public PGP key.
1701 git config user.signingkey CABBA6EA1DC0FF33
1704 To check that commits are signed with correct key, use:
1710 You can prevent yourself from accidentally pushing unsigned or signed
1711 with the wrong key commits to Savannah by using the pre-push Git hook
1712 located at @file{etc/git/pre-push}:
1715 cp etc/git/pre-push .git/hooks/pre-push
1718 It additionally calls @code{make check-channel-news} to be sure
1719 @file{news.scm} file is correct.
1721 @subsection Commit Policy
1723 If you get commit access, please make sure to follow
1724 the policy below (discussions of the policy can take place on
1725 @email{guix-devel@@gnu.org}).
1727 Non-trivial patches should always be posted to
1728 @email{guix-patches@@gnu.org} (trivial patches include fixing typos,
1729 etc.). This mailing list fills the patch-tracking database
1730 (@pxref{Tracking Bugs and Patches}).
1732 For patches that just add a new package, and a simple one, it's OK to
1733 commit, if you're confident (which means you successfully built it in a
1734 chroot setup, and have done a reasonable copyright and license
1735 auditing). Likewise for package upgrades, except upgrades that trigger
1736 a lot of rebuilds (for example, upgrading GnuTLS or GLib). We have a
1737 mailing list for commit notifications (@email{guix-commits@@gnu.org}),
1738 so people can notice. Before pushing your changes, make sure to run
1739 @code{git pull --rebase}.
1741 When pushing a commit on behalf of somebody else, please add a
1742 @code{Signed-off-by} line at the end of the commit log message---e.g.,
1743 with @command{git am --signoff}. This improves tracking of who did
1746 When adding channel news entries (@pxref{Channels, Writing Channel
1747 News}), make sure they are well-formed by running the following command
1748 right before pushing:
1751 make check-channel-news
1754 For anything else, please post to @email{guix-patches@@gnu.org} and
1755 leave time for a review, without committing anything (@pxref{Submitting
1756 Patches}). If you didn’t receive any reply after two weeks, and if
1757 you're confident, it's OK to commit.
1759 That last part is subject to being adjusted, allowing individuals to commit
1760 directly on non-controversial changes on parts they’re familiar with.
1762 @subsection Addressing Issues
1764 Peer review (@pxref{Submitting Patches}) and tools such as
1765 @command{guix lint} (@pxref{Invoking guix lint}) and the test suite
1766 (@pxref{Running the Test Suite}) should catch issues before they are
1767 pushed. Yet, commits that ``break'' functionality might occasionally
1768 go through. When that happens, there are two priorities: mitigating
1769 the impact, and understanding what happened to reduce the chance of
1770 similar incidents in the future. The responsibility for both these
1771 things primarily lies with those involved, but like everything this is
1774 Some issues can directly affect all users---for instance because they
1775 make @command{guix pull} fail or break core functionality, because they
1776 break major packages (at build time or run time), or because they
1777 introduce known security vulnerabilities.
1779 @cindex reverting commits
1780 The people involved in authoring, reviewing, and pushing such
1781 commit(s) should be at the forefront to mitigate their impact in a
1782 timely fashion: by pushing a followup commit to fix it (if possible),
1783 or by reverting it to leave time to come up with a proper fix, and by
1784 communicating with other developers about the problem.
1786 If these persons are unavailable to address the issue in time, other
1787 committers are entitled to revert the commit(s), explaining in the
1788 commit log and on the mailing list what the problem was, with the goal
1789 of leaving time to the original committer, reviewer(s), and author(s)
1790 to propose a way forward.
1792 Once the problem has been dealt with, it is the responsibility of
1793 those involved to make sure the situation is understood. If you are
1794 working to understand what happened, focus on gathering information
1795 and avoid assigning any blame. Do ask those involved to describe what
1796 happened, do not ask them to explain the situation---this would
1797 implicitly blame them, which is unhelpful. Accountability comes from
1798 a consensus about the problem, learning from it and improving
1799 processes so that it's less likely to reoccur.
1801 @subsection Commit Revocation
1803 In order to reduce the possibility of mistakes, committers will have
1804 their Savannah account removed from the Guix Savannah project and their
1805 key removed from @file{.guix-authorizations} after 12 months of
1806 inactivity; they can ask to regain commit access by emailing the
1807 maintainers, without going through the vouching process.
1809 Maintainers@footnote{See @uref{https://guix.gnu.org/en/about} for the
1810 current list of maintainers. You can email them privately at
1811 @email{guix-maintainers@@gnu.org}.} may also revoke an individual's
1812 commit rights, as a last resort, if cooperation with the rest of the
1813 community has caused too much friction---even within the bounds of the
1814 project's code of conduct (@pxref{Contributing}). They would only do so
1815 after public or private discussion with the individual and a clear
1816 notice. Examples of behavior that hinders cooperation and could lead to
1817 such a decision include:
1820 @item repeated violation of the commit policy stated above;
1821 @item repeated failure to take peer criticism into account;
1822 @item breaching trust through a series of grave incidents.
1825 When maintainers resort to such a decision, they notify developers on
1826 @email{guix-devel@@gnu.org}; inquiries may be sent to
1827 @email{guix-maintainers@@gnu.org}. Depending on the situation, the
1828 individual may still be welcome to contribute.
1830 @subsection Helping Out
1832 One last thing: the project keeps moving forward because committers not
1833 only push their own awesome changes, but also offer some of their time
1834 @emph{reviewing} and pushing other people's changes. As a committer,
1835 you're welcome to use your expertise and commit rights to help other
1838 @node Updating the Guix Package
1839 @section Updating the Guix Package
1841 @cindex update-guix-package, updating the guix package
1842 It is sometimes desirable to update the @code{guix} package itself (the
1843 package defined in @code{(gnu packages package-management)}), for
1844 example to make new daemon features available for use by the
1845 @code{guix-service-type} service type. In order to simplify this task,
1846 the following command can be used:
1849 make update-guix-package
1852 The @code{update-guix-package} make target will use the last known
1853 @emph{commit} corresponding to @code{HEAD} in your Guix checkout,
1854 compute the hash of the Guix sources corresponding to that commit and
1855 update the @code{commit}, @code{revision} and hash of the @code{guix}
1858 To validate that the updated @code{guix} package hashes are correct and
1859 that it can be built successfully, the following command can be run from
1860 the directory of your Guix checkout:
1863 ./pre-inst-env guix build guix
1866 To guard against accidentally updating the @code{guix} package to a
1867 commit that others can't refer to, a check is made that the commit used
1868 has already been pushed to the Savannah-hosted Guix git repository.
1870 This check can be disabled, @emph{at your own peril}, by setting the
1871 @code{GUIX_ALLOW_ME_TO_USE_PRIVATE_COMMIT} environment variable. When
1872 this variable is set, the updated package source is also added to the
1873 store. This is used as part of the release process of Guix.
1875 @cindex documentation
1876 @node Writing Documentation
1877 @section Writing Documentation
1879 Guix is documented using the Texinfo system. If you are not yet
1880 familiar with it, we accept contributions for documentation in most
1881 formats. That includes plain text, Markdown, Org, etc.
1883 Documentation contributions can be sent to
1884 @email{guix-patches@@gnu.org}. Prepend @samp{[DOCUMENTATION]} to the
1887 When you need to make more than a simple addition to the documentation,
1888 we prefer that you send a proper patch as opposed to sending an email
1889 as described above. @xref{Submitting Patches} for more information on
1890 how to send your patches.
1892 To modify the documentation, you need to edit @file{doc/guix.texi} and
1893 @file{doc/contributing.texi} (which contains this documentation
1894 section), or @file{doc/guix-cookbook.texi} for the cookbook. If
1895 you compiled the Guix repository before, you will have
1896 many more @file{.texi} files that are translations of these
1897 documents. Do not modify them, the translation is managed through
1898 @uref{https://translate.fedoraproject.org/projects/guix, Weblate}.
1899 @xref{Translating Guix} for more information.
1901 To render documentation, you must first make sure that you ran
1902 @command{./configure} in your source tree (@pxref{Running Guix Before
1903 It Is Installed}). After that you can run one of the following
1907 @item @samp{make doc/guix.info} to compile the Info manual.
1908 You can check it with @command{info doc/guix.info}.
1909 @item @samp{make doc/guix.html} to compile the HTML version.
1910 You can point your browser to the relevant file in the
1911 @file{doc/guix.html} directory.
1912 @item @samp{make doc/guix-cookbook.info} for the cookbook Info manual.
1913 @item @samp{make doc/guix-cookbook.html} for the cookbook HTML version.
1919 @cindex native language support
1920 @node Translating Guix
1921 @section Translating Guix
1923 Writing code and packages is not the only way to provide a meaningful
1924 contribution to Guix. Translating to a language you speak is another
1925 example of a valuable contribution you can make. This section is designed
1926 to describe the translation process. It gives you advice on how you can
1927 get involved, what can be translated, what mistakes you should avoid and
1928 what we can do to help you!
1930 Guix is a big project that has multiple components that can be translated.
1931 We coordinate the translation effort on a
1932 @uref{https://translate.fedoraproject.org/projects/guix/,Weblate instance}
1933 hosted by our friends at Fedora. You will need an account to submit
1936 Some of the software packaged in Guix also contain translations. We do not
1937 host a translation platform for them. If you want to translate a package
1938 provided by Guix, you should contact their developers or find the information
1939 on their website. As an example, you can find the homepage of the
1940 @code{hello} package by typing @code{guix show hello}. On the ``homepage''
1941 line, you will see @url{https://www.gnu.org/software/hello/} as the homepage.
1943 Many GNU and non-GNU packages can be translated on the
1944 @uref{https://translationproject.org,Translation Project}. Some projects
1945 with multiple components have their own platform. For instance, GNOME has
1946 its own platform, @uref{https://l10n.gnome.org/,Damned Lies}.
1948 Guix has five components hosted on Weblate.
1951 @item @code{guix} contains all the strings from the Guix software (the
1952 guided system installer, the package manager, etc), excluding packages.
1953 @item @code{packages} contains the synopsis (single-sentence description
1954 of a package) and description (longer description) of packages in Guix.
1955 @item @code{website} contains the official Guix website, except for
1956 blog posts and multimedia content.
1957 @item @code{documentation-manual} corresponds to this manual.
1958 @item @code{documentation-cookbook} is the component for the cookbook.
1961 @subsubheading General Directions
1963 Once you get an account, you should be able to select a component from
1964 @uref{https://translate.fedoraproject.org/projects/guix/,the guix project},
1965 and select a language. If your language does not appear in the list, go
1966 to the bottom and click on the ``Start new translation'' button. Select
1967 the language you want to translate to from the list, to start your new
1970 Like lots of other free software packages, Guix uses
1971 @uref{https://www.gnu.org/software/gettext,GNU Gettext} for its translations,
1972 with which translatable strings are extracted from the source code to so-called
1975 Even though PO files are text files, changes should not be made with a text
1976 editor but with PO editing software. Weblate integrates PO editing
1977 functionality. Alternatively, translators can use any of various
1978 free-software tools for filling in translations, of which
1979 @uref{https://poedit.net/,Poedit} is one example, and (after logging in)
1980 @uref{https://docs.weblate.org/en/latest/user/files.html,upload} the changed
1981 file. There is also a special
1982 @uref{https://www.emacswiki.org/emacs/PoMode,PO editing mode} for users of GNU
1983 Emacs. Over time translators find out what software they are happy with and
1984 what features they need.
1986 On Weblate, you will find various links to the editor, that will show various
1987 subsets (or all) of the strings. Have a look around and at the
1988 @uref{https://docs.weblate.org/en/latest/,documentation} to familiarize
1989 yourself with the platform.
1991 @subsubheading Translation Components
1993 In this section, we provide more detailed guidance on the translation
1994 process, as well as details on what you should or should not do. When in
1995 doubt, please contact us, we will be happy to help!
1999 Guix is written in the Guile programming language, and some strings contain
2000 special formatting that is interpreted by Guile. These special formatting
2001 should be highlighted by Weblate. They start with @code{~} followed by one
2004 When printing the string, Guile replaces the special formatting symbols with
2005 actual values. For instance, the string @samp{ambiguous package specification
2006 `~a'} would be substituted to contain said package specification instead of
2007 @code{~a}. To properly translate this string, you must keep the formatting
2008 code in your translation, although you can place it where it makes sense in
2009 your language. For instance, the French translation says @samp{spécification
2010 du paquet « ~a » ambiguë} because the adjective needs to be placed in the
2011 end of the sentence.
2013 If there are multiple formatting symbols, make sure to respect the order.
2014 Guile does not know in which order you intended the string to be read, so it
2015 will substitute the symbols in the same order as the English sentence.
2017 As an example, you cannot translate @samp{package '~a' has been superseded by
2018 '~a'} by @samp{'~a' superseeds package '~a'}, because the meaning would be
2019 reversed. If @var{foo} is superseded by @var{bar}, the translation would read
2020 @samp{'foo' superseeds package 'bar'}. To work around this problem, it
2021 is possible to use more advanced formatting to select a given piece of data,
2022 instead of following the default English order. @xref{Formatted Output,,,
2023 guile, GNU Guile Reference Manual}, for more information on formatting in Guile.
2027 Package descriptions occasionally contain Texinfo markup (@pxref{Synopses
2028 and Descriptions}). Texinfo markup looks like @samp{@@code@{rm -rf@}},
2029 @samp{@@emph@{important@}}, etc. When translating, please leave markup as is.
2031 The characters after ``@@'' form the name of the markup, and the text between
2032 ``@{'' and ``@}'' is its content. In general, you should not translate the
2033 content of markup like @code{@@code}, as it contains literal code that do not
2034 change with language. You can translate the content of formatting markup such
2035 as @code{@@emph}, @code{@@i}, @code{@@itemize}, @code{@@item}. However, do
2036 not translate the name of the markup, or it will not be recognized. Do
2037 not translate the word after @code{@@end}, it is the name of the markup that
2038 is closed at this position (e.g.@: @code{@@itemize ... @@end itemize}).
2040 @item documentation-manual and documentation-cookbook
2042 The first step to ensure a successful translation of the manual is to find
2043 and translate the following strings @emph{first}:
2046 @item @code{version.texi}: Translate this string as @code{version-xx.texi},
2047 where @code{xx} is your language code (the one shown in the URL on
2049 @item @code{contributing.texi}: Translate this string as
2050 @code{contributing.xx.texi}, where @code{xx} is the same language code.
2051 @item @code{Top}: Do not translate this string, it is important for Texinfo.
2052 If you translate it, the document will be empty (missing a Top node).
2053 Please look for it, and register @code{Top} as its translation.
2056 Translating these strings first ensure we can include your translation in
2057 the guix repository without breaking the make process or the
2058 @command{guix pull} machinery.
2060 The manual and the cookbook both use Texinfo. As for @code{packages}, please
2061 keep Texinfo markup as is. There are more possible markup types in the manual
2062 than in the package descriptions. In general, do not translate the content
2063 of @code{@@code}, @code{@@file}, @code{@@var}, @code{@@value}, etc. You
2064 should translate the content of formatting markup such as @code{@@emph},
2067 The manual contains sections that can be referred to by name by @code{@@ref},
2068 @code{@@xref} and @code{@@pxref}. We have a mechanism in place so you do
2069 not have to translate their content. If you keep the English title, we will
2070 automatically replace it with your translation of that title. This ensures
2071 that Texinfo will always be able to find the node. If you decide to change
2072 the translation of the title, the references will automatically be updated
2073 and you will not have to update them all yourself.
2075 When translating references from the cookbook to the manual, you need to
2076 replace the name of the manual and the name of the section. For instance,
2077 to translate @code{@@pxref@{Defining Packages,,, guix, GNU Guix Reference
2078 Manual@}}, you would replace @code{Defining Packages} with the title of that
2079 section in the translated manual @emph{only} if that title is translated.
2080 If the title is not translated in your language yet, do not translate it here,
2081 or the link will be broken. Replace @code{guix} with @code{guix.xx} where
2082 @code{xx} is your language code. @code{GNU Guix Reference Manual} is the
2083 text of the link. You can translate it however you wish.
2087 The website pages are written using SXML, an s-expression version of HTML,
2088 the basic language of the web. We have a process to extract translatable
2089 strings from the source, and replace complex s-expressions with a more familiar
2090 XML markup, where each markup is numbered. Translators can arbitrarily change
2091 the ordering, as in the following example.
2094 #. TRANSLATORS: Defining Packages is a section name
2095 #. in the English (en) manual.
2096 #: apps/base/templates/about.scm:64
2097 msgid "Packages are <1>defined<1.1>en</1.1><1.2>Defining-Packages.html</1.2></1> as native <2>Guile</2> modules."
2098 msgstr "Pakete werden als reine <2>Guile</2>-Module <1>definiert<1.1>de</1.1><1.2>Pakete-definieren.html</1.2></1>."
2101 Note that you need to include the same markups. You cannot skip any.
2104 In case you make a mistake, the component might fail to build properly with your
2105 language, or even make guix pull fail. To prevent that, we have a process
2106 in place to check the content of the files before pushing to our repository.
2107 We will not be able to update the translation for your language in Guix, so
2108 we will notify you (through weblate and/or by email) so you get a chance to
2111 @subsubheading Outside of Weblate
2113 Currently, some parts of Guix cannot be translated on Weblate, help wanted!
2116 @item @command{guix pull} news can be translated in @file{news.scm}, but is not
2117 available from Weblate. If you want to provide a translation, you
2118 can prepare a patch as described above, or simply send us your
2119 translation with the name of the news entry you translated and your
2120 language. @xref{Writing Channel News}, for more information about
2122 @item Guix blog posts cannot currently be translated.
2123 @item The installer script (for foreign distributions) is entirely in English.
2124 @item Some of the libraries Guix uses cannot be translated or are translated
2125 outside of the Guix project. Guile itself is not internationalized.
2126 @item Other manuals linked from this manual or the cookbook might not be
2130 @subsubheading Conditions for Inclusion
2132 There are no conditions for adding new translations of the @code{guix} and
2133 @code{guix-packages} components, other than they need at least one translated
2134 string. New languages will be added to Guix as soon as possible. The
2135 files may be removed if they fall out of sync and have no more translated
2138 Given that the web site is dedicated to new users, we want its translation
2139 to be as complete as possible before we include it in the language menu.
2140 For a new language to be included, it needs to reach at least 80% completion.
2141 When a language is included, it may be removed in the future if it stays
2142 out of sync and falls below 60% completion.
2144 The manual and cookbook are automatically added in the default compilation
2145 target. Every time we synchronize translations, developers need to
2146 recompile all the translated manuals and cookbooks. This is useless for what
2147 is essentially the English manual or cookbook. Therefore, we will only
2148 include a new language when it reaches 10% completion in the component.
2149 When a language is included, it may be removed in the future if it stays
2150 out of sync and falls below 5% completion.
2152 @subsubheading Translation Infrastructure
2154 Weblate is backed by a git repository from which it discovers new strings to
2155 translate and pushes new and updated translations. Normally, it would be
2156 enough to give it commit access to our repositories. However, we decided
2157 to use a separate repository for two reasons. First, we would have to give
2158 Weblate commit access and authorize its signing key, but we do not trust it
2159 in the same way we trust guix developers, especially since we do not manage
2160 the instance ourselves. Second, if translators mess something up, it can
2161 break the generation of the website and/or guix pull for all our users,
2162 independently of their language.
2164 For these reasons, we use a dedicated repository to host translations, and we
2165 synchronize it with our guix and artworks repositories after checking no issue
2166 was introduced in the translation.
2168 Developers can download the latest PO files from weblate in the Guix
2169 repository by running the @command{make download-po} command. It will
2170 automatically download the latest files from weblate, reformat them to a
2171 canonical form, and check they do not contain issues. The manual needs to be
2172 built again to check for additional issues that might crash Texinfo.
2174 Before pushing new translation files, developers should add them to the
2175 make machinery so the translations are actually available. The process
2176 differs for the various components.
2179 @item New po files for the @code{guix} and @code{packages} components must
2180 be registered by adding the new language to @file{po/guix/LINGUAS} or
2181 @file{po/packages/LINGUAS}.
2182 @item New po files for the @code{documentation-manual} component must be
2183 registered by adding the file name to @code{DOC_PO_FILES} in
2184 @file{po/doc/local.mk}, the generated @file{%D%/guix.xx.texi} manual to
2185 @code{info_TEXINFOS} in @file{doc/local.mk} and the generated
2186 @file{%D%/guix.xx.texi} and @file{%D%/contributing.xx.texi} to
2187 @code{TRANSLATED_INFO} also in @file{doc/local.mk}.
2188 @item New po files for the @code{documentation-cookbook} component must be
2189 registered by adding the file name to @code{DOC_COOKBOOK_PO_FILES} in
2190 @file{po/doc/local.mk}, the generated @file{%D%/guix-cookbook.xx.texi}
2191 manual to @code{info_TEXINFOS} in @file{doc/local.mk} and the generated
2192 @file{%D%/guix-cookbook.xx.texi} to @code{TRANSLATED_INFO} also
2193 in @file{doc/local.mk}.
2194 @item New po files for the @code{website} component must be added to the
2195 @code{guix-artwork} repository, in @file{website/po/}.
2196 @file{website/po/LINGUAS} and @file{website/po/ietf-tags.scm} must
2197 be updated accordingly (see @file{website/i18n-howto.txt} for more
2198 information on the process).