7b710836a1
* doc/contributing.texi (Data Types and Pattern Matching): Add paragraph about keeping RTDs private. Suggested-by: Maxim Cournoyer <maxim.cournoyer@gmail.com>
2601 lines
106 KiB
Text
2601 lines
106 KiB
Text
@node Contributing
|
||
@chapter Contributing
|
||
|
||
This project is a cooperative effort, and we need your help to make it
|
||
grow! Please get in touch with us on @email{guix-devel@@gnu.org} and
|
||
@code{#guix} on the Libera Chat IRC network. We welcome ideas, bug
|
||
reports, patches, and anything that may be helpful to the project. We
|
||
particularly welcome help on packaging (@pxref{Packaging Guidelines}).
|
||
|
||
@cindex code of conduct, of contributors
|
||
@cindex contributor covenant
|
||
We want to provide a warm, friendly, and harassment-free environment, so
|
||
that anyone can contribute to the best of their abilities. To this end
|
||
our project uses a ``Contributor Covenant'', which was adapted from
|
||
@url{https://contributor-covenant.org/}. You can find a local version in
|
||
the @file{CODE-OF-CONDUCT} file in the source tree.
|
||
|
||
Contributors are not required to use their legal name in patches and
|
||
on-line communication; they can use any name or pseudonym of their
|
||
choice.
|
||
|
||
@menu
|
||
* Building from Git:: The latest and greatest.
|
||
* Running Guix Before It Is Installed:: Hacker tricks.
|
||
* The Perfect Setup:: The right tools.
|
||
* Alternative Setups:: Other posible tools that do the job.
|
||
* Packaging Guidelines:: Growing the distribution.
|
||
* Coding Style:: Hygiene of the contributor.
|
||
* Submitting Patches:: Share your work.
|
||
* Tracking Bugs and Changes:: Keeping it all organized.
|
||
* Commit Access:: Pushing to the official repository.
|
||
* Updating the Guix Package:: Updating the Guix package definition.
|
||
* Writing Documentation:: Improving documentation in GNU Guix.
|
||
* Translating Guix:: Make Guix speak your native language.
|
||
@end menu
|
||
|
||
@node Building from Git
|
||
@section Building from Git
|
||
|
||
If you want to hack Guix itself, it is recommended to use the latest
|
||
version from the Git repository:
|
||
|
||
@example
|
||
git clone https://git.savannah.gnu.org/git/guix.git
|
||
@end example
|
||
|
||
@cindex authentication, of a Guix checkout
|
||
How do you ensure that you obtained a genuine copy of the repository?
|
||
To do that, run @command{guix git authenticate}, passing it the commit
|
||
and OpenPGP fingerprint of the @dfn{channel introduction}
|
||
(@pxref{Invoking guix git authenticate}):
|
||
|
||
@c The commit and fingerprint below must match those of the channel
|
||
@c introduction in '%default-channels'.
|
||
@example
|
||
git fetch origin keyring:keyring
|
||
guix git authenticate 9edb3f66fd807b096b48283debdcddccfea34bad \
|
||
"BBB0 2DDF 2CEA F6A8 0D1D E643 A2A0 6DF2 A33A 54FA"
|
||
@end example
|
||
|
||
@noindent
|
||
This command completes with exit code zero on success; it prints an
|
||
error message and exits with a non-zero code otherwise.
|
||
|
||
As you can see, there is a chicken-and-egg problem: you first need to
|
||
have Guix installed. Typically you would install Guix System
|
||
(@pxref{System Installation}) or Guix on top of another distro
|
||
(@pxref{Binary Installation}); in either case, you would verify the
|
||
OpenPGP signature on the installation medium. This ``bootstraps'' the
|
||
trust chain.
|
||
|
||
The easiest way to set up a development environment for Guix is, of
|
||
course, by using Guix! The following command starts a new shell where
|
||
all the dependencies and appropriate environment variables are set up to
|
||
hack on Guix:
|
||
|
||
@example
|
||
guix shell -D guix --pure
|
||
@end example
|
||
|
||
or even, from within a Git worktree for Guix:
|
||
|
||
@example
|
||
guix shell --pure
|
||
@end example
|
||
|
||
@xref{Invoking guix shell}, for more information on that command.
|
||
|
||
If you are unable to use Guix when building Guix from a checkout, the
|
||
following are the required packages in addition to those mentioned in the
|
||
installation instructions (@pxref{Requirements}).
|
||
|
||
@itemize
|
||
@item @url{https://gnu.org/software/autoconf/, GNU Autoconf};
|
||
@item @url{https://gnu.org/software/automake/, GNU Automake};
|
||
@item @url{https://gnu.org/software/gettext/, GNU Gettext};
|
||
@item @url{https://gnu.org/software/texinfo/, GNU Texinfo};
|
||
@item @url{https://www.graphviz.org/, Graphviz};
|
||
@item @url{https://www.gnu.org/software/help2man/, GNU Help2man (optional)}.
|
||
@end itemize
|
||
|
||
On Guix, extra dependencies can be added by instead running @command{guix
|
||
shell}:
|
||
|
||
@example
|
||
guix shell -D guix help2man git strace --pure
|
||
@end example
|
||
|
||
From there you can generate the build system infrastructure
|
||
using Autoconf and Automake:
|
||
|
||
@example
|
||
./bootstrap
|
||
@end example
|
||
|
||
If you get an error like this one:
|
||
|
||
@example
|
||
configure.ac:46: error: possibly undefined macro: PKG_CHECK_MODULES
|
||
@end example
|
||
|
||
@noindent
|
||
it probably means that Autoconf couldn’t find @file{pkg.m4}, which is
|
||
provided by pkg-config. Make sure that @file{pkg.m4} is available. The
|
||
same holds for the @file{guile.m4} set of macros provided by Guile. For
|
||
instance, if you installed Automake in @file{/usr/local}, it wouldn’t
|
||
look for @file{.m4} files in @file{/usr/share}. In that case, you have
|
||
to invoke the following command:
|
||
|
||
@example
|
||
export ACLOCAL_PATH=/usr/share/aclocal
|
||
@end example
|
||
|
||
@xref{Macro Search Path,,, automake, The GNU Automake Manual}, for
|
||
more information.
|
||
|
||
Then, run:
|
||
|
||
@example
|
||
./configure --localstatedir=/var --sysconfdir=/etc
|
||
@end example
|
||
|
||
@noindent
|
||
... where @file{/var} is the normal @code{localstatedir} value
|
||
(@pxref{The Store}, for information about this) and @file{/etc} is the
|
||
normal @code{sysconfdir} value. Note that you will probably not run
|
||
@command{make install} at the end (you don't have to) but it's still
|
||
important to pass the right @code{localstatedir} and @code{sysconfdir}
|
||
values, which get recorded in the @code{(guix config)} Guile module.
|
||
|
||
Finally, you can build Guix and, if you feel so inclined, run the tests
|
||
(@pxref{Running the Test Suite}):
|
||
|
||
@example
|
||
make
|
||
make check
|
||
@end example
|
||
|
||
@noindent
|
||
If anything fails, take a look at installation instructions
|
||
(@pxref{Installation}) or send a message to the
|
||
@email{guix-devel@@gnu.org, mailing list}.
|
||
|
||
From there on, you can authenticate all the commits included in your
|
||
checkout by running:
|
||
|
||
@example
|
||
make authenticate
|
||
@end example
|
||
|
||
The first run takes a couple of minutes, but subsequent runs are faster.
|
||
|
||
Or, when your configuration for your local Git repository doesn't match
|
||
the default one, you can provide the reference for the @code{keyring}
|
||
branch through the variable @code{GUIX_GIT_KEYRING}. The following
|
||
example assumes that you have a Git remote called @samp{myremote}
|
||
pointing to the official repository:
|
||
|
||
@example
|
||
make authenticate GUIX_GIT_KEYRING=myremote/keyring
|
||
@end example
|
||
|
||
@quotation Note
|
||
You are advised to run @command{make authenticate} after every
|
||
@command{git pull} invocation. This ensures you keep receiving valid
|
||
changes to the repository.
|
||
@end quotation
|
||
|
||
After updating the repository, @command{make} might fail with an error
|
||
similar to the following example:
|
||
|
||
@example
|
||
error: failed to load 'gnu/packages/dunst.scm':
|
||
ice-9/eval.scm:293:34: In procedure abi-check: #<record-type <origin>>: record ABI mismatch; recompilation needed
|
||
@end example
|
||
|
||
This means that one of the record types that Guix defines (in this
|
||
example, the @code{origin} record) has changed, and all of guix needs
|
||
to be recompiled to take that change into account. To do so, run
|
||
@command{make clean-go} followed by @command{make}.
|
||
|
||
@node Running Guix Before It Is Installed
|
||
@section Running Guix Before It Is Installed
|
||
|
||
In order to keep a sane working environment, you will find it useful to
|
||
test the changes made in your local source tree checkout without
|
||
actually installing them. So that you can distinguish between your
|
||
``end-user'' hat and your ``motley'' costume.
|
||
|
||
To that end, all the command-line tools can be used even if you have not
|
||
run @code{make install}. To do that, you first need to have an
|
||
environment with all the dependencies available (@pxref{Building from
|
||
Git}), and then simply prefix each command with @command{./pre-inst-env}
|
||
(the @file{pre-inst-env} script lives in the top build tree of Guix;
|
||
@pxref{Building from Git} to generate it). As an example, here is how you
|
||
would build the @code{hello} package as defined in your working tree (this
|
||
assumes @command{guix-daemon} is already running on your system; it's OK if
|
||
it's a different version):
|
||
|
||
@example
|
||
$ ./pre-inst-env guix build hello
|
||
@end example
|
||
|
||
@noindent
|
||
Similarly, an example for a Guile session using the Guix modules:
|
||
|
||
@example
|
||
$ ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))'
|
||
|
||
;;; ("x86_64-linux")
|
||
@end example
|
||
|
||
@noindent
|
||
@cindex REPL
|
||
@cindex read-eval-print loop
|
||
@dots{} and for a REPL (@pxref{Using Guix Interactively}):
|
||
|
||
@example
|
||
$ ./pre-inst-env guile
|
||
scheme@@(guile-user)> ,use(guix)
|
||
scheme@@(guile-user)> ,use(gnu)
|
||
scheme@@(guile-user)> (define snakes
|
||
(fold-packages
|
||
(lambda (package lst)
|
||
(if (string-prefix? "python"
|
||
(package-name package))
|
||
(cons package lst)
|
||
lst))
|
||
'()))
|
||
scheme@@(guile-user)> (length snakes)
|
||
$1 = 361
|
||
@end example
|
||
|
||
If you are hacking on the daemon and its supporting code or if
|
||
@command{guix-daemon} is not already running on your system, you can
|
||
launch it straight from the build tree@footnote{The @option{-E} flag to
|
||
@command{sudo} guarantees that @code{GUILE_LOAD_PATH} is correctly set
|
||
such that @command{guix-daemon} and the tools it uses can find the Guile
|
||
modules they need.}:
|
||
|
||
@example
|
||
$ sudo -E ./pre-inst-env guix-daemon --build-users-group=guixbuild
|
||
@end example
|
||
|
||
The @command{pre-inst-env} script sets up all the environment variables
|
||
necessary to support this, including @env{PATH} and @env{GUILE_LOAD_PATH}.
|
||
|
||
Note that @command{./pre-inst-env guix pull} does @emph{not} upgrade the
|
||
local source tree; it simply updates the @file{~/.config/guix/current}
|
||
symlink (@pxref{Invoking guix pull}). Run @command{git pull} instead if
|
||
you want to upgrade your local source tree.
|
||
|
||
Sometimes, especially if you have recently updated your repository,
|
||
running @command{./pre-inst-env} will print a message similar to the
|
||
following example:
|
||
|
||
@example
|
||
;;; note: source file /home/user/projects/guix/guix/progress.scm
|
||
;;; newer than compiled /home/user/projects/guix/guix/progress.go
|
||
@end example
|
||
|
||
This is only a note and you can safely ignore it. You can get rid of
|
||
the message by running @command{make -j4}. Until you do, Guile will run
|
||
slightly slower because it will interpret the code instead of using
|
||
prepared Guile object (@file{.go}) files.
|
||
|
||
You can run @command{make} automatically as you work using
|
||
@command{watchexec} from the @code{watchexec} package. For example,
|
||
to build again each time you update a package file, run
|
||
@samp{watchexec -w gnu/packages -- make -j4}.
|
||
|
||
@node The Perfect Setup
|
||
@section The Perfect Setup
|
||
|
||
The Perfect Setup to hack on Guix is basically the perfect setup used
|
||
for Guile hacking (@pxref{Using Guile in Emacs,,, guile, Guile Reference
|
||
Manual}). First, you need more than an editor, you need
|
||
@url{https://www.gnu.org/software/emacs, Emacs}, empowered by the
|
||
wonderful @url{https://nongnu.org/geiser/, Geiser}. To set that up, run:
|
||
|
||
@example
|
||
guix install emacs guile emacs-geiser emacs-geiser-guile
|
||
@end example
|
||
|
||
Geiser allows for interactive and incremental development from within
|
||
Emacs: code compilation and evaluation from within buffers, access to
|
||
on-line documentation (docstrings), context-sensitive completion,
|
||
@kbd{M-.} to jump to an object definition, a REPL to try out your code,
|
||
and more (@pxref{Introduction,,, geiser, Geiser User Manual}). If you
|
||
allow Emacs to load the @file{.dir-locals.el} file at the root of the
|
||
project checkout, it will cause Geiser to automatically add the local
|
||
Guix sources to the Guile load path.
|
||
|
||
To actually edit the code, Emacs already has a neat Scheme mode. But in
|
||
addition to that, you must not miss
|
||
@url{https://www.emacswiki.org/emacs/ParEdit, Paredit}. It provides
|
||
facilities to directly operate on the syntax tree, such as raising an
|
||
s-expression or wrapping it, swallowing or rejecting the following
|
||
s-expression, etc.
|
||
|
||
@cindex code snippets
|
||
@cindex templates
|
||
@cindex reducing boilerplate
|
||
We also provide templates for common git commit messages and package
|
||
definitions in the @file{etc/snippets} directory. These templates can
|
||
be used to expand short trigger strings to interactive text snippets. If
|
||
you use @url{https://joaotavora.github.io/yasnippet/, YASnippet}, you
|
||
may want to add the @file{etc/snippets/yas} snippets directory to the
|
||
@var{yas-snippet-dirs} variable. If you use
|
||
@url{https://github.com/minad/tempel/, Tempel}, you may want to add the
|
||
@file{etc/snippets/tempel/*} path to the @var{tempel-path} variable in
|
||
Emacs.
|
||
|
||
@lisp
|
||
;; @r{Assuming the Guix checkout is in ~/src/guix.}
|
||
;; @r{Yasnippet configuration}
|
||
(with-eval-after-load 'yasnippet
|
||
(add-to-list 'yas-snippet-dirs "~/src/guix/etc/snippets/yas"))
|
||
;; @r{Tempel configuration}
|
||
(with-eval-after-load 'tempel
|
||
;; Ensure tempel-path is a list -- it may also be a string.
|
||
(unless (listp 'tempel-path)
|
||
(setq tempel-path (list tempel-path)))
|
||
(add-to-list 'tempel-path "~/src/guix/etc/snippets/tempel/*"))
|
||
@end lisp
|
||
|
||
The commit message snippets depend on @url{https://magit.vc/, Magit} to
|
||
display staged files. When editing a commit message type @code{add}
|
||
followed by @kbd{TAB} to insert a commit message template for adding a
|
||
package; type @code{update} followed by @kbd{TAB} to insert a template
|
||
for updating a package; type @code{https} followed by @kbd{TAB} to
|
||
insert a template for changing the home page URI of a package to HTTPS.
|
||
|
||
The main snippet for @code{scheme-mode} is triggered by typing
|
||
@code{package...} followed by @kbd{TAB}. This snippet also inserts the
|
||
trigger string @code{origin...}, which can be expanded further. The
|
||
@code{origin} snippet in turn may insert other trigger strings ending on
|
||
@code{...}, which also can be expanded further.
|
||
|
||
@cindex insert or update copyright
|
||
@cindex @code{M-x guix-copyright}
|
||
@cindex @code{M-x copyright-update}
|
||
We additionally provide insertion and automatic update of a copyright in
|
||
@file{etc/copyright.el}. You may want to set your full name, mail, and
|
||
load a file.
|
||
|
||
@lisp
|
||
(setq user-full-name "Alice Doe")
|
||
(setq user-mail-address "alice@@mail.org")
|
||
;; @r{Assuming the Guix checkout is in ~/src/guix.}
|
||
(load-file "~/src/guix/etc/copyright.el")
|
||
@end lisp
|
||
|
||
To insert a copyright at the current line invoke @code{M-x guix-copyright}.
|
||
|
||
To update a copyright you need to specify a @code{copyright-names-regexp}.
|
||
|
||
@lisp
|
||
(setq copyright-names-regexp
|
||
(format "%s <%s>" user-full-name user-mail-address))
|
||
@end lisp
|
||
|
||
You can check if your copyright is up to date by evaluating @code{M-x
|
||
copyright-update}. If you want to do it automatically after each buffer
|
||
save then add @code{(add-hook 'after-save-hook 'copyright-update)} in
|
||
Emacs.
|
||
|
||
@subsection Viewing Bugs within Emacs
|
||
|
||
Emacs has a nice minor mode called @code{bug-reference}, which, when
|
||
combined with @samp{emacs-debbugs} (the Emacs package), can be used to
|
||
open links such as @samp{<https://bugs.gnu.org/58697>} or
|
||
@samp{<https://issues.guix.gnu.org/58697>} as bug report buffers. From
|
||
there you can easily consult the email thread via the Gnus interface,
|
||
reply or modify the bug status, all without leaving the comfort of
|
||
Emacs! Below is a sample configuration to add to your @file{~/.emacs}
|
||
configuration file:
|
||
|
||
@lisp
|
||
;;; Bug references.
|
||
(require 'bug-reference)
|
||
(add-hook 'prog-mode-hook #'bug-reference-prog-mode)
|
||
(add-hook 'gnus-mode-hook #'bug-reference-mode)
|
||
(add-hook 'erc-mode-hook #'bug-reference-mode)
|
||
(add-hook 'gnus-summary-mode-hook #'bug-reference-mode)
|
||
(add-hook 'gnus-article-mode-hook #'bug-reference-mode)
|
||
|
||
;;; This extends the default expression (the top-most, first expression
|
||
;;; provided to 'or') to also match URLs such as
|
||
;;; <https://issues.guix.gnu.org/58697> or <https://bugs.gnu.org/58697>.
|
||
;;; It is also extended to detect "Fixes: #NNNNN" git trailers.
|
||
(setq bug-reference-bug-regexp
|
||
(rx (group (or (seq word-boundary
|
||
(or (seq (char "Bb") "ug"
|
||
(zero-or-one " ")
|
||
(zero-or-one "#"))
|
||
(seq (char "Pp") "atch"
|
||
(zero-or-one " ")
|
||
"#")
|
||
(seq (char "Ff") "ixes"
|
||
(zero-or-one ":")
|
||
(zero-or-one " ") "#")
|
||
(seq "RFE"
|
||
(zero-or-one " ") "#")
|
||
(seq "PR "
|
||
(one-or-more (char "a-z+-")) "/"))
|
||
(group (one-or-more (char "0-9"))
|
||
(zero-or-one
|
||
(seq "#" (one-or-more
|
||
(char "0-9"))))))
|
||
(seq (? "<") "https://bugs.gnu.org/"
|
||
(group-n 2 (one-or-more (char "0-9")))
|
||
(? ">"))
|
||
(seq (? "<") "https://issues.guix.gnu.org/"
|
||
(? "issue/")
|
||
(group-n 2 (one-or-more (char "0-9")))
|
||
(? ">"))))))
|
||
(setq bug-reference-url-format "https://issues.guix.gnu.org/%s")
|
||
|
||
(require 'debbugs)
|
||
(require 'debbugs-browse)
|
||
(add-hook 'bug-reference-mode-hook #'debbugs-browse-mode)
|
||
(add-hook 'bug-reference-prog-mode-hook #'debbugs-browse-mode)
|
||
|
||
;; The following allows Emacs Debbugs user to open the issue directly within
|
||
;; Emacs.
|
||
(setq debbugs-browse-url-regexp
|
||
(rx line-start
|
||
"http" (zero-or-one "s") "://"
|
||
(or "debbugs" "issues.guix" "bugs")
|
||
".gnu.org" (one-or-more "/")
|
||
(group (zero-or-one "cgi/bugreport.cgi?bug="))
|
||
(group-n 3 (one-or-more digit))
|
||
line-end))
|
||
@end lisp
|
||
|
||
For more information, refer to @ref{Bug Reference,,, emacs, The GNU
|
||
Emacs Manual} and @ref{Minor Mode,,, debbugs-ug, The Debbugs User
|
||
Guide}.
|
||
|
||
@node Alternative Setups
|
||
@section Alternative Setups
|
||
|
||
Alternative setups than Emacs may let you work on Guix with a
|
||
similar development experience and they might work better with the
|
||
tools you currently use or help you make the transition to Emacs.
|
||
|
||
The options listed below only provide the alternatives to the Emacs
|
||
based setup, which is the most widely used in the Guix community. If
|
||
you want to really understand how is the perfect setup for Guix
|
||
development supposed to work, we encourage you to read the section
|
||
before this regardless the editor you choose to use.
|
||
|
||
@menu
|
||
* Guile Studio:: First step in your transition to Emacs.
|
||
* Vim and NeoVim:: When you are evil to the root.
|
||
@end menu
|
||
|
||
@node Guile Studio
|
||
@subsection Guile Studio
|
||
|
||
Guile Studio is a pre-configured Emacs with mostly everything you need
|
||
to start hacking in Guile. If you are not familiar with Emacs it makes
|
||
the transition easier for you.
|
||
|
||
@example
|
||
guix install guile-studio
|
||
@end example
|
||
|
||
Guile Studio comes with Geiser preinstalled and prepared for action.
|
||
|
||
@node Vim and NeoVim
|
||
@subsection Vim and NeoVim
|
||
|
||
|
||
Vim (and NeoVim) are also packaged in Guix, just in case you decided
|
||
to go for the evil path.
|
||
|
||
@example
|
||
guix install vim
|
||
@end example
|
||
|
||
If you want to enjoy a similar development experience to that in the perfect
|
||
setup, you should install several plugins to configure the editor. Vim (and
|
||
NeoVim) have the equivalent to Paredit,
|
||
@uref{https://www.vim.org/scripts/script.php?script_id=3998,
|
||
@code{paredit.vim}}, that will help you with the structural editing of Scheme
|
||
files (the support for very large files is not great, though).
|
||
|
||
@example
|
||
guix install vim-paredit
|
||
@end example
|
||
|
||
We also recommend that you run @code{:set autoindent} so that your code is
|
||
automatically indented as you type.
|
||
|
||
For the interaction with Git,
|
||
@uref{https://www.vim.org/scripts/script.php?script_id=2975
|
||
@code{fugitive.vim}} is the most commonly used plugin:
|
||
|
||
@example
|
||
guix install vim-fugitive
|
||
@end example
|
||
|
||
And of course if you want to interact with Guix directly from inside of
|
||
vim, using the built-in terminal emulator, we have our very own
|
||
@code{guix.vim} package!
|
||
|
||
@example
|
||
guix install vim-guix-vim
|
||
@end example
|
||
|
||
In NeoVim you can even make a similar setup to Geiser using
|
||
@url{https://conjure.fun/, Conjure} that lets you connect to a running Guile
|
||
process and inject your code there live (sadly it's not packaged in Guix yet).
|
||
|
||
|
||
@node Packaging Guidelines
|
||
@section Packaging Guidelines
|
||
|
||
@cindex packages, creating
|
||
The GNU distribution is nascent and may well lack some of your favorite
|
||
packages. This section describes how you can help make the distribution
|
||
grow.
|
||
|
||
Free software packages are usually distributed in the form of
|
||
@dfn{source code tarballs}---typically @file{tar.gz} files that contain
|
||
all the source files. Adding a package to the distribution means
|
||
essentially two things: adding a @dfn{recipe} that describes how to
|
||
build the package, including a list of other packages required to build
|
||
it, and adding @dfn{package metadata} along with that recipe, such as a
|
||
description and licensing information.
|
||
|
||
In Guix all this information is embodied in @dfn{package definitions}.
|
||
Package definitions provide a high-level view of the package. They are
|
||
written using the syntax of the Scheme programming language; in fact,
|
||
for each package we define a variable bound to the package definition,
|
||
and export that variable from a module (@pxref{Package Modules}).
|
||
However, in-depth Scheme knowledge is @emph{not} a prerequisite for
|
||
creating packages. For more information on package definitions,
|
||
@pxref{Defining Packages}.
|
||
|
||
Once a package definition is in place, stored in a file in the Guix
|
||
source tree, it can be tested using the @command{guix build} command
|
||
(@pxref{Invoking guix build}). For example, assuming the new package is
|
||
called @code{gnew}, you may run this command from the Guix build tree
|
||
(@pxref{Running Guix Before It Is Installed}):
|
||
|
||
@example
|
||
./pre-inst-env guix build gnew --keep-failed
|
||
@end example
|
||
|
||
Using @code{--keep-failed} makes it easier to debug build failures since
|
||
it provides access to the failed build tree. Another useful
|
||
command-line option when debugging is @code{--log-file}, to access the
|
||
build log.
|
||
|
||
If the package is unknown to the @command{guix} command, it may be that
|
||
the source file contains a syntax error, or lacks a @code{define-public}
|
||
clause to export the package variable. To figure it out, you may load
|
||
the module from Guile to get more information about the actual error:
|
||
|
||
@example
|
||
./pre-inst-env guile -c '(use-modules (gnu packages gnew))'
|
||
@end example
|
||
|
||
Once your package builds correctly, please send us a patch
|
||
(@pxref{Submitting Patches}). Well, if you need help, we will be happy to
|
||
help you too. Once the patch is committed in the Guix repository, the
|
||
new package automatically gets built on the supported platforms by
|
||
@url{https://@value{SUBSTITUTE-SERVER-1}, our continuous integration system}.
|
||
|
||
@cindex substituter
|
||
Users can obtain the new package definition simply by running
|
||
@command{guix pull} (@pxref{Invoking guix pull}). When
|
||
@code{@value{SUBSTITUTE-SERVER-1}} is done building the package, installing the
|
||
package automatically downloads binaries from there
|
||
(@pxref{Substitutes}). The only place where human intervention is
|
||
needed is to review and apply the patch.
|
||
|
||
|
||
@menu
|
||
* Software Freedom:: What may go into the distribution.
|
||
* Package Naming:: What's in a name?
|
||
* Version Numbers:: When the name is not enough.
|
||
* Synopses and Descriptions:: Helping users find the right package.
|
||
* Snippets versus Phases:: Whether to use a snippet, or a build phase.
|
||
* Cyclic Module Dependencies:: Going full circle.
|
||
* Emacs Packages:: Your Elisp fix.
|
||
* Python Modules:: A touch of British comedy.
|
||
* Perl Modules:: Little pearls.
|
||
* Java Packages:: Coffee break.
|
||
* Rust Crates:: Beware of oxidation.
|
||
* Elm Packages:: Trees of browser code
|
||
* Fonts:: Fond of fonts.
|
||
@end menu
|
||
|
||
@node Software Freedom
|
||
@subsection Software Freedom
|
||
|
||
@c Adapted from http://www.gnu.org/philosophy/philosophy.html.
|
||
@cindex free software
|
||
The GNU operating system has been developed so that users can have
|
||
freedom in their computing. GNU is @dfn{free software}, meaning that
|
||
users have the @url{https://www.gnu.org/philosophy/free-sw.html,four
|
||
essential freedoms}: to run the program, to study and change the program
|
||
in source code form, to redistribute exact copies, and to distribute
|
||
modified versions. Packages found in the GNU distribution provide only
|
||
software that conveys these four freedoms.
|
||
|
||
In addition, the GNU distribution follow the
|
||
@url{https://www.gnu.org/distros/free-system-distribution-guidelines.html,free
|
||
software distribution guidelines}. Among other things, these guidelines
|
||
reject non-free firmware, recommendations of non-free software, and
|
||
discuss ways to deal with trademarks and patents.
|
||
|
||
Some otherwise free upstream package sources contain a small and optional
|
||
subset that violates the above guidelines, for instance because this subset
|
||
is itself non-free code. When that happens, the offending items are removed
|
||
with appropriate patches or code snippets in the @code{origin} form of the
|
||
package (@pxref{Defining Packages}). This way, @code{guix
|
||
build --source} returns the ``freed'' source rather than the unmodified
|
||
upstream source.
|
||
|
||
|
||
@node Package Naming
|
||
@subsection Package Naming
|
||
|
||
@cindex package name
|
||
A package actually has two names associated with it.
|
||
First, there is the name of the @emph{Scheme variable}, the one following
|
||
@code{define-public}. By this name, the package can be made known in the
|
||
Scheme code, for instance as input to another package. Second, there is
|
||
the string in the @code{name} field of a package definition. This name
|
||
is used by package management commands such as
|
||
@command{guix package} and @command{guix build}.
|
||
|
||
Both are usually the same and correspond to the lowercase conversion of
|
||
the project name chosen upstream, with underscores replaced with
|
||
hyphens. For instance, GNUnet is available as @code{gnunet}, and
|
||
SDL_net as @code{sdl-net}.
|
||
|
||
A noteworthy exception to this rule is when the project name is only a
|
||
single character, or if an older maintained project with the same name
|
||
already exists---regardless of whether it has already been packaged for
|
||
Guix. Use common sense to make such names unambiguous and meaningful.
|
||
For example, Guix's package for the shell called ``s'' upstream is
|
||
@code{s-shell} and @emph{not} @code{s}. Feel free to ask your fellow
|
||
hackers for inspiration.
|
||
|
||
We do not add @code{lib} prefixes for library packages, unless these are
|
||
already part of the official project name. But @pxref{Python
|
||
Modules} and @ref{Perl Modules} for special rules concerning modules for
|
||
the Python and Perl languages.
|
||
|
||
Font package names are handled differently, @pxref{Fonts}.
|
||
|
||
|
||
@node Version Numbers
|
||
@subsection Version Numbers
|
||
|
||
@cindex package version
|
||
We usually package only the latest version of a given free software
|
||
project. But sometimes, for instance for incompatible library versions,
|
||
two (or more) versions of the same package are needed. These require
|
||
different Scheme variable names. We use the name as defined
|
||
in @ref{Package Naming}
|
||
for the most recent version; previous versions use the same name, suffixed
|
||
by @code{-} and the smallest prefix of the version number that may
|
||
distinguish the two versions.
|
||
|
||
The name inside the package definition is the same for all versions of a
|
||
package and does not contain any version number.
|
||
|
||
For instance, the versions 2.24.20 and 3.9.12 of GTK+ may be packaged as follows:
|
||
|
||
@lisp
|
||
(define-public gtk+
|
||
(package
|
||
(name "gtk+")
|
||
(version "3.9.12")
|
||
...))
|
||
(define-public gtk+-2
|
||
(package
|
||
(name "gtk+")
|
||
(version "2.24.20")
|
||
...))
|
||
@end lisp
|
||
If we also wanted GTK+ 3.8.2, this would be packaged as
|
||
@lisp
|
||
(define-public gtk+-3.8
|
||
(package
|
||
(name "gtk+")
|
||
(version "3.8.2")
|
||
...))
|
||
@end lisp
|
||
|
||
@c See <https://lists.gnu.org/archive/html/guix-devel/2016-01/msg00425.html>,
|
||
@c for a discussion of what follows.
|
||
@cindex version number, for VCS snapshots
|
||
Occasionally, we package snapshots of upstream's version control system
|
||
(VCS) instead of formal releases. This should remain exceptional,
|
||
because it is up to upstream developers to clarify what the stable
|
||
release is. Yet, it is sometimes necessary. So, what should we put in
|
||
the @code{version} field?
|
||
|
||
Clearly, we need to make the commit identifier of the VCS snapshot
|
||
visible in the version string, but we also need to make sure that the
|
||
version string is monotonically increasing so that @command{guix package
|
||
--upgrade} can determine which version is newer. Since commit
|
||
identifiers, notably with Git, are not monotonically increasing, we add
|
||
a revision number that we increase each time we upgrade to a newer
|
||
snapshot. The resulting version string looks like this:
|
||
|
||
@example
|
||
2.0.11-3.cabba9e
|
||
^ ^ ^
|
||
| | `-- upstream commit ID
|
||
| |
|
||
| `--- Guix package revision
|
||
|
|
||
latest upstream version
|
||
@end example
|
||
|
||
It is a good idea to strip commit identifiers in the @code{version}
|
||
field to, say, 7 digits. It avoids an aesthetic annoyance (assuming
|
||
aesthetics have a role to play here) as well as problems related to OS
|
||
limits such as the maximum shebang length (127 bytes for the Linux
|
||
kernel). There are helper functions for doing this for packages using
|
||
@code{git-fetch} or @code{hg-fetch} (see below). It is best to use the
|
||
full commit identifiers in @code{origin}s, though, to avoid ambiguities.
|
||
A typical package definition may look like this:
|
||
|
||
|
||
@lisp
|
||
(define my-package
|
||
(let ((commit "c3f29bc928d5900971f65965feaae59e1272a3f7")
|
||
(revision "1")) ;Guix package revision
|
||
(package
|
||
(version (git-version "0.9" revision commit))
|
||
(source (origin
|
||
(method git-fetch)
|
||
(uri (git-reference
|
||
(url "git://example.org/my-package.git")
|
||
(commit commit)))
|
||
(sha256 (base32 "1mbikn@dots{}"))
|
||
(file-name (git-file-name name version))))
|
||
;; @dots{}
|
||
)))
|
||
@end lisp
|
||
|
||
@deffn {Procedure} git-version @var{VERSION} @var{REVISION} @var{COMMIT}
|
||
Return the version string for packages using @code{git-fetch}.
|
||
|
||
@lisp
|
||
(git-version "0.2.3" "0" "93818c936ee7e2f1ba1b315578bde363a7d43d05")
|
||
@result{} "0.2.3-0.93818c9"
|
||
@end lisp
|
||
@end deffn
|
||
|
||
@deffn {Procedure} hg-version @var{VERSION} @var{REVISION} @var{CHANGESET}
|
||
Return the version string for packages using @code{hg-fetch}. It works
|
||
in the same way as @code{git-version}.
|
||
@end deffn
|
||
|
||
@node Synopses and Descriptions
|
||
@subsection Synopses and Descriptions
|
||
|
||
@cindex package description
|
||
@cindex package synopsis
|
||
As we have seen before, each package in GNU@tie{}Guix includes a
|
||
synopsis and a description (@pxref{Defining Packages}). Synopses and
|
||
descriptions are important: They are what @command{guix package
|
||
--search} searches, and a crucial piece of information to help users
|
||
determine whether a given package suits their needs. Consequently,
|
||
packagers should pay attention to what goes into them.
|
||
|
||
Synopses must start with a capital letter and must not end with a
|
||
period. They must not start with ``a'' or ``the'', which usually does
|
||
not bring anything; for instance, prefer ``File-frobbing tool'' over ``A
|
||
tool that frobs files''. The synopsis should say what the package
|
||
is---e.g., ``Core GNU utilities (file, text, shell)''---or what it is
|
||
used for---e.g., the synopsis for GNU@tie{}grep is ``Print lines
|
||
matching a pattern''.
|
||
|
||
Keep in mind that the synopsis must be meaningful for a very wide
|
||
audience. For example, ``Manipulate alignments in the SAM format''
|
||
might make sense for a seasoned bioinformatics researcher, but might be
|
||
fairly unhelpful or even misleading to a non-specialized audience. It
|
||
is a good idea to come up with a synopsis that gives an idea of the
|
||
application domain of the package. In this example, this might give
|
||
something like ``Manipulate nucleotide sequence alignments'', which
|
||
hopefully gives the user a better idea of whether this is what they are
|
||
looking for.
|
||
|
||
Descriptions should take between five and ten lines. Use full
|
||
sentences, and avoid using acronyms without first introducing them.
|
||
Please avoid marketing phrases such as ``world-leading'',
|
||
``industrial-strength'', and ``next-generation'', and avoid superlatives
|
||
like ``the most advanced''---they are not helpful to users looking for a
|
||
package and may even sound suspicious. Instead, try to be factual,
|
||
mentioning use cases and features.
|
||
|
||
@cindex Texinfo markup, in package descriptions
|
||
Descriptions can include Texinfo markup, which is useful to introduce
|
||
ornaments such as @code{@@code} or @code{@@dfn}, bullet lists, or
|
||
hyperlinks (@pxref{Overview,,, texinfo, GNU Texinfo}). However you
|
||
should be careful when using some characters for example @samp{@@} and
|
||
curly braces which are the basic special characters in Texinfo
|
||
(@pxref{Special Characters,,, texinfo, GNU Texinfo}). User interfaces
|
||
such as @command{guix show} take care of rendering it
|
||
appropriately.
|
||
|
||
Synopses and descriptions are translated by volunteers
|
||
@uref{https://translate.fedoraproject.org/projects/guix/packages, at
|
||
Weblate} so that as many users as possible can read them in
|
||
their native language. User interfaces search them and display them in
|
||
the language specified by the current locale.
|
||
|
||
To allow @command{xgettext} to extract them as translatable strings,
|
||
synopses and descriptions @emph{must be literal strings}. This means
|
||
that you cannot use @code{string-append} or @code{format} to construct
|
||
these strings:
|
||
|
||
@lisp
|
||
(package
|
||
;; @dots{}
|
||
(synopsis "This is translatable")
|
||
(description (string-append "This is " "*not*" " translatable.")))
|
||
@end lisp
|
||
|
||
Translation is a lot of work so, as a packager, please pay even more
|
||
attention to your synopses and descriptions as every change may entail
|
||
additional work for translators. In order to help them, it is possible
|
||
to make recommendations or instructions visible to them by inserting
|
||
special comments like this (@pxref{xgettext Invocation,,, gettext, GNU
|
||
Gettext}):
|
||
|
||
@lisp
|
||
;; TRANSLATORS: "X11 resize-and-rotate" should not be translated.
|
||
(description "ARandR is designed to provide a simple visual front end
|
||
for the X11 resize-and-rotate (RandR) extension. @dots{}")
|
||
@end lisp
|
||
|
||
@node Snippets versus Phases
|
||
@subsection Snippets versus Phases
|
||
|
||
@cindex snippets, when to use
|
||
The boundary between using an origin snippet versus a build phase to
|
||
modify the sources of a package can be elusive. Origin snippets are
|
||
typically used to remove unwanted files such as bundled libraries,
|
||
nonfree sources, or to apply simple substitutions. The source derived
|
||
from an origin should produce a source that can be used to build the
|
||
package on any system that the upstream package supports (i.e., act as
|
||
the corresponding source). In particular, origin snippets must not
|
||
embed store items in the sources; such patching should rather be done
|
||
using build phases. Refer to the @code{origin} record documentation for
|
||
more information (@pxref{origin Reference}).
|
||
|
||
@node Cyclic Module Dependencies
|
||
@subsection Cyclic Module Dependencies
|
||
|
||
While there cannot be circular dependencies between packages, Guile's
|
||
lax module loading mechanism allows circular dependencies between Guile
|
||
modules, which doesn't cause problems as long as the following
|
||
conditions are followed for two modules part of a dependency cycle:
|
||
|
||
@cindex rules to cope with circular module dependencies
|
||
@enumerate
|
||
@item
|
||
Macros are not shared between the co-dependent modules
|
||
@item
|
||
Top-level variables are only referenced in delayed (@i{thunked}) package
|
||
fields: @code{arguments}, @code{native-inputs}, @code{inputs},
|
||
@code{propagated-inputs} or @code{replacement}
|
||
@item
|
||
Procedures referencing top-level variables from another module are not
|
||
called at the top level of a module themselves.
|
||
@end enumerate
|
||
|
||
Straying away from the above rules may work while there are no
|
||
dependency cycles between modules, but given such cycles are confusing
|
||
and difficult to troubleshoot, it is best to follow the rules to avoid
|
||
introducing problems down the line.
|
||
|
||
@noindent
|
||
Here is a common trap to avoid:
|
||
|
||
@lisp
|
||
(define-public avr-binutils
|
||
(package
|
||
(inherit (cross-binutils "avr"))
|
||
(name "avr-binutils")))
|
||
@end lisp
|
||
|
||
In the above example, the @code{avr-binutils} package was defined in the
|
||
module @code{(gnu packages avr)}, and the @code{cross-binutils}
|
||
procedure in @code{(gnu packages cross-base)}. Because the
|
||
@code{inherit} field is not delayed (thunked), it is evaluated at the
|
||
top level at load time, which is problematic in the presence of module
|
||
dependency cycles. This could be resolved by turning the package into a
|
||
procedure instead, like:
|
||
|
||
@lisp
|
||
(define (make-avr-binutils)
|
||
(package
|
||
(inherit (cross-binutils "avr"))
|
||
(name "avr-binutils")))
|
||
@end lisp
|
||
|
||
Care would need to be taken to ensure the above procedure is only ever
|
||
used in a package delayed fields or within another procedure also not
|
||
called at the top level.
|
||
|
||
@node Emacs Packages
|
||
@subsection Emacs Packages
|
||
|
||
@cindex emacs, packaging
|
||
@cindex elisp, packaging
|
||
Emacs packages should preferably use the Emacs build system
|
||
(@pxref{emacs-build-system}), for uniformity and the benefits provided
|
||
by its build phases, such as the auto-generation of the autoloads file
|
||
and the byte compilation of the sources. Because there is no
|
||
standardized way to run a test suite for Emacs packages, tests are
|
||
disabled by default. When a test suite is available, it should be
|
||
enabled by setting the @code{#:tests?} argument to @code{#true}. By
|
||
default, the command to run the test is @command{make check}, but any
|
||
command can be specified via the @code{#:test-command} argument. The
|
||
@code{#:test-command} argument expects a list containing a command and
|
||
its arguments, to be invoked during the @code{check} phase.
|
||
|
||
The Elisp dependencies of Emacs packages are typically provided as
|
||
@code{propagated-inputs} when required at run time. As for other
|
||
packages, build or test dependencies should be specified as
|
||
@code{native-inputs}.
|
||
|
||
Emacs packages sometimes depend on resources directories that should be
|
||
installed along the Elisp files. The @code{#:include} argument can be
|
||
used for that purpose, by specifying a list of regexps to match. The
|
||
best practice when using the @code{#:include} argument is to extend
|
||
rather than override its default value (accessible via the
|
||
@code{%default-include} variable). As an example, a yasnippet extension
|
||
package typically include a @file{snippets} directory, which could be
|
||
copied to the installation directory using:
|
||
|
||
@lisp
|
||
#:include (cons "^snippets/" %default-include)
|
||
@end lisp
|
||
|
||
When encountering problems, it is wise to check for the presence of the
|
||
@code{Package-Requires} extension header in the package main source
|
||
file, and whether any dependencies and their versions listed therein are
|
||
satisfied.
|
||
|
||
@node Python Modules
|
||
@subsection Python Modules
|
||
|
||
@cindex python
|
||
We currently package Python 2 and Python 3, under the Scheme variable names
|
||
@code{python-2} and @code{python} as explained in @ref{Version Numbers}.
|
||
To avoid confusion and naming clashes with other programming languages, it
|
||
seems desirable that the name of a package for a Python module contains
|
||
the word @code{python}.
|
||
|
||
Some modules are compatible with only one version of Python, others with
|
||
both. If the package Foo is compiled with Python 3, we name it
|
||
@code{python-foo}. If it is compiled with Python 2, we name it
|
||
@code{python2-foo}. Python 2 packages are being removed from the
|
||
distribution; please do no not submit any new Python 2 packages.
|
||
|
||
If a project already contains the word @code{python}, we drop this;
|
||
for instance, the module python-dateutil is packaged under the names
|
||
@code{python-dateutil} and @code{python2-dateutil}. If the project name
|
||
starts with @code{py} (e.g.@: @code{pytz}), we keep it and prefix it as
|
||
described above.
|
||
|
||
@quotation Note
|
||
Currently there are two different build systems for Python packages in Guix:
|
||
@var{python-build-system} and @var{pyproject-build-system}. For the
|
||
longest time, Python packages were built from an informally specified
|
||
@file{setup.py} file. That worked amazingly well, considering Python's
|
||
success, but was difficult to build tooling around. As a result, a host
|
||
of alternative build systems emerged and the community eventually settled on a
|
||
@url{https://peps.python.org/pep-0517/, formal standard} for specifying build
|
||
requirements. @var{pyproject-build-system} is Guix's implementation of this
|
||
standard. It is considered ``experimental'' in that it does not yet support
|
||
all the various PEP-517 @emph{build backends}, but you are encouraged to try
|
||
it for new Python packages and report any problems. It will eventually be
|
||
deprecated and merged into @var{python-build-system}.
|
||
@end quotation
|
||
|
||
@subsubsection Specifying Dependencies
|
||
@cindex inputs, for Python packages
|
||
|
||
Dependency information for Python packages is usually available in the
|
||
package source tree, with varying degrees of accuracy: in the
|
||
@file{pyproject.toml} file, the @file{setup.py} file, in
|
||
@file{requirements.txt}, or in @file{tox.ini} (the latter mostly for
|
||
test dependencies).
|
||
|
||
Your mission, when writing a recipe for a Python package, is to map
|
||
these dependencies to the appropriate type of ``input'' (@pxref{package
|
||
Reference, inputs}). Although the @code{pypi} importer normally does a
|
||
good job (@pxref{Invoking guix import}), you may want to check the
|
||
following check list to determine which dependency goes where.
|
||
|
||
@itemize
|
||
|
||
@item
|
||
We currently package Python with @code{setuptools} and @code{pip}
|
||
installed per default. This is about to change, and users are encouraged
|
||
to use @code{python-toolchain} if they want a build environment for Python.
|
||
|
||
@command{guix lint} will warn if @code{setuptools} or @code{pip} are
|
||
added as native-inputs because they are generally not necessary.
|
||
|
||
@item
|
||
Python dependencies required at run time go into
|
||
@code{propagated-inputs}. They are typically defined with the
|
||
@code{install_requires} keyword in @file{setup.py}, or in the
|
||
@file{requirements.txt} file.
|
||
|
||
@item
|
||
Python packages required only at build time---e.g., those listed under
|
||
@code{build-system.requires} in @file{pyproject.toml} or with the
|
||
@code{setup_requires} keyword in @file{setup.py}---or dependencies only
|
||
for testing---e.g., those in @code{tests_require} or @file{tox.ini}---go into
|
||
@code{native-inputs}. The rationale is that (1) they do not need to be
|
||
propagated because they are not needed at run time, and (2) in a
|
||
cross-compilation context, it's the ``native'' input that we'd want.
|
||
|
||
Examples are the @code{pytest}, @code{mock}, and @code{nose} test
|
||
frameworks. Of course if any of these packages is also required at
|
||
run-time, it needs to go to @code{propagated-inputs}.
|
||
|
||
@item
|
||
Anything that does not fall in the previous categories goes to
|
||
@code{inputs}, for example programs or C libraries required for building
|
||
Python packages containing C extensions.
|
||
|
||
@item
|
||
If a Python package has optional dependencies (@code{extras_require}),
|
||
it is up to you to decide whether to add them or not, based on their
|
||
usefulness/overhead ratio (@pxref{Submitting Patches, @command{guix
|
||
size}}).
|
||
|
||
@end itemize
|
||
|
||
|
||
@node Perl Modules
|
||
@subsection Perl Modules
|
||
|
||
@cindex perl
|
||
Perl programs standing for themselves are named as any other package,
|
||
using the lowercase upstream name.
|
||
For Perl packages containing a single class, we use the lowercase class name,
|
||
replace all occurrences of @code{::} by dashes and prepend the prefix
|
||
@code{perl-}.
|
||
So the class @code{XML::Parser} becomes @code{perl-xml-parser}.
|
||
Modules containing several classes keep their lowercase upstream name and
|
||
are also prepended by @code{perl-}. Such modules tend to have the word
|
||
@code{perl} somewhere in their name, which gets dropped in favor of the
|
||
prefix. For instance, @code{libwww-perl} becomes @code{perl-libwww}.
|
||
|
||
|
||
@node Java Packages
|
||
@subsection Java Packages
|
||
|
||
@cindex java
|
||
Java programs standing for themselves are named as any other package,
|
||
using the lowercase upstream name.
|
||
|
||
To avoid confusion and naming clashes with other programming languages,
|
||
it is desirable that the name of a package for a Java package is
|
||
prefixed with @code{java-}. If a project already contains the word
|
||
@code{java}, we drop this; for instance, the package @code{ngsjava} is
|
||
packaged under the name @code{java-ngs}.
|
||
|
||
For Java packages containing a single class or a small class hierarchy,
|
||
we use the lowercase class name, replace all occurrences of @code{.} by
|
||
dashes and prepend the prefix @code{java-}. So the class
|
||
@code{apache.commons.cli} becomes package
|
||
@code{java-apache-commons-cli}.
|
||
|
||
|
||
@node Rust Crates
|
||
@subsection Rust Crates
|
||
|
||
@cindex rust
|
||
Rust programs standing for themselves are named as any other package, using the
|
||
lowercase upstream name.
|
||
|
||
To prevent namespace collisions we prefix all other Rust packages with the
|
||
@code{rust-} prefix. The name should be changed to lowercase as appropriate and
|
||
dashes should remain in place.
|
||
|
||
In the rust ecosystem it is common for multiple incompatible versions of a
|
||
package to be used at any given time, so all package definitions should have a
|
||
versioned suffix. The versioned suffix is the left-most non-zero digit (and
|
||
any leading zeros, of course). This follows the ``caret'' version scheme
|
||
intended by Cargo. Examples@: @code{rust-clap-2}, @code{rust-rand-0.6}.
|
||
|
||
Because of the difficulty in reusing rust packages as pre-compiled inputs for
|
||
other packages the Cargo build system (@pxref{Build Systems,
|
||
@code{cargo-build-system}}) presents the @code{#:cargo-inputs} and
|
||
@code{cargo-development-inputs} keywords as build system arguments. It would be
|
||
helpful to think of these as similar to @code{propagated-inputs} and
|
||
@code{native-inputs}. Rust @code{dependencies} and @code{build-dependencies}
|
||
should go in @code{#:cargo-inputs}, and @code{dev-dependencies} should go in
|
||
@code{#:cargo-development-inputs}. If a Rust package links to other libraries
|
||
then the standard placement in @code{inputs} and the like should be used.
|
||
|
||
Care should be taken to ensure the correct version of dependencies are used; to
|
||
this end we try to refrain from skipping the tests or using @code{#:skip-build?}
|
||
when possible. Of course this is not always possible, as the package may be
|
||
developed for a different Operating System, depend on features from the Nightly
|
||
Rust compiler, or the test suite may have atrophied since it was released.
|
||
|
||
|
||
@node Elm Packages
|
||
@subsection Elm Packages
|
||
|
||
@cindex Elm
|
||
Elm applications can be named like other software: their names need not
|
||
mention Elm.
|
||
|
||
Packages in the Elm sense (see @code{elm-build-system} under @ref{Build
|
||
Systems}) are required use names of the format
|
||
@var{author}@code{/}@var{project}, where both the @var{author} and the
|
||
@var{project} may contain hyphens internally, and the @var{author} sometimes
|
||
contains uppercase letters.
|
||
|
||
To form the Guix package name from the upstream name, we follow a convention
|
||
similar to Python packages (@pxref{Python Modules}), adding an @code{elm-}
|
||
prefix unless the name would already begin with @code{elm-}.
|
||
|
||
In many cases we can reconstruct an Elm package's upstream name heuristically,
|
||
but, since conversion to a Guix-style name involves a loss of information,
|
||
this is not always possible. Care should be taken to add the
|
||
@code{'upstream-name} property when necessary so that @samp{guix import elm}
|
||
will work correctly (@pxref{Invoking guix import}). The most notable scenarios
|
||
when explicitly specifying the upstream name is necessary are:
|
||
|
||
@enumerate
|
||
@item
|
||
When the @var{author} is @code{elm} and the @var{project} contains one or more
|
||
hyphens, as with @code{elm/virtual-dom}; and
|
||
|
||
@item
|
||
When the @var{author} contains hyphens or uppercase letters, as with
|
||
@code{Elm-Canvas/raster-shapes}---unless the @var{author} is
|
||
@code{elm-explorations}, which is handled as a special case, so packages like
|
||
@code{elm-explorations/markdown} do @emph{not} need to use the
|
||
@code{'upstream-name} property.
|
||
@end enumerate
|
||
|
||
The module @code{(guix build-system elm)} provides the following utilities for
|
||
working with names and related conventions:
|
||
|
||
@deffn {Procedure} elm-package-origin @var{elm-name} @var{version} @
|
||
@var{hash}
|
||
Returns a Git origin using the repository naming and tagging regime required
|
||
for a published Elm package with the upstream name @var{elm-name} at version
|
||
@var{version} with sha256 checksum @var{hash}.
|
||
|
||
For example:
|
||
@lisp
|
||
(package
|
||
(name "elm-html")
|
||
(version "1.0.0")
|
||
(source
|
||
(elm-package-origin
|
||
"elm/html"
|
||
version
|
||
(base32 "15k1679ja57vvlpinpv06znmrxy09lbhzfkzdc89i01qa8c4gb4a")))
|
||
...)
|
||
@end lisp
|
||
@end deffn
|
||
|
||
@deffn {Procedure} elm->package-name @var{elm-name}
|
||
Returns the Guix-style package name for an Elm package with upstream name
|
||
@var{elm-name}.
|
||
|
||
Note that there is more than one possible @var{elm-name} for which
|
||
@code{elm->package-name} will produce a given result.
|
||
@end deffn
|
||
|
||
@deffn {Procedure} guix-package->elm-name @var{package}
|
||
Given an Elm @var{package}, returns the possibly-inferred upstream name, or
|
||
@code{#f} the upstream name is not specified via the @code{'upstream-name}
|
||
property and can not be inferred by @code{infer-elm-package-name}.
|
||
@end deffn
|
||
|
||
@deffn {Procedure} infer-elm-package-name @var{guix-name}
|
||
Given the @var{guix-name} of an Elm package, returns the inferred upstream
|
||
name, or @code{#f} if the upstream name can't be inferred. If the result is
|
||
not @code{#f}, supplying it to @code{elm->package-name} would produce
|
||
@var{guix-name}.
|
||
@end deffn
|
||
|
||
@node Fonts
|
||
@subsection Fonts
|
||
|
||
@cindex fonts
|
||
For fonts that are in general not installed by a user for typesetting
|
||
purposes, or that are distributed as part of a larger software package,
|
||
we rely on the general packaging rules for software; for instance, this
|
||
applies to the fonts delivered as part of the X.Org system or fonts that
|
||
are part of TeX Live.
|
||
|
||
To make it easier for a user to search for fonts, names for other packages
|
||
containing only fonts are constructed as follows, independently of the
|
||
upstream package name.
|
||
|
||
The name of a package containing only one font family starts with
|
||
@code{font-}; it is followed by the foundry name and a dash @code{-}
|
||
if the foundry is known, and the font family name, in which spaces are
|
||
replaced by dashes (and as usual, all upper case letters are transformed
|
||
to lower case).
|
||
For example, the Gentium font family by SIL is packaged under the name
|
||
@code{font-sil-gentium}.
|
||
|
||
For a package containing several font families, the name of the collection
|
||
is used in the place of the font family name.
|
||
For instance, the Liberation fonts consist of three families,
|
||
Liberation Sans, Liberation Serif and Liberation Mono.
|
||
These could be packaged separately under the names
|
||
@code{font-liberation-sans} and so on; but as they are distributed together
|
||
under a common name, we prefer to package them together as
|
||
@code{font-liberation}.
|
||
|
||
In the case where several formats of the same font family or font collection
|
||
are packaged separately, a short form of the format, prepended by a dash,
|
||
is added to the package name. We use @code{-ttf} for TrueType fonts,
|
||
@code{-otf} for OpenType fonts and @code{-type1} for PostScript Type 1
|
||
fonts.
|
||
|
||
|
||
@node Coding Style
|
||
@section Coding Style
|
||
|
||
In general our code follows the GNU Coding Standards (@pxref{Top,,,
|
||
standards, GNU Coding Standards}). However, they do not say much about
|
||
Scheme, so here are some additional rules.
|
||
|
||
@menu
|
||
* Programming Paradigm:: How to compose your elements.
|
||
* Modules:: Where to store your code?
|
||
* Data Types and Pattern Matching:: Implementing data structures.
|
||
* Formatting Code:: Writing conventions.
|
||
@end menu
|
||
|
||
@node Programming Paradigm
|
||
@subsection Programming Paradigm
|
||
|
||
Scheme code in Guix is written in a purely functional style. One
|
||
exception is code that involves input/output, and procedures that
|
||
implement low-level concepts, such as the @code{memoize} procedure.
|
||
|
||
@node Modules
|
||
@subsection Modules
|
||
|
||
Guile modules that are meant to be used on the builder side must live in
|
||
the @code{(guix build @dots{})} name space. They must not refer to
|
||
other Guix or GNU modules. However, it is OK for a ``host-side'' module
|
||
to use a build-side module.
|
||
|
||
Modules that deal with the broader GNU system should be in the
|
||
@code{(gnu @dots{})} name space rather than @code{(guix @dots{})}.
|
||
|
||
@node Data Types and Pattern Matching
|
||
@subsection Data Types and Pattern Matching
|
||
|
||
The tendency in classical Lisp is to use lists to represent everything,
|
||
and then to browse them ``by hand'' using @code{car}, @code{cdr},
|
||
@code{cadr}, and co. There are several problems with that style,
|
||
notably the fact that it is hard to read, error-prone, and a hindrance
|
||
to proper type error reports.
|
||
|
||
@findex define-record-type*
|
||
@findex match-record
|
||
@cindex pattern matching
|
||
Guix code should define appropriate data types (for instance, using
|
||
@code{define-record-type*}) rather than abuse lists. In addition, it
|
||
should use pattern matching, via Guile’s @code{(ice-9 match)} module,
|
||
especially when matching lists (@pxref{Pattern Matching,,, guile, GNU
|
||
Guile Reference Manual}); pattern matching for records is better done
|
||
using @code{match-record} from @code{(guix records)}, which, unlike
|
||
@code{match}, verifies field names at macro-expansion time.
|
||
|
||
When defining a new record type, keep the @dfn{record type descriptor}
|
||
(RTD) private (@pxref{Records,,, guile, GNU Guile Reference Manual}, for
|
||
more on records and RTDs). As an example, the @code{(guix packages)}
|
||
module defines @code{<package>} as the RTD for package records but it
|
||
does not export it; instead, it exports a type predicate, a constructor,
|
||
and field accessors. Exporting RTDs would make it harder to change the
|
||
application binary interface (because code in other modules might be
|
||
matching fields by position) and would make it trivial for users to
|
||
forge records of that type, bypassing any checks we may have in the
|
||
official constructor (such as ``field sanitizers'').
|
||
|
||
@node Formatting Code
|
||
@subsection Formatting Code
|
||
|
||
@cindex formatting code
|
||
@cindex coding style
|
||
When writing Scheme code, we follow common wisdom among Scheme
|
||
programmers. In general, we follow the
|
||
@url{https://mumble.net/~campbell/scheme/style.txt, Riastradh's Lisp
|
||
Style Rules}. This document happens to describe the conventions mostly
|
||
used in Guile’s code too. It is very thoughtful and well written, so
|
||
please do read it.
|
||
|
||
Some special forms introduced in Guix, such as the @code{substitute*}
|
||
macro, have special indentation rules. These are defined in the
|
||
@file{.dir-locals.el} file, which Emacs automatically uses. Also note
|
||
that Emacs-Guix provides @code{guix-devel-mode} mode that indents and
|
||
highlights Guix code properly (@pxref{Development,,, emacs-guix, The
|
||
Emacs-Guix Reference Manual}).
|
||
|
||
@cindex indentation, of code
|
||
@cindex formatting, of code
|
||
If you do not use Emacs, please make sure to let your editor knows these
|
||
rules. To automatically indent a package definition, you can also run:
|
||
|
||
@example
|
||
./pre-inst-env guix style @var{package}
|
||
@end example
|
||
|
||
@noindent
|
||
@xref{Invoking guix style}, for more information.
|
||
|
||
We require all top-level procedures to carry a docstring. This
|
||
requirement can be relaxed for simple private procedures in the
|
||
@code{(guix build @dots{})} name space, though.
|
||
|
||
Procedures should not have more than four positional parameters. Use
|
||
keyword parameters for procedures that take more than four parameters.
|
||
|
||
|
||
@node Submitting Patches
|
||
@section Submitting Patches
|
||
|
||
Development is done using the Git distributed version control system.
|
||
Thus, access to the repository is not strictly necessary. We welcome
|
||
contributions in the form of patches as produced by @code{git
|
||
format-patch} sent to the @email{guix-patches@@gnu.org} mailing list
|
||
(@pxref{Submitting patches to a project,,, git, Git User Manual}).
|
||
Contributors are encouraged to take a moment to set some Git repository
|
||
options (@pxref{Configuring Git}) first, which can improve the
|
||
readability of patches. Seasoned Guix developers may also want to look
|
||
at the section on commit access (@pxref{Commit Access}).
|
||
|
||
This mailing list is backed by a Debbugs instance, which allows us to
|
||
keep track of submissions (@pxref{Tracking Bugs and Changes}).
|
||
Each message sent to that mailing list gets a new tracking number
|
||
assigned; people can then follow up on the submission by sending email
|
||
to @code{@var{ISSUE_NUMBER}@@debbugs.gnu.org}, where @var{ISSUE_NUMBER}
|
||
is the tracking number (@pxref{Sending a Patch Series}).
|
||
|
||
Please write commit logs in the ChangeLog format (@pxref{Change Logs,,,
|
||
standards, GNU Coding Standards}); you can check the commit history for
|
||
examples.
|
||
|
||
You can help make the review process more efficient, and increase the
|
||
chance that your patch will be reviewed quickly, by describing the
|
||
context of your patch and the impact you expect it to have. For
|
||
example, if your patch is fixing something that is broken, describe the
|
||
problem and how your patch fixes it. Tell us how you have tested your
|
||
patch. Will users of the code changed by your patch have to adjust
|
||
their workflow at all? If so, tell us how. In general, try to imagine
|
||
what questions a reviewer will ask, and answer those questions in
|
||
advance.
|
||
|
||
Before submitting a patch that adds or modifies a package definition,
|
||
please run through this check list:
|
||
|
||
@enumerate
|
||
@item
|
||
If the authors of the packaged software provide a cryptographic
|
||
signature for the release tarball, make an effort to verify the
|
||
authenticity of the archive. For a detached GPG signature file this
|
||
would be done with the @code{gpg --verify} command.
|
||
|
||
@item
|
||
Take some time to provide an adequate synopsis and description for the
|
||
package. @xref{Synopses and Descriptions}, for some guidelines.
|
||
|
||
@item
|
||
Run @code{guix lint @var{package}}, where @var{package} is the
|
||
name of the new or modified package, and fix any errors it reports
|
||
(@pxref{Invoking guix lint}).
|
||
|
||
@item
|
||
Run @code{guix style @var{package}} to format the new package definition
|
||
according to the project's conventions (@pxref{Invoking guix style}).
|
||
|
||
@item
|
||
Make sure the package builds on your platform, using @code{guix build
|
||
@var{package}}.
|
||
|
||
@item
|
||
We recommend you also try building the package on other supported
|
||
platforms. As you may not have access to actual hardware platforms, we
|
||
recommend using the @code{qemu-binfmt-service-type} to emulate them. In
|
||
order to enable it, add the @code{virtualization} service module and the
|
||
following service to the list of services in your @code{operating-system}
|
||
configuration:
|
||
|
||
@lisp
|
||
(service qemu-binfmt-service-type
|
||
(qemu-binfmt-configuration
|
||
(platforms (lookup-qemu-platforms "arm" "aarch64"))))
|
||
@end lisp
|
||
|
||
Then reconfigure your system.
|
||
|
||
You can then build packages for different platforms by specifying the
|
||
@code{--system} option. For example, to build the "hello" package for
|
||
the armhf or aarch64 architectures, you would run the following
|
||
commands, respectively:
|
||
@example
|
||
guix build --system=armhf-linux --rounds=2 hello
|
||
guix build --system=aarch64-linux --rounds=2 hello
|
||
@end example
|
||
|
||
@item
|
||
@cindex bundling
|
||
Make sure the package does not use bundled copies of software already
|
||
available as separate packages.
|
||
|
||
Sometimes, packages include copies of the source code of their
|
||
dependencies as a convenience for users. However, as a distribution, we
|
||
want to make sure that such packages end up using the copy we already
|
||
have in the distribution, if there is one. This improves resource usage
|
||
(the dependency is built and stored only once), and allows the
|
||
distribution to make transverse changes such as applying security
|
||
updates for a given software package in a single place and have them
|
||
affect the whole system---something that bundled copies prevent.
|
||
|
||
@item
|
||
Take a look at the profile reported by @command{guix size}
|
||
(@pxref{Invoking guix size}). This will allow you to notice references
|
||
to other packages unwillingly retained. It may also help determine
|
||
whether to split the package (@pxref{Packages with Multiple Outputs}),
|
||
and which optional dependencies should be used. In particular, avoid
|
||
adding @code{texlive} as a dependency: because of its extreme size, use
|
||
@code{texlive-updmap.cfg} procedure instead.
|
||
|
||
@item
|
||
Check that dependent packages (if applicable) are not affected by the
|
||
change; @code{guix refresh --list-dependent @var{package}} will help you
|
||
do that (@pxref{Invoking guix refresh}).
|
||
|
||
@item
|
||
@cindex determinism, of build processes
|
||
@cindex reproducible builds, checking
|
||
Check whether the package's build process is deterministic. This
|
||
typically means checking whether an independent build of the package
|
||
yields the exact same result that you obtained, bit for bit.
|
||
|
||
A simple way to do that is by building the same package several times in
|
||
a row on your machine (@pxref{Invoking guix build}):
|
||
|
||
@example
|
||
guix build --rounds=2 my-package
|
||
@end example
|
||
|
||
This is enough to catch a class of common non-determinism issues, such
|
||
as timestamps or randomly-generated output in the build result.
|
||
|
||
Another option is to use @command{guix challenge} (@pxref{Invoking guix
|
||
challenge}). You may run it once the package has been committed and
|
||
built by @code{@value{SUBSTITUTE-SERVER-1}} to check whether it obtains the same
|
||
result as you did. Better yet: Find another machine that can build it
|
||
and run @command{guix publish}. Since the remote build machine is
|
||
likely different from yours, this can catch non-determinism issues
|
||
related to the hardware---e.g., use of different instruction set
|
||
extensions---or to the operating system kernel---e.g., reliance on
|
||
@code{uname} or @file{/proc} files.
|
||
|
||
@item
|
||
When writing documentation, please use gender-neutral wording when
|
||
referring to people, such as
|
||
@uref{https://en.wikipedia.org/wiki/Singular_they, singular
|
||
``they''@comma{} ``their''@comma{} ``them''}, and so forth.
|
||
|
||
@item
|
||
Verify that your patch contains only one set of related changes.
|
||
Bundling unrelated changes together makes reviewing harder and slower.
|
||
|
||
Examples of unrelated changes include the addition of several packages,
|
||
or a package update along with fixes to that package.
|
||
|
||
@item
|
||
Please follow our code formatting rules, possibly running
|
||
@command{guix style} script to do that automatically for you
|
||
(@pxref{Formatting Code}).
|
||
|
||
@item
|
||
When possible, use mirrors in the source URL (@pxref{Invoking guix download}).
|
||
Use reliable URLs, not generated ones. For instance, GitHub archives are not
|
||
necessarily identical from one generation to the next, so in this case it's
|
||
often better to clone the repository. Don't use the @command{name} field in
|
||
the URL: it is not very useful and if the name changes, the URL will probably
|
||
be wrong.
|
||
|
||
@item
|
||
Check if Guix builds (@pxref{Building from Git}) and address the
|
||
warnings, especially those about use of undefined symbols.
|
||
|
||
@item
|
||
Make sure your changes do not break Guix and simulate a @code{guix pull} with:
|
||
@example
|
||
guix pull --url=/path/to/your/checkout --profile=/tmp/guix.master
|
||
@end example
|
||
|
||
@end enumerate
|
||
|
||
When posting a patch to the mailing list, use @samp{[PATCH] @dots{}} as
|
||
a subject, if your patch is to be applied on a branch other than
|
||
@code{master}, say @code{core-updates}, specify it in the subject like
|
||
@samp{[PATCH core-updates] @dots{}}.
|
||
|
||
You may use your email client or the @command{git send-email} command
|
||
(@pxref{Sending a Patch Series}). We prefer to get patches in plain
|
||
text messages, either inline or as MIME attachments. You are advised to
|
||
pay attention if your email client changes anything like line breaks or
|
||
indentation which could potentially break the patches.
|
||
|
||
Expect some delay when you submit your very first patch to
|
||
@email{guix-patches@@gnu.org}. You have to wait until you get an
|
||
acknowledgement with the assigned tracking number. Future acknowledgements
|
||
should not be delayed.
|
||
|
||
When a bug is resolved, please close the thread by sending an email to
|
||
@email{@var{ISSUE_NUMBER}-done@@debbugs.gnu.org}.
|
||
|
||
@menu
|
||
* Configuring Git::
|
||
* Sending a Patch Series::
|
||
* Teams::
|
||
@end menu
|
||
|
||
@node Configuring Git
|
||
@subsection Configuring Git
|
||
@cindex git configuration
|
||
@cindex @code{git format-patch}
|
||
@cindex @code{git send-email}
|
||
|
||
If you have not done so already, you may wish to set a name and email
|
||
that will be associated with your commits (@pxref{telling git your name,
|
||
, Telling Git your name, git, Git User Manual}). If you wish to use a
|
||
different name or email just for commits in this repository, you can
|
||
use @command{git config --local}, or edit @file{.git/config} in the
|
||
repository instead of @file{~/.gitconfig}.
|
||
|
||
Other important Git configuration will automatically be configured when
|
||
building the project (@pxref{Building from Git}).
|
||
|
||
@node Sending a Patch Series
|
||
@subsection Sending a Patch Series
|
||
@cindex patch series
|
||
@cindex @code{git send-email}
|
||
@cindex @code{git format-patch}
|
||
|
||
@unnumberedsubsubsec Single Patches
|
||
@anchor{Single Patches}
|
||
The @command{git send-email} command is the best way to send both single
|
||
patches and patch series (@pxref{Multiple Patches}) to the Guix mailing
|
||
list. Sending patches as email attachments may make them difficult to
|
||
review in some mail clients, and @command{git diff} does not store commit
|
||
metadata.
|
||
|
||
@quotation Note
|
||
The @command{git send-email} command is provided by the @code{send-email}
|
||
output of the @code{git} package, i.e. @code{git:send-email}.
|
||
@end quotation
|
||
|
||
The following command will create a patch email from the latest commit,
|
||
open it in your @var{EDITOR} or @var{VISUAL} for editing, and send it to
|
||
the Guix mailing list to be reviewed and merged. Assuming you have
|
||
already configured Git according to @xref{Configuring Git}, you can
|
||
simply use:
|
||
|
||
@example
|
||
$ git send-email --annotate -1
|
||
@end example
|
||
|
||
@quotation Tip
|
||
To add a prefix to the subject of your patch, you may use the
|
||
@option{--subject-prefix} option. The Guix project uses this to
|
||
specify that the patch is intended for a branch or repository
|
||
other than the @code{master} branch of
|
||
@url{https://git.savannah.gnu.org/cgit/guix.git}.
|
||
|
||
@example
|
||
git send-email --annotate --subject-prefix='PATCH core-updates' -1
|
||
@end example
|
||
@end quotation
|
||
|
||
The patch email contains a three-dash separator line after the commit
|
||
message. You may ``annotate'' the patch with explanatory text by adding
|
||
it under this line. If you do not wish to annotate the email, you may
|
||
drop the @option{--annotate} option.
|
||
|
||
If you need to send a revised patch, don't resend it like this or send
|
||
a ``fix'' patch to be applied on top of the last one; instead, use
|
||
@command{git commit --amend} or @url{https://git-rebase.io,
|
||
@command{git rebase}} to modify the commit, and use the
|
||
@email{@var{ISSUE_NUMBER}@@debbugs.gnu.org} address and the @option{-v}
|
||
flag with @command{git send-email}.
|
||
|
||
@example
|
||
$ git commit --amend
|
||
$ git send-email --annotate -v@var{REVISION} \
|
||
--to=@var{ISSUE_NUMBER}@@debbugs.gnu.org -1
|
||
@end example
|
||
|
||
@quotation Note
|
||
Due to an apparent bug in @command{git send-email},
|
||
@option{-v @var{REVISION}} (with the space) will not work; you
|
||
@emph{must} use @option{-v@var{REVISION}}.
|
||
@end quotation
|
||
|
||
You can find out @var{ISSUE_NUMBER} either by searching on the mumi
|
||
interface at @url{https://issues.guix.gnu.org} for the name of your patch or
|
||
reading the acknowledgement email sent automatically by Debbugs in
|
||
reply to incoming bugs and patches, which contains the bug number.
|
||
|
||
@unnumberedsubsubsec Notifying Teams
|
||
@anchor{Notifying Teams}
|
||
@cindex teams
|
||
If your git checkout has been correctly configured (@pxref{Configuring
|
||
Git}), the @command{git send-email} command will automatically notify
|
||
the appropriate team members, based on the scope of your changes. This
|
||
relies on the @file{etc/teams.scm} script, which can also be invoked
|
||
manually if you do not use the preferred @command{git send-email}
|
||
command to submit patches. To list the available actions of the script,
|
||
you can invoke it via the @command{etc/teams.scm help} command. For
|
||
more information regarding teams, see @xref{Teams}.
|
||
|
||
@unnumberedsubsubsec Multiple Patches
|
||
@anchor{Multiple Patches}
|
||
@cindex cover letter
|
||
While @command{git send-email} alone will suffice for a single
|
||
patch, an unfortunate flaw in Debbugs means you need to be more
|
||
careful when sending multiple patches: if you send them all to the
|
||
@email{guix-patches@@gnu.org} address, a new issue will be created
|
||
for each patch!
|
||
|
||
When sending a series of patches, it's best to send a Git ``cover
|
||
letter'' first, to give reviewers an overview of the patch series.
|
||
We can create a directory called @file{outgoing} containing both
|
||
our patch series and a cover letter called @file{0000-cover-letter.patch}
|
||
with @command{git format-patch}.
|
||
|
||
@example
|
||
$ git format-patch -@var{NUMBER_COMMITS} -o outgoing \
|
||
--cover-letter --base=auto
|
||
@end example
|
||
|
||
We can now send @emph{just} the cover letter to the
|
||
@email{guix-patches@@gnu.org} address, which will create an issue
|
||
that we can send the rest of the patches to.
|
||
|
||
@example
|
||
$ git send-email outgoing/0000-cover-letter.patch --annotate
|
||
$ rm outgoing/0000-cover-letter.patch # we don't want to resend it!
|
||
@end example
|
||
|
||
Ensure you edit the email to add an appropriate subject line and
|
||
blurb before sending it. Note the automatically generated shortlog
|
||
and diffstat below the blurb.
|
||
|
||
Once the Debbugs mailer has replied to your cover letter email, you
|
||
can send the actual patches to the newly-created issue address.
|
||
|
||
@example
|
||
$ git send-email outgoing/*.patch --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org
|
||
$ rm -rf outgoing # we don't need these anymore
|
||
@end example
|
||
|
||
Thankfully, this @command{git format-patch} dance is not necessary
|
||
to send an amended patch series, since an issue already exists for
|
||
the patchset.
|
||
|
||
@example
|
||
$ git send-email -@var{NUMBER_COMMITS} -v@var{REVISION} \
|
||
--to=@var{ISSUE_NUMBER}@@debbugs.gnu.org
|
||
@end example
|
||
|
||
If need be, you may use @option{--cover-letter --annotate} to send
|
||
another cover letter, e.g. for explaining what's changed since the last
|
||
revision, and these changes are necessary.
|
||
|
||
@node Teams
|
||
@subsection Teams
|
||
@cindex teams
|
||
|
||
There are several teams mentoring different parts of the Guix source
|
||
code. To list all those teams, you can run from a Guix checkout:
|
||
|
||
@example
|
||
$ ./etc/teams.scm list-teams
|
||
id: mentors
|
||
name: Mentors
|
||
description: A group of mentors who chaperone contributions by newcomers.
|
||
members:
|
||
+ Christopher Baines <mail@@cbaines.net>
|
||
+ Ricardo Wurmus <rekado@@elephly.net>
|
||
+ Mathieu Othacehe <othacehe@@gnu.org>
|
||
+ jgart <jgart@@dismail.de>
|
||
+ Ludovic Courtès <ludo@@gnu.org>
|
||
@dots{}
|
||
@end example
|
||
|
||
You can run the following command to have the @code{Mentors} team put in
|
||
CC of a patch series:
|
||
|
||
@example
|
||
$ git send-email --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org \
|
||
--header-cmd='etc/teams.scm cc-mentors-header-cmd' *.patch
|
||
@end example
|
||
|
||
The appropriate team or teams can also be inferred from the modified
|
||
files. For instance, if you want to send the two latest commits of the
|
||
current Git repository to review, you can run:
|
||
|
||
@example
|
||
$ guix shell -D guix
|
||
[env]$ git send-email --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org -2
|
||
@end example
|
||
|
||
@node Tracking Bugs and Changes
|
||
@section Tracking Bugs and Changes
|
||
|
||
This section describes how the Guix project tracks its bug reports,
|
||
patch submissions and topic branches.
|
||
|
||
@menu
|
||
* The Issue Tracker:: The official bug and patch tracker.
|
||
* Managing Patches and Branches:: How changes to Guix are managed.
|
||
* Debbugs User Interfaces:: Ways to interact with Debbugs.
|
||
* Debbugs Usertags:: Tag reports with custom labels.
|
||
@end menu
|
||
|
||
@node The Issue Tracker
|
||
@subsection The Issue Tracker
|
||
|
||
@cindex bug reports, tracking
|
||
@cindex patch submissions, tracking
|
||
@cindex issue tracking
|
||
@cindex Debbugs, issue tracking system
|
||
Bug reports and patch submissions are currently tracked using the
|
||
Debbugs instance at @uref{https://bugs.gnu.org}. Bug reports are filed
|
||
against the @code{guix} ``package'' (in Debbugs parlance), by sending
|
||
email to @email{bug-guix@@gnu.org}, while patch submissions are filed
|
||
against the @code{guix-patches} package by sending email to
|
||
@email{guix-patches@@gnu.org} (@pxref{Submitting Patches}).
|
||
|
||
@node Managing Patches and Branches
|
||
@subsection Managing Patches and Branches
|
||
@cindex branching strategy
|
||
@cindex rebuild scheduling strategy
|
||
|
||
Changes should be posted to @email{guix-patches@@gnu.org}. This mailing
|
||
list fills the patch-tracking database (@pxref{The Issue Tracker}). It
|
||
also allows patches to be picked up and tested by the quality assurance
|
||
tooling; the result of that testing eventually shows up on the dashboard
|
||
at @indicateurl{https://qa.guix.gnu.org/issue/@var{ISSUE_NUMBER}}, where
|
||
@var{ISSUE_NUMBER} is the number assigned by the issue tracker. Leave
|
||
time for a review, without committing anything.
|
||
|
||
As an exception, some changes considered ``trivial'' or ``obvious'' may
|
||
be pushed directly to the @code{master} branch. This includes changes
|
||
to fix typos and reverting commits that caused immediate problems. This
|
||
is subject to being adjusted, allowing individuals to commit directly on
|
||
non-controversial changes on parts they’re familiar with.
|
||
|
||
Changes which affect more than 300 dependent packages (@pxref{Invoking
|
||
guix refresh}) should first be pushed to a topic branch other than
|
||
@code{master}; the set of changes should be consistent---e.g., ``GNOME
|
||
update'', ``NumPy update'', etc. This allows for testing: the branch
|
||
will automatically show up at
|
||
@indicateurl{https://qa.guix.gnu.org/branch/@var{branch}}, with an
|
||
indication of its build status on various platforms.
|
||
|
||
@cindex feature branches, coordination
|
||
To help coordinate the merging of branches, you must create a new
|
||
guix-patches issue each time you wish to merge a branch (@pxref{The
|
||
Issue Tracker}). The title of the issue requesting to merge a branch
|
||
should have the following format:
|
||
|
||
@cindex merge requests, template
|
||
@example
|
||
Request for merging "@var{name}" branch
|
||
@end example
|
||
|
||
The @url{https://qa.guix.gnu.org/, QA infrastructure} recognizes such
|
||
issues and lists the merge requests on its main page. Normally branches
|
||
will be merged in a ``first come, first merged'' manner, tracked through
|
||
the guix-patches issues.
|
||
|
||
If you agree on a different order with those involved, you can track
|
||
this by updating which issues block@footnote{You can mark an issue as
|
||
blocked by another by emailing @email{control@@debbugs.gnu.org} with the
|
||
following line in the body of the email: @code{block XXXXX by YYYYY}.
|
||
Where @code{XXXXX} is the number for the blocked issue, and @code{YYYYY}
|
||
is the number for the issue blocking it.} which other issues.
|
||
Therefore, to know which branch is at the front of the queue, look for
|
||
the oldest issue, or the issue that isn't @dfn{blocked} by any other
|
||
branch merges. An ordered list of branches with the open issues is
|
||
available at @url{https://qa.guix.gnu.org}.
|
||
|
||
Once a branch is at the front of the queue, wait until sufficient time
|
||
has passed for the build farms to have processed the changes, and for
|
||
the necessary testing to have happened. For example, you can check
|
||
@indicateurl{https://qa.guix.gnu.org/branch/@var{branch}} to see
|
||
information on some builds and substitute availability.
|
||
|
||
@node Debbugs User Interfaces
|
||
@subsection Debbugs User Interfaces
|
||
|
||
@subsubsection Web interface
|
||
|
||
A web interface (actually @emph{two} web interfaces!) are available to
|
||
browse issues:
|
||
|
||
@itemize
|
||
@item
|
||
@url{https://issues.guix.gnu.org} provides a pleasant
|
||
interface@footnote{The web interface at
|
||
@url{https://issues.guix.gnu.org} is powered by Mumi, a nice piece of
|
||
software written in Guile, and you can help! See
|
||
@url{https://git.elephly.net/gitweb.cgi?p=software/mumi.git}.} to browse
|
||
bug reports and patches, and to participate in discussions;
|
||
@item
|
||
@url{https://bugs.gnu.org/guix} lists bug reports;
|
||
@item
|
||
@url{https://bugs.gnu.org/guix-patches} lists patch submissions.
|
||
@end itemize
|
||
|
||
To view discussions related to issue number @var{n}, go to
|
||
@indicateurl{https://issues.guix.gnu.org/@var{n}} or
|
||
@indicateurl{https://bugs.gnu.org/@var{n}}.
|
||
|
||
@subsubsection Command-line interface
|
||
|
||
Mumi also comes with a command-line interface that can be used to search
|
||
existing issues, open new issues and send patches. You do not need to
|
||
use Emacs to use the mumi command-line client. You interact with it
|
||
only on the command-line.
|
||
|
||
To use the mumi command-line interface, navigate to a local clone of the
|
||
Guix git repository, and drop into a shell with mumi, git and
|
||
git:send-email installed.
|
||
|
||
@example
|
||
$ cd guix
|
||
~/guix$ guix shell mumi git git:send-email
|
||
@end example
|
||
|
||
To search for issues, say all open issues about "zig", run
|
||
|
||
@example
|
||
~/guix [env]$ mumi search zig is:open
|
||
|
||
#60889 Add zig-build-system
|
||
opened on 17 Jan 17:37 Z by Ekaitz Zarraga
|
||
#61036 [PATCH 0/3] Update zig to 0.10.1
|
||
opened on 24 Jan 09:42 Z by Efraim Flashner
|
||
#39136 [PATCH] gnu: services: Add endlessh.
|
||
opened on 14 Jan 2020 21:21 by Nicol? Balzarotti
|
||
#60424 [PATCH] gnu: Add python-online-judge-tools
|
||
opened on 30 Dec 2022 07:03 by gemmaro
|
||
#45601 [PATCH 0/6] vlang 0.2 update
|
||
opened on 1 Jan 2021 19:23 by Ryan Prior
|
||
@end example
|
||
|
||
Pick an issue and make it the "current" issue.
|
||
|
||
@example
|
||
~/guix [env]$ mumi current 61036
|
||
|
||
#61036 [PATCH 0/3] Update zig to 0.10.1
|
||
opened on 24 Jan 09:42 Z by Efraim Flashner
|
||
@end example
|
||
|
||
Once an issue is the current issue, you can easily create and send
|
||
patches to it using
|
||
|
||
@example
|
||
~/guix [env]$ git format-patch origin/master
|
||
~/guix [env]$ mumi send-email foo.patch bar.patch
|
||
@end example
|
||
|
||
Note that you do not have to pass in @samp{--to} or @samp{--cc}
|
||
arguments to @command{git format-patch}. @command{mumi send-email} will
|
||
put them in correctly when sending the patches.
|
||
|
||
To open a new issue, run
|
||
|
||
@example
|
||
~/guix [env]$ mumi new
|
||
@end example
|
||
|
||
and send patches
|
||
|
||
@example
|
||
~/guix [env]$ mumi send-email foo.patch bar.patch
|
||
@end example
|
||
|
||
@command{mumi send-email} is really a wrapper around @command{git
|
||
send-email} that automates away all the nitty-gritty of sending patches.
|
||
It uses the current issue state to automatically figure out the correct
|
||
@samp{To} address to send to, other participants to @samp{Cc}, headers
|
||
to add, etc.
|
||
|
||
Also note that, unlike @command{git send-email}, @command{mumi
|
||
send-email} works perfectly well with single and multiple patches alike.
|
||
It automates away the debbugs dance of sending the first patch, waiting
|
||
for a response from debbugs and sending the remaining patches. It does
|
||
so by sending the first patch, polling the server for a response, and
|
||
then sending the remaining patches. This polling can unfortunately take
|
||
a few minutes. So, please be patient.
|
||
|
||
@subsubsection Emacs interface
|
||
|
||
If you use Emacs, you may find it more convenient to interact with
|
||
issues using @file{debbugs.el}, which you can install with:
|
||
|
||
@example
|
||
guix install emacs-debbugs
|
||
@end example
|
||
|
||
For example, to list all open issues on @code{guix-patches}, hit:
|
||
|
||
@example
|
||
@kbd{C-u} @kbd{M-x} debbugs-gnu @kbd{RET} @kbd{RET} guix-patches @kbd{RET} n y
|
||
@end example
|
||
|
||
@xref{Top,,, debbugs-ug, Debbugs User Guide}, for more information on
|
||
this nifty tool!
|
||
|
||
@node Debbugs Usertags
|
||
@subsection Debbugs Usertags
|
||
|
||
@cindex usertags, for debbugs
|
||
@cindex Debbugs usertags
|
||
Debbugs provides a feature called @dfn{usertags} that allows any user to
|
||
tag any bug with an arbitrary label. Bugs can be searched by usertag,
|
||
so this is a handy way to organize bugs@footnote{The list of usertags is
|
||
public information, and anyone can modify any user's list of usertags,
|
||
so keep that in mind if you choose to use this feature.}.
|
||
|
||
For example, to view all the bug reports (or patches, in the case of
|
||
@code{guix-patches}) tagged with the usertag @code{powerpc64le-linux}
|
||
for the user @code{guix}, open a URL like the following in a web
|
||
browser:
|
||
@url{https://debbugs.gnu.org/cgi-bin/pkgreport.cgi?tag=powerpc64le-linux;users=guix}.
|
||
|
||
For more information on how to use usertags, please refer to the
|
||
documentation for Debbugs or the documentation for whatever tool you use
|
||
to interact with Debbugs.
|
||
|
||
In Guix, we are experimenting with usertags to keep track of
|
||
architecture-specific issues. To facilitate collaboration, all our
|
||
usertags are associated with the single user @code{guix}. The following
|
||
usertags currently exist for that user:
|
||
|
||
@table @code
|
||
|
||
@item powerpc64le-linux
|
||
The purpose of this usertag is to make it easy to find the issues that
|
||
matter most for the @code{powerpc64le-linux} system type. Please assign
|
||
this usertag to bugs or patches that affect @code{powerpc64le-linux} but
|
||
not other system types. In addition, you may use it to identify issues
|
||
that for some reason are particularly important for the
|
||
@code{powerpc64le-linux} system type, even if the issue affects other
|
||
system types, too.
|
||
|
||
@item reproducibility
|
||
For issues related to reproducibility. For example, it would be
|
||
appropriate to assign this usertag to a bug report for a package that
|
||
fails to build reproducibly.
|
||
|
||
@end table
|
||
|
||
If you're a committer and you want to add a usertag, just start using it
|
||
with the @code{guix} user. If the usertag proves useful to you,
|
||
consider updating this section of the manual so that others will know
|
||
what your usertag means.
|
||
|
||
@node Commit Access
|
||
@section Commit Access
|
||
|
||
@cindex commit access, for developers
|
||
Everyone can contribute to Guix without having commit access
|
||
(@pxref{Submitting Patches}). However, for frequent contributors,
|
||
having write access to the repository can be convenient. As a rule of
|
||
thumb, a contributor should have accumulated fifty (50) reviewed commits
|
||
to be considered as a committer and have sustained their activity in the
|
||
project for at least 6 months. This ensures enough interactions with
|
||
the contributor, which is essential for mentoring and assessing whether
|
||
they are ready to become a committer. Commit access should not be
|
||
thought of as a ``badge of honor'' but rather as a responsibility a
|
||
contributor is willing to take to help the project. It is expected from
|
||
all contributors, and even more so from committers, to help build
|
||
consensus and make decisions based on consensus. To learn what
|
||
consensus decision making means and understand its finer details, you
|
||
are encouraged to read
|
||
@url{https://www.seedsforchange.org.uk/consensus}.
|
||
|
||
The following sections explain how to get commit access, how to be ready
|
||
to push commits, and the policies and community expectations for commits
|
||
pushed upstream.
|
||
|
||
@subsection Applying for Commit Access
|
||
|
||
When you deem it necessary, consider applying for commit
|
||
access by following these steps:
|
||
|
||
@enumerate
|
||
@item
|
||
Find three committers who would vouch for you. You can view the list of
|
||
committers at
|
||
@url{https://savannah.gnu.org/project/memberlist.php?group=guix}. Each
|
||
of them should email a statement to @email{guix-maintainers@@gnu.org} (a
|
||
private alias for the collective of maintainers), signed with their
|
||
OpenPGP key.
|
||
|
||
Committers are expected to have had some interactions with you as a
|
||
contributor and to be able to judge whether you are sufficiently
|
||
familiar with the project's practices. It is @emph{not} a judgment on
|
||
the value of your work, so a refusal should rather be interpreted as
|
||
``let's try again later''.
|
||
|
||
@item
|
||
Send @email{guix-maintainers@@gnu.org} a message stating your intent,
|
||
listing the three committers who support your application, signed with
|
||
the OpenPGP key you will use to sign commits, and giving its fingerprint
|
||
(see below). See @uref{https://emailselfdefense.fsf.org/en/}, for an
|
||
introduction to public-key cryptography with GnuPG.
|
||
|
||
@c See <https://sha-mbles.github.io/>.
|
||
Set up GnuPG such that it never uses the SHA1 hash algorithm for digital
|
||
signatures, which is known to be unsafe since 2019, for instance by
|
||
adding the following line to @file{~/.gnupg/gpg.conf} (@pxref{GPG
|
||
Esoteric Options,,, gnupg, The GNU Privacy Guard Manual}):
|
||
|
||
@example
|
||
digest-algo sha512
|
||
@end example
|
||
|
||
@item
|
||
Maintainers ultimately decide whether to grant you commit access,
|
||
usually following your referrals' recommendation.
|
||
|
||
@item
|
||
@cindex OpenPGP, signed commits
|
||
If and once you've been given access, please send a message to
|
||
@email{guix-devel@@gnu.org} to say so, again signed with the OpenPGP key
|
||
you will use to sign commits (do that before pushing your first commit).
|
||
That way, everyone can notice and ensure you control that OpenPGP key.
|
||
|
||
@quotation Important
|
||
Before you can push for the first time, maintainers must:
|
||
|
||
@enumerate
|
||
@item
|
||
add your OpenPGP key to the @code{keyring} branch;
|
||
@item
|
||
add your OpenPGP fingerprint to the @file{.guix-authorizations} file of
|
||
the branch(es) you will commit to.
|
||
@end enumerate
|
||
@end quotation
|
||
|
||
@item
|
||
Make sure to read the rest of this section and... profit!
|
||
@end enumerate
|
||
|
||
@quotation Note
|
||
Maintainers are happy to give commit access to people who have been
|
||
contributing for some time and have a track record---don't be shy and
|
||
don't underestimate your work!
|
||
|
||
However, note that the project is working towards a more automated patch
|
||
review and merging system, which, as a consequence, may lead us to have
|
||
fewer people with commit access to the main repository. Stay tuned!
|
||
@end quotation
|
||
|
||
All commits that are pushed to the central repository on Savannah must
|
||
be signed with an OpenPGP key, and the public key should be uploaded to
|
||
your user account on Savannah and to public key servers, such as
|
||
@code{keys.openpgp.org}. To configure Git to automatically sign
|
||
commits, run:
|
||
|
||
@example
|
||
git config commit.gpgsign true
|
||
|
||
# Substitute the fingerprint of your public PGP key.
|
||
git config user.signingkey CABBA6EA1DC0FF33
|
||
@end example
|
||
|
||
To check that commits are signed with correct key, use:
|
||
|
||
@example
|
||
make authenticate
|
||
@end example
|
||
|
||
To avoid accidentally pushing unsigned or signed with the wrong key
|
||
commits to Savannah, make sure to configure Git according to
|
||
@xref{Configuring Git}.
|
||
|
||
@subsection Commit Policy
|
||
|
||
If you get commit access, please make sure to follow the policy below
|
||
(discussions of the policy can take place on
|
||
@email{guix-devel@@gnu.org}).
|
||
|
||
Ensure you're aware of how the changes should be handled
|
||
(@pxref{Managing Patches and Branches}) prior to being pushed to the
|
||
repository, especially for the @code{master} branch.
|
||
|
||
If you're committing and pushing your own changes, try and wait at least
|
||
one week (two weeks for more significant changes) after you send them
|
||
for review. After this, if no one else is available to review them and
|
||
if you're confident about the changes, it's OK to commit.
|
||
|
||
When pushing a commit on behalf of somebody else, please add a
|
||
@code{Signed-off-by} line at the end of the commit log message---e.g.,
|
||
with @command{git am --signoff}. This improves tracking of who did
|
||
what.
|
||
|
||
When adding channel news entries (@pxref{Channels, Writing Channel
|
||
News}), make sure they are well-formed by running the following command
|
||
right before pushing:
|
||
|
||
@example
|
||
make check-channel-news
|
||
@end example
|
||
|
||
@subsection Addressing Issues
|
||
|
||
Peer review (@pxref{Submitting Patches}) and tools such as
|
||
@command{guix lint} (@pxref{Invoking guix lint}) and the test suite
|
||
(@pxref{Running the Test Suite}) should catch issues before they are
|
||
pushed. Yet, commits that ``break'' functionality might occasionally
|
||
go through. When that happens, there are two priorities: mitigating
|
||
the impact, and understanding what happened to reduce the chance of
|
||
similar incidents in the future. The responsibility for both these
|
||
things primarily lies with those involved, but like everything this is
|
||
a group effort.
|
||
|
||
Some issues can directly affect all users---for instance because they
|
||
make @command{guix pull} fail or break core functionality, because they
|
||
break major packages (at build time or run time), or because they
|
||
introduce known security vulnerabilities.
|
||
|
||
@cindex reverting commits
|
||
The people involved in authoring, reviewing, and pushing such
|
||
commit(s) should be at the forefront to mitigate their impact in a
|
||
timely fashion: by pushing a followup commit to fix it (if possible),
|
||
or by reverting it to leave time to come up with a proper fix, and by
|
||
communicating with other developers about the problem.
|
||
|
||
If these persons are unavailable to address the issue in time, other
|
||
committers are entitled to revert the commit(s), explaining in the
|
||
commit log and on the mailing list what the problem was, with the goal
|
||
of leaving time to the original committer, reviewer(s), and author(s)
|
||
to propose a way forward.
|
||
|
||
Once the problem has been dealt with, it is the responsibility of
|
||
those involved to make sure the situation is understood. If you are
|
||
working to understand what happened, focus on gathering information
|
||
and avoid assigning any blame. Do ask those involved to describe what
|
||
happened, do not ask them to explain the situation---this would
|
||
implicitly blame them, which is unhelpful. Accountability comes from
|
||
a consensus about the problem, learning from it and improving
|
||
processes so that it's less likely to reoccur.
|
||
|
||
@subsection Commit Revocation
|
||
|
||
In order to reduce the possibility of mistakes, committers will have
|
||
their Savannah account removed from the Guix Savannah project and their
|
||
key removed from @file{.guix-authorizations} after 12 months of
|
||
inactivity; they can ask to regain commit access by emailing the
|
||
maintainers, without going through the vouching process.
|
||
|
||
Maintainers@footnote{See @uref{https://guix.gnu.org/en/about} for the
|
||
current list of maintainers. You can email them privately at
|
||
@email{guix-maintainers@@gnu.org}.} may also revoke an individual's
|
||
commit rights, as a last resort, if cooperation with the rest of the
|
||
community has caused too much friction---even within the bounds of the
|
||
project's code of conduct (@pxref{Contributing}). They would only do so
|
||
after public or private discussion with the individual and a clear
|
||
notice. Examples of behavior that hinders cooperation and could lead to
|
||
such a decision include:
|
||
|
||
@itemize
|
||
@item repeated violation of the commit policy stated above;
|
||
@item repeated failure to take peer criticism into account;
|
||
@item breaching trust through a series of grave incidents.
|
||
@end itemize
|
||
|
||
When maintainers resort to such a decision, they notify developers on
|
||
@email{guix-devel@@gnu.org}; inquiries may be sent to
|
||
@email{guix-maintainers@@gnu.org}. Depending on the situation, the
|
||
individual may still be welcome to contribute.
|
||
|
||
@subsection Helping Out
|
||
|
||
One last thing: the project keeps moving forward because committers not
|
||
only push their own awesome changes, but also offer some of their time
|
||
@emph{reviewing} and pushing other people's changes. As a committer,
|
||
you're welcome to use your expertise and commit rights to help other
|
||
contributors, too!
|
||
|
||
@node Updating the Guix Package
|
||
@section Updating the Guix Package
|
||
|
||
@cindex update-guix-package, updating the guix package
|
||
It is sometimes desirable to update the @code{guix} package itself (the
|
||
package defined in @code{(gnu packages package-management)}), for
|
||
example to make new daemon features available for use by the
|
||
@code{guix-service-type} service type. In order to simplify this task,
|
||
the following command can be used:
|
||
|
||
@example
|
||
make update-guix-package
|
||
@end example
|
||
|
||
The @code{update-guix-package} make target will use the last known
|
||
@emph{commit} corresponding to @code{HEAD} in your Guix checkout,
|
||
compute the hash of the Guix sources corresponding to that commit and
|
||
update the @code{commit}, @code{revision} and hash of the @code{guix}
|
||
package definition.
|
||
|
||
To validate that the updated @code{guix} package hashes are correct and
|
||
that it can be built successfully, the following command can be run from
|
||
the directory of your Guix checkout:
|
||
|
||
@example
|
||
./pre-inst-env guix build guix
|
||
@end example
|
||
|
||
To guard against accidentally updating the @code{guix} package to a
|
||
commit that others can't refer to, a check is made that the commit used
|
||
has already been pushed to the Savannah-hosted Guix git repository.
|
||
|
||
This check can be disabled, @emph{at your own peril}, by setting the
|
||
@code{GUIX_ALLOW_ME_TO_USE_PRIVATE_COMMIT} environment variable. When
|
||
this variable is set, the updated package source is also added to the
|
||
store. This is used as part of the release process of Guix.
|
||
|
||
@cindex documentation
|
||
@node Writing Documentation
|
||
@section Writing Documentation
|
||
|
||
Guix is documented using the Texinfo system. If you are not yet
|
||
familiar with it, we accept contributions for documentation in most
|
||
formats. That includes plain text, Markdown, Org, etc.
|
||
|
||
Documentation contributions can be sent to
|
||
@email{guix-patches@@gnu.org}. Prepend @samp{[DOCUMENTATION]} to the
|
||
subject.
|
||
|
||
When you need to make more than a simple addition to the documentation,
|
||
we prefer that you send a proper patch as opposed to sending an email
|
||
as described above. @xref{Submitting Patches} for more information on
|
||
how to send your patches.
|
||
|
||
To modify the documentation, you need to edit @file{doc/guix.texi} and
|
||
@file{doc/contributing.texi} (which contains this documentation
|
||
section), or @file{doc/guix-cookbook.texi} for the cookbook. If
|
||
you compiled the Guix repository before, you will have
|
||
many more @file{.texi} files that are translations of these
|
||
documents. Do not modify them, the translation is managed through
|
||
@uref{https://translate.fedoraproject.org/projects/guix, Weblate}.
|
||
@xref{Translating Guix} for more information.
|
||
|
||
To render documentation, you must first make sure that you ran
|
||
@command{./configure} in your source tree (@pxref{Running Guix Before
|
||
It Is Installed}). After that you can run one of the following
|
||
commands:
|
||
|
||
@itemize
|
||
@item @samp{make doc/guix.info} to compile the Info manual.
|
||
You can check it with @command{info doc/guix.info}.
|
||
@item @samp{make doc/guix.html} to compile the HTML version.
|
||
You can point your browser to the relevant file in the
|
||
@file{doc/guix.html} directory.
|
||
@item @samp{make doc/guix-cookbook.info} for the cookbook Info manual.
|
||
@item @samp{make doc/guix-cookbook.html} for the cookbook HTML version.
|
||
@end itemize
|
||
|
||
@cindex translation
|
||
@cindex l10n
|
||
@cindex i18n
|
||
@cindex native language support
|
||
@node Translating Guix
|
||
@section Translating Guix
|
||
|
||
Writing code and packages is not the only way to provide a meaningful
|
||
contribution to Guix. Translating to a language you speak is another
|
||
example of a valuable contribution you can make. This section is designed
|
||
to describe the translation process. It gives you advice on how you can
|
||
get involved, what can be translated, what mistakes you should avoid and
|
||
what we can do to help you!
|
||
|
||
Guix is a big project that has multiple components that can be translated.
|
||
We coordinate the translation effort on a
|
||
@uref{https://translate.fedoraproject.org/projects/guix/,Weblate instance}
|
||
hosted by our friends at Fedora. You will need an account to submit
|
||
translations.
|
||
|
||
Some of the software packaged in Guix also contain translations. We do not
|
||
host a translation platform for them. If you want to translate a package
|
||
provided by Guix, you should contact their developers or find the information
|
||
on their website. As an example, you can find the homepage of the
|
||
@code{hello} package by typing @code{guix show hello}. On the ``homepage''
|
||
line, you will see @url{https://www.gnu.org/software/hello/} as the homepage.
|
||
|
||
Many GNU and non-GNU packages can be translated on the
|
||
@uref{https://translationproject.org,Translation Project}. Some projects
|
||
with multiple components have their own platform. For instance, GNOME has
|
||
its own platform, @uref{https://l10n.gnome.org/,Damned Lies}.
|
||
|
||
Guix has five components hosted on Weblate.
|
||
|
||
@itemize
|
||
@item @code{guix} contains all the strings from the Guix software (the
|
||
guided system installer, the package manager, etc), excluding packages.
|
||
@item @code{packages} contains the synopsis (single-sentence description
|
||
of a package) and description (longer description) of packages in Guix.
|
||
@item @code{website} contains the official Guix website, except for
|
||
blog posts and multimedia content.
|
||
@item @code{documentation-manual} corresponds to this manual.
|
||
@item @code{documentation-cookbook} is the component for the cookbook.
|
||
@end itemize
|
||
|
||
@subsubheading General Directions
|
||
|
||
Once you get an account, you should be able to select a component from
|
||
@uref{https://translate.fedoraproject.org/projects/guix/,the guix project},
|
||
and select a language. If your language does not appear in the list, go
|
||
to the bottom and click on the ``Start new translation'' button. Select
|
||
the language you want to translate to from the list, to start your new
|
||
translation.
|
||
|
||
Like lots of other free software packages, Guix uses
|
||
@uref{https://www.gnu.org/software/gettext,GNU Gettext} for its translations,
|
||
with which translatable strings are extracted from the source code to so-called
|
||
PO files.
|
||
|
||
Even though PO files are text files, changes should not be made with a text
|
||
editor but with PO editing software. Weblate integrates PO editing
|
||
functionality. Alternatively, translators can use any of various
|
||
free-software tools for filling in translations, of which
|
||
@uref{https://poedit.net/,Poedit} is one example, and (after logging in)
|
||
@uref{https://docs.weblate.org/en/latest/user/files.html,upload} the changed
|
||
file. There is also a special
|
||
@uref{https://www.emacswiki.org/emacs/PoMode,PO editing mode} for users of GNU
|
||
Emacs. Over time translators find out what software they are happy with and
|
||
what features they need.
|
||
|
||
On Weblate, you will find various links to the editor, that will show various
|
||
subsets (or all) of the strings. Have a look around and at the
|
||
@uref{https://docs.weblate.org/en/latest/,documentation} to familiarize
|
||
yourself with the platform.
|
||
|
||
@subsubheading Translation Components
|
||
|
||
In this section, we provide more detailed guidance on the translation
|
||
process, as well as details on what you should or should not do. When in
|
||
doubt, please contact us, we will be happy to help!
|
||
|
||
@table @asis
|
||
@item guix
|
||
Guix is written in the Guile programming language, and some strings contain
|
||
special formatting that is interpreted by Guile. These special formatting
|
||
should be highlighted by Weblate. They start with @code{~} followed by one
|
||
or more characters.
|
||
|
||
When printing the string, Guile replaces the special formatting symbols with
|
||
actual values. For instance, the string @samp{ambiguous package specification
|
||
`~a'} would be substituted to contain said package specification instead of
|
||
@code{~a}. To properly translate this string, you must keep the formatting
|
||
code in your translation, although you can place it where it makes sense in
|
||
your language. For instance, the French translation says @samp{spécification
|
||
du paquet « ~a » ambiguë} because the adjective needs to be placed in the
|
||
end of the sentence.
|
||
|
||
If there are multiple formatting symbols, make sure to respect the order.
|
||
Guile does not know in which order you intended the string to be read, so it
|
||
will substitute the symbols in the same order as the English sentence.
|
||
|
||
As an example, you cannot translate @samp{package '~a' has been superseded by
|
||
'~a'} by @samp{'~a' superseeds package '~a'}, because the meaning would be
|
||
reversed. If @var{foo} is superseded by @var{bar}, the translation would read
|
||
@samp{'foo' superseeds package 'bar'}. To work around this problem, it
|
||
is possible to use more advanced formatting to select a given piece of data,
|
||
instead of following the default English order. @xref{Formatted Output,,,
|
||
guile, GNU Guile Reference Manual}, for more information on formatting in Guile.
|
||
|
||
@item packages
|
||
|
||
Package descriptions occasionally contain Texinfo markup (@pxref{Synopses
|
||
and Descriptions}). Texinfo markup looks like @samp{@@code@{rm -rf@}},
|
||
@samp{@@emph@{important@}}, etc. When translating, please leave markup as is.
|
||
|
||
The characters after ``@@'' form the name of the markup, and the text between
|
||
``@{'' and ``@}'' is its content. In general, you should not translate the
|
||
content of markup like @code{@@code}, as it contains literal code that do not
|
||
change with language. You can translate the content of formatting markup such
|
||
as @code{@@emph}, @code{@@i}, @code{@@itemize}, @code{@@item}. However, do
|
||
not translate the name of the markup, or it will not be recognized. Do
|
||
not translate the word after @code{@@end}, it is the name of the markup that
|
||
is closed at this position (e.g.@: @code{@@itemize ... @@end itemize}).
|
||
|
||
@item documentation-manual and documentation-cookbook
|
||
|
||
The first step to ensure a successful translation of the manual is to find
|
||
and translate the following strings @emph{first}:
|
||
|
||
@itemize
|
||
@item @code{version.texi}: Translate this string as @code{version-xx.texi},
|
||
where @code{xx} is your language code (the one shown in the URL on
|
||
weblate).
|
||
@item @code{contributing.texi}: Translate this string as
|
||
@code{contributing.xx.texi}, where @code{xx} is the same language code.
|
||
@item @code{Top}: Do not translate this string, it is important for Texinfo.
|
||
If you translate it, the document will be empty (missing a Top node).
|
||
Please look for it, and register @code{Top} as its translation.
|
||
@end itemize
|
||
|
||
Translating these strings first ensure we can include your translation in
|
||
the guix repository without breaking the make process or the
|
||
@command{guix pull} machinery.
|
||
|
||
The manual and the cookbook both use Texinfo. As for @code{packages}, please
|
||
keep Texinfo markup as is. There are more possible markup types in the manual
|
||
than in the package descriptions. In general, do not translate the content
|
||
of @code{@@code}, @code{@@file}, @code{@@var}, @code{@@value}, etc. You
|
||
should translate the content of formatting markup such as @code{@@emph},
|
||
@code{@@i}, etc.
|
||
|
||
The manual contains sections that can be referred to by name by @code{@@ref},
|
||
@code{@@xref} and @code{@@pxref}. We have a mechanism in place so you do
|
||
not have to translate their content. If you keep the English title, we will
|
||
automatically replace it with your translation of that title. This ensures
|
||
that Texinfo will always be able to find the node. If you decide to change
|
||
the translation of the title, the references will automatically be updated
|
||
and you will not have to update them all yourself.
|
||
|
||
When translating references from the cookbook to the manual, you need to
|
||
replace the name of the manual and the name of the section. For instance,
|
||
to translate @code{@@pxref@{Defining Packages,,, guix, GNU Guix Reference
|
||
Manual@}}, you would replace @code{Defining Packages} with the title of that
|
||
section in the translated manual @emph{only} if that title is translated.
|
||
If the title is not translated in your language yet, do not translate it here,
|
||
or the link will be broken. Replace @code{guix} with @code{guix.xx} where
|
||
@code{xx} is your language code. @code{GNU Guix Reference Manual} is the
|
||
text of the link. You can translate it however you wish.
|
||
|
||
@item website
|
||
|
||
The website pages are written using SXML, an s-expression version of HTML,
|
||
the basic language of the web. We have a process to extract translatable
|
||
strings from the source, and replace complex s-expressions with a more familiar
|
||
XML markup, where each markup is numbered. Translators can arbitrarily change
|
||
the ordering, as in the following example.
|
||
|
||
@example
|
||
#. TRANSLATORS: Defining Packages is a section name
|
||
#. in the English (en) manual.
|
||
#: apps/base/templates/about.scm:64
|
||
msgid "Packages are <1>defined<1.1>en</1.1><1.2>Defining-Packages.html</1.2></1> as native <2>Guile</2> modules."
|
||
msgstr "Pakete werden als reine <2>Guile</2>-Module <1>definiert<1.1>de</1.1><1.2>Pakete-definieren.html</1.2></1>."
|
||
@end example
|
||
|
||
Note that you need to include the same markups. You cannot skip any.
|
||
@end table
|
||
|
||
In case you make a mistake, the component might fail to build properly with your
|
||
language, or even make guix pull fail. To prevent that, we have a process
|
||
in place to check the content of the files before pushing to our repository.
|
||
We will not be able to update the translation for your language in Guix, so
|
||
we will notify you (through weblate and/or by email) so you get a chance to
|
||
fix the issue.
|
||
|
||
@subsubheading Outside of Weblate
|
||
|
||
Currently, some parts of Guix cannot be translated on Weblate, help wanted!
|
||
|
||
@itemize
|
||
@item @command{guix pull} news can be translated in @file{news.scm}, but is not
|
||
available from Weblate. If you want to provide a translation, you
|
||
can prepare a patch as described above, or simply send us your
|
||
translation with the name of the news entry you translated and your
|
||
language. @xref{Writing Channel News}, for more information about
|
||
channel news.
|
||
@item Guix blog posts cannot currently be translated.
|
||
@item The installer script (for foreign distributions) is entirely in English.
|
||
@item Some of the libraries Guix uses cannot be translated or are translated
|
||
outside of the Guix project. Guile itself is not internationalized.
|
||
@item Other manuals linked from this manual or the cookbook might not be
|
||
translated.
|
||
@end itemize
|
||
|
||
@subsubheading Conditions for Inclusion
|
||
|
||
There are no conditions for adding new translations of the @code{guix} and
|
||
@code{guix-packages} components, other than they need at least one translated
|
||
string. New languages will be added to Guix as soon as possible. The
|
||
files may be removed if they fall out of sync and have no more translated
|
||
strings.
|
||
|
||
Given that the web site is dedicated to new users, we want its translation
|
||
to be as complete as possible before we include it in the language menu.
|
||
For a new language to be included, it needs to reach at least 80% completion.
|
||
When a language is included, it may be removed in the future if it stays
|
||
out of sync and falls below 60% completion.
|
||
|
||
The manual and cookbook are automatically added in the default compilation
|
||
target. Every time we synchronize translations, developers need to
|
||
recompile all the translated manuals and cookbooks. This is useless for what
|
||
is essentially the English manual or cookbook. Therefore, we will only
|
||
include a new language when it reaches 10% completion in the component.
|
||
When a language is included, it may be removed in the future if it stays
|
||
out of sync and falls below 5% completion.
|
||
|
||
@subsubheading Translation Infrastructure
|
||
|
||
Weblate is backed by a git repository from which it discovers new strings to
|
||
translate and pushes new and updated translations. Normally, it would be
|
||
enough to give it commit access to our repositories. However, we decided
|
||
to use a separate repository for two reasons. First, we would have to give
|
||
Weblate commit access and authorize its signing key, but we do not trust it
|
||
in the same way we trust guix developers, especially since we do not manage
|
||
the instance ourselves. Second, if translators mess something up, it can
|
||
break the generation of the website and/or guix pull for all our users,
|
||
independently of their language.
|
||
|
||
For these reasons, we use a dedicated repository to host translations, and we
|
||
synchronize it with our guix and artworks repositories after checking no issue
|
||
was introduced in the translation.
|
||
|
||
Developers can download the latest PO files from weblate in the Guix
|
||
repository by running the @command{make download-po} command. It will
|
||
automatically download the latest files from weblate, reformat them to a
|
||
canonical form, and check they do not contain issues. The manual needs to be
|
||
built again to check for additional issues that might crash Texinfo.
|
||
|
||
Before pushing new translation files, developers should add them to the
|
||
make machinery so the translations are actually available. The process
|
||
differs for the various components.
|
||
|
||
@itemize
|
||
@item New po files for the @code{guix} and @code{packages} components must
|
||
be registered by adding the new language to @file{po/guix/LINGUAS} or
|
||
@file{po/packages/LINGUAS}.
|
||
@item New po files for the @code{documentation-manual} component must be
|
||
registered by adding the file name to @code{DOC_PO_FILES} in
|
||
@file{po/doc/local.mk}, the generated @file{%D%/guix.xx.texi} manual to
|
||
@code{info_TEXINFOS} in @file{doc/local.mk} and the generated
|
||
@file{%D%/guix.xx.texi} and @file{%D%/contributing.xx.texi} to
|
||
@code{TRANSLATED_INFO} also in @file{doc/local.mk}.
|
||
@item New po files for the @code{documentation-cookbook} component must be
|
||
registered by adding the file name to @code{DOC_COOKBOOK_PO_FILES} in
|
||
@file{po/doc/local.mk}, the generated @file{%D%/guix-cookbook.xx.texi}
|
||
manual to @code{info_TEXINFOS} in @file{doc/local.mk} and the generated
|
||
@file{%D%/guix-cookbook.xx.texi} to @code{TRANSLATED_INFO} also
|
||
in @file{doc/local.mk}.
|
||
@item New po files for the @code{website} component must be added to the
|
||
@code{guix-artwork} repository, in @file{website/po/}.
|
||
@file{website/po/LINGUAS} and @file{website/po/ietf-tags.scm} must
|
||
be updated accordingly (see @file{website/i18n-howto.txt} for more
|
||
information on the process).
|
||
@end itemize
|