@node Zapojiť sa
@chapter Zapojiť sa

Tento projekt je výsledkom spoločného úsilia a potrebujeme vašu pomoc pri
jeho rozširovaní! Spojte sa s nami prostredníctvom
@email{guix-devel@@gnu.org} alebo @code{#guix} na sieti IRC Freenode.  Radi
privítame vaše nápady, hlásenia chýb, záplaty a čokoľvek čo môže projektu
pomôcť.  Zvlášť radi privítame vašu pomoc s pridávaním balíkov
(@pxref{Zásady pridávania balíkov}).

@cindex zásady správania, prispievateľov
@cindex záväzok prispievateľa
Chceme vám poskytnúť príjemné a priateľské prostredie bez obťažovania, aby
sa každý mohol zapojiť najlepšie ako vie.  Preto sa náš projekt riadi
„záväzkom prispievateľa“ založeným na
@url{https://contributor-covenant.org/}.  Úplné znenie záväzku nájdete v
súbore @file{CODE-OF-CONDUCT} v strome zdrojových súborov.

Prispievatelia nemusia používať ich ozajstné meno v záplatách a online
dokumentácii; môžu používať ľubovoľné meno alebo prezývku.

@menu
* Zostavenie z Gitu::        Vždy ten najnovší.
* Spúšťanie Guixu ešte pred inštaláciou::  Finty pre hackerov.
* Dokonalé nastavenie::     Správne nástroje.
* Zásady pridávania balíkov::  Rast distribúcie.
* Štýl kódovania::        Návyky prispievateľa.
* Odovzdávanie záplat::    Zdieľajte vašu prácu.
* Sledovanie chýb a záplat::  Používanie Debbugs.
* Právo na úpravu::        Odosielanie úprav do oficiálneho repozitára.
* Aktualizácia balíka Guix::  Aktualizovať zadanie balíka Guix.
@end menu

@node Zostavenie z Gitu
@section Zostavenie z Gitu

Ak chcete pracovať na Guixe samotnom, odporúčame vám použiť najnovšiu verziu
z Git repozitára:

@example
git clone https://git.savannah.gnu.org/git/guix.git
@end example

@cindex overenie, miestneho Git repozitára Guixu
Ako sa uistíte, že ste získali pravú kópiu repozitára? Spustite
@command{guix git authenticate} a ako parametre použite číslo úpravy
(commit) a OpenPGP odtlačok @dfn{úvodu kanála} (@pxref{Invoking guix git
authenticate}):

@c ===========================================================================
@c
@c This file was generated with po4a. Translate the source file.
@c
@c ===========================================================================

@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
Tento príkaz má v prípade úspešného ukončenia nulovú návratovú hodnotu; v
opačnom prípade zobrazí chybové hlásenie a vráti nenulovú hodnotu.

Ako vidíte, je to rovnaký problém ako v prípade sliepky a vajca: najprv
musíte mať nainštalovaný Guix.  Obyčajne by ste si nainštalovali Guix ako
samostatný systém (@pxref{System Installation}) alebo ako doplnkového
správcu balíkov na inej distribúcii (@pxref{Binary Installation}); v každom
prípade by ste si overili OpenPGP podpis na inštalačnom nosiči.  Toto
predstavuje začiatok reťazca dôvery.

Najjednoduchší spôsob nastavenia vývojového prostredia pre Guix je
samozrejme s použitím Guixu! Nasledovný príkaz spustí nový shell so všetkými
závislosťami a premennými prostrediami potrebnými na prácu s Guixom:

@example
guix environment guix --pure
@end example

@xref{Invoking guix environment}, pre viac podrobností o tomto príkaze.

Ak nemáte možnosť použiť Guix na zostavenie Guixu zo zdrojových súborov,
budete ešte okrem balíkov spomenutých v návode na inštaláciu
(@pxref{Requirements}) potrebovať aj nasledovné balíky.

@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 (nepovinné)}.
@end itemize

S Guixom môžete pridať dodatočné závislosti pomocou príkazu @command{guix
environment} s prepínačom @option{--ad-hoc}:

@example
guix environment guix --pure --ad-hoc help2man git strace
@end example

Spustite @command{./bootstrap} pre vytvorenie kostry zostavovacieho systému
pomocou nástrojov Autoconf a Automake.  V prípade chyby ako je táto:

@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 @command{./configure} as usual.  Make sure to pass
@code{--localstatedir=@var{directory}} where @var{directory} is the
@code{localstatedir} value used by your current installation (@pxref{The
Store}, for information about this), usually @file{/var}.  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 have to invoke @code{make && make check} to build Guix and run
the tests (@pxref{Running the Test Suite}).  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


@node Spúšťanie Guixu ešte pred inštaláciou
@section Spúšťanie Guixu ešte pred inštaláciou

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{Zostavenie z Gitu}), 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 Guile Interactively,,, guile, Guile
Reference Manual}):

@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.


@node Dokonalé nastavenie
@section Dokonalé nastavenie

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 package -i emacs guile emacs-geiser
@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 Zásady pridávania balíkov
@section Zásady pridávania balíkov

@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{Spúšťanie Guixu ešte pred inštaláciou}):

@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{Odovzdávanie záplat}).  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{@value{SUBSTITUTE-URL}, 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}}
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.
* 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).  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

@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 package
--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{Odovzdávanie záplat, @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 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 Štýl kódovania
@section Štýl kódovania

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
./etc/indent-code.el gnu/packages/@var{file}.scm @var{package}
@end example

@noindent
This automatically indents the definition of @var{package} in
@file{gnu/packages/@var{file}.scm} by running Emacs in batch mode.  To
indent a whole file, omit the second argument:

@example
./etc/indent-code.el gnu/services/@var{file}.scm
@end example

@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 Odovzdávanie záplat
@section Odovzdávanie záplat

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.  Seasoned Guix
developers may also want to look at the section on commit access
(@pxref{Právo na úpravu}).

This mailing list is backed by a Debbugs instance, which allows us to keep
track of submissions (@pxref{Sledovanie chýb a záplat}).  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
@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
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 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, aarch64, or mips64 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 package (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}).

@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.
@end table

All these branches are @uref{@value{SUBSTITUTE-URL}, 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.

@c TODO: It would be good with badges on the website that tracks these
@c branches.  Or maybe even a status page.
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.

@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}} 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 the
@command{etc/indent-code.el} 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{Zostavenie z Gitu}) 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.

When a bug is resolved, please close the thread by sending an email to
@email{@var{NNN}-done@@debbugs.gnu.org}.

@unnumberedsubsec Sending a Patch Series
@anchor{Sending a Patch Series}
@cindex patch series
@cindex @code{git send-email}
@cindex @code{git-send-email}

@c Debbugs bug: https://debbugs.gnu.org/db/15/15361.html
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}.

@node Sledovanie chýb a záplat
@section Sledovanie chýb a záplat

@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{Odovzdávanie záplat}).

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 Právo na úpravu
@section Právo na úpravu

@cindex commit access, for developers
For frequent contributors, having write access to the repository is
convenient.  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

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{Sledovanie chýb a záplat}).

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}.

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
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 called located at
@file{etc/git/pre-push}:

@example
cp etc/git/pre-push .git/hooks/pre-push
@end example

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{Odovzdávanie záplat}).  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.

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.

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 Aktualizácia balíka Guix
@section Aktualizácia balíka Guix

@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.
