2107 lines
87 KiB
Plaintext
2107 lines
87 KiB
Plaintext
@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.
|
||
* Packaging Guidelines:: Growing the distribution.
|
||
* Coding Style:: Hygiene of the contributor.
|
||
* Submitting Patches:: Share your work.
|
||
* Tracking Bugs and Patches:: 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
|
||
|
||
@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
|
||
@end example
|
||
|
||
@noindent
|
||
... where @file{/var} is the normal @code{localstatedir} value
|
||
(@pxref{The Store}, for information about this). 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}.
|
||
|
||
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; it
|
||
is generated by running @command{./bootstrap} followed by
|
||
@command{./configure}). 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}). For
|
||
convenient Guix development, make sure to augment Guile’s load path so
|
||
that it finds source files from your checkout:
|
||
|
||
@lisp
|
||
;; @r{Assuming the Guix checkout is in ~/src/guix.}
|
||
(with-eval-after-load 'geiser-guile
|
||
(add-to-list 'geiser-guile-load-path "~/src/guix"))
|
||
@end lisp
|
||
|
||
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 with @url{https://joaotavora.github.io/yasnippet/, YASnippet} to
|
||
expand short trigger strings to interactive text snippets. You may want
|
||
to add the snippets directory to the @var{yas-snippet-dirs} variable in
|
||
Emacs.
|
||
|
||
@lisp
|
||
;; @r{Assuming the Guix checkout is in ~/src/guix.}
|
||
(with-eval-after-load 'yasnippet
|
||
(add-to-list 'yas-snippet-dirs "~/src/guix/etc/snippets"))
|
||
@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.
|
||
|
||
@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.
|
||
* 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 {Scheme 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 {Scheme 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 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}. Packages should be added when they are necessary;
|
||
we don't add Python 2 variants of the package unless we are going to use
|
||
them.
|
||
|
||
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.
|
||
|
||
@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{setup.py} file, in @file{requirements.txt}, or in @file{tox.ini}.
|
||
|
||
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 2 with @code{setuptools} and @code{pip}
|
||
installed like Python 3.4 has per default. Thus you don't need to
|
||
specify either of these as an input. @command{guix lint} will warn you
|
||
if you do.
|
||
|
||
@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 with
|
||
the @code{setup_requires} keyword in @file{setup.py}---or only for
|
||
testing---e.g., those in @code{tests_require}---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 {Scheme 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 {Scheme 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 {Scheme 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 {Scheme 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.
|
||
|
||
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}).
|
||
|
||
@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.
|
||
|
||
@cindex Vim, Scheme code editing
|
||
If you are editing code with Vim, we recommend that you run @code{:set
|
||
autoindent} so that your code is automatically indented as you type.
|
||
Additionally,
|
||
@uref{https://www.vim.org/scripts/script.php?script_id=3998,
|
||
@code{paredit.vim}} may help you deal with all these parentheses.
|
||
|
||
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 Patches}). 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{NNN}@@debbugs.gnu.org}, where @var{NNN} 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.
|
||
|
||
Before submitting a patch that adds or modifies a package definition,
|
||
please run through this check list:
|
||
|
||
@enumerate
|
||
@cindex @code{git format-patch}
|
||
@cindex @code{git-format-patch}
|
||
@item
|
||
When generating your patches with @code{git format-patch} or @code{git
|
||
send-email}, we recommend using the option @code{--base=}, perhaps with
|
||
the value @code{auto}. This option adds a note to the patch stating
|
||
which commit the patch is based on. This helps reviewers understand how
|
||
to apply and review your patches.
|
||
|
||
@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
|
||
the @code{texlive-tiny} package or @code{texlive-union} procedure instead.
|
||
|
||
@item
|
||
For important changes, 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}).
|
||
|
||
@c See <https://lists.gnu.org/archive/html/guix-devel/2016-10/msg00933.html>.
|
||
@cindex branching strategy
|
||
@cindex rebuild scheduling strategy
|
||
Depending on the number of dependent packages and thus the amount of
|
||
rebuilding induced, commits go to different branches, along these lines:
|
||
|
||
@table @asis
|
||
@item 300 dependent packages or less
|
||
@code{master} branch (non-disruptive changes).
|
||
|
||
@item between 300 and 1,800 dependent packages
|
||
@code{staging} branch (non-disruptive changes). This branch is intended
|
||
to be merged in @code{master} every 6 weeks or so. Topical changes
|
||
(e.g., an update of the GNOME stack) can instead go to a specific branch
|
||
(say, @code{gnome-updates}). This branch is not expected to be
|
||
buildable or usable until late in its development process.
|
||
|
||
@item more than 1,800 dependent packages
|
||
@code{core-updates} branch (may include major and potentially disruptive
|
||
changes). This branch is intended to be merged in @code{master} every
|
||
6 months or so. This branch is not expected to be buildable or usable
|
||
until late in its development process.
|
||
@end table
|
||
|
||
All these branches are @uref{https://@value{SUBSTITUTE-SERVER-1},
|
||
tracked by our build farm} and merged into @code{master} once
|
||
everything has been successfully built. This allows us to fix issues
|
||
before they hit users, and to reduce the window during which pre-built
|
||
binaries are not available.
|
||
|
||
When we decide to start building the @code{staging} or
|
||
@code{core-updates} branches, they will be forked and renamed with the
|
||
suffix @code{-frozen}, at which time only bug fixes may be pushed to the
|
||
frozen branches. The @code{core-updates} and @code{staging} branches
|
||
will remain open to accept patches for the next cycle. Please ask on
|
||
the mailing list or IRC if unsure where to place a patch.
|
||
@c TODO: It would be good with badges on the website that tracks these
|
||
@c branches. Or maybe even a status page.
|
||
|
||
@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{NNN}-done@@debbugs.gnu.org}.
|
||
|
||
@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}.
|
||
|
||
We provide some default settings in @file{etc/git/gitconfig} which
|
||
modify how patches are generated, making them easier to read and apply.
|
||
These settings can be applied by manually copying them to
|
||
@file{.git/config} in your checkout, or by telling Git to include the
|
||
whole file:
|
||
|
||
@example
|
||
git config --local include.path ../etc/git/gitconfig
|
||
@end example
|
||
|
||
From then on, any changes to @file{etc/git/gitconfig} would
|
||
automatically take effect.
|
||
|
||
Since the first patch in a series must be sent separately
|
||
(@pxref{Sending a Patch Series}), it can also be helpful to tell
|
||
@command{git format-patch} to handle the e-mail threading instead of
|
||
@command{git send-email}:
|
||
|
||
@example
|
||
git config --local format.thread shallow
|
||
git config --local sendemail.thread no
|
||
@end example
|
||
|
||
@unnumberedsubsec Sending a Patch Series
|
||
@anchor{Sending a Patch Series}
|
||
@cindex patch series
|
||
@cindex @code{git send-email}
|
||
|
||
When sending a patch series (e.g., using @code{git send-email}), please
|
||
first send one message to @email{guix-patches@@gnu.org}, and then send
|
||
subsequent patches to @email{@var{NNN}@@debbugs.gnu.org} to make sure
|
||
they are kept together. See
|
||
@uref{https://debbugs.gnu.org/Advanced.html, the Debbugs documentation}
|
||
for more information. You can install @command{git send-email} with
|
||
@command{guix install git:send-email}.
|
||
@c Debbugs bug: https://debbugs.gnu.org/db/15/15361.html
|
||
|
||
@node Tracking Bugs and Patches
|
||
@section Tracking Bugs and Patches
|
||
|
||
This section describes how the Guix project tracks its bug reports and
|
||
patch submissions.
|
||
|
||
@menu
|
||
* The Issue Tracker:: The official bug and patch tracker.
|
||
* 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 Debbugs User Interfaces
|
||
@subsection Debbugs User Interfaces
|
||
|
||
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}}.
|
||
|
||
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.
|
||
|
||
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
|
||
|
||
You can prevent yourself from accidentally pushing unsigned commits to
|
||
Savannah by using the pre-push Git hook located at
|
||
@file{etc/git/pre-push}:
|
||
|
||
@example
|
||
cp etc/git/pre-push .git/hooks/pre-push
|
||
@end example
|
||
|
||
@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}).
|
||
|
||
Non-trivial patches should always be posted to
|
||
@email{guix-patches@@gnu.org} (trivial patches include fixing typos,
|
||
etc.). This mailing list fills the patch-tracking database
|
||
(@pxref{Tracking Bugs and Patches}).
|
||
|
||
For patches that just add a new package, and a simple one, it's OK to
|
||
commit, if you're confident (which means you successfully built it in a
|
||
chroot setup, and have done a reasonable copyright and license
|
||
auditing). Likewise for package upgrades, except upgrades that trigger
|
||
a lot of rebuilds (for example, upgrading GnuTLS or GLib). We have a
|
||
mailing list for commit notifications (@email{guix-commits@@gnu.org}),
|
||
so people can notice. Before pushing your changes, make sure to run
|
||
@code{git pull --rebase}.
|
||
|
||
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
|
||
|
||
For anything else, please post to @email{guix-patches@@gnu.org} and
|
||
leave time for a review, without committing anything (@pxref{Submitting
|
||
Patches}). If you didn’t receive any reply after two weeks, and if
|
||
you're confident, it's OK to commit.
|
||
|
||
That last part is subject to being adjusted, allowing individuals to commit
|
||
directly on non-controversial changes on parts they’re familiar with.
|
||
|
||
@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
|