Contributing
************

This project is a cooperative effort, and we need your help to make it grow!  Please get in touch with us on guix-devel@gnu.org and #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 (see Packaging Guidelines).

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 https://contributor-covenant.org/.  You can find a local version in the 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.

Building from Git
=================

If you want to hack Guix itself, it is recommended to use the latest version from the Git repository:

     git clone https://git.savannah.gnu.org/git/guix.git

How do you ensure that you obtained a genuine copy of the repository? To do that, run guix git authenticate, passing it the commit and OpenPGP fingerprint of the channel introduction (see Invoking guix git authenticate):

     git fetch origin keyring:keyring
     guix git authenticate 9edb3f66fd807b096b48283debdcddccfea34bad \
       "BBB0 2DDF 2CEA F6A8 0D1D  E643 A2A0 6DF2 A33A 54FA"

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 (see System Installation) or Guix on top of another distro (see 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:

     guix shell -D guix --pure

See 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 (see Requirements).

  * GNU Autoconf (https://gnu.org/software/autoconf/);

  * GNU Automake (https://gnu.org/software/automake/);

  * GNU Gettext (https://gnu.org/software/gettext/);

  * GNU Texinfo (https://gnu.org/software/texinfo/);

  * Graphviz (https://www.graphviz.org/);

  * GNU Help2man (optional) (https://www.gnu.org/software/help2man/).

On Guix, extra dependencies can be added by instead running guix shell:

     guix shell -D guix help2man git strace --pure

From there you can generate the build system infrastructure using Autoconf and Automake:

     ./bootstrap

If you get an error like this one:

     configure.ac:46: error: possibly undefined macro: PKG_CHECK_MODULES

it probably means that Autoconf couldn’t find pkg.m4, which is provided by pkg-config.  Make sure that pkg.m4 is available.  The same holds for the guile.m4 set of macros provided by Guile.  For instance, if you installed Automake in /usr/local, it wouldn’t look for .m4 files in /usr/share.  In that case, you have to invoke the following command:

     export ACLOCAL_PATH=/usr/share/aclocal

See Macro Search Path (The GNU Automake Manual), for more information.

Then, run:

     ./configure --localstatedir=/var

... where /var is the normal localstatedir value (see The Store, for information about this).  Note that you will probably not run make install at the end (you don't have to) but it's still important to pass the right localstatedir.

Finally, you can build Guix and, if you feel so inclined, run the tests (see Running the Test Suite):

     make
     make check

If anything fails, take a look at installation instructions (see Installation) or send a message to the mailing list.

From there on, you can authenticate all the commits included in your checkout by running:

     make authenticate

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 keyring branch through the variable GUIX_GIT_KEYRING.  The following example assumes that you have a Git remote called myremote pointing to the official repository:

     make authenticate GUIX_GIT_KEYRING=myremote/keyring

     You are advised to run make authenticate after every git pull invocation.  This ensures you keep receiving valid changes to the repository.

After updating the repository, make might fail with an error similar to the following 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

This means that one of the record types that Guix defines (in this example, the origin record) has changed, and all of guix needs to be recompiled to take that change into account.  To do so, run make clean-go followed by make.

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 make install.  To do that, you first need to have an environment with all the dependencies available (see Building from Git), and then simply prefix each command with ./pre-inst-env (the pre-inst-env script lives in the top build tree of Guix; it is generated by running ./bootstrap followed by ./configure).  As an example, here is how you would build the hello package as defined in your working tree (this assumes guix-daemon is already running on your system; it's OK if it's a different version):

     $ ./pre-inst-env guix build hello

Similarly, an example for a Guile session using the Guix modules:

     $ ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))'

     ;;; ("x86_64-linux")

... and for a REPL (see Using Guix Interactively):

     $ ./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

If you are hacking on the daemon and its supporting code or if guix-daemon is not already running on your system, you can launch it straight from the build tree (The -E flag to sudo guarantees that GUILE_LOAD_PATH is correctly set such that guix-daemon and the tools it uses can find the Guile modules they need.):

     $ sudo -E ./pre-inst-env guix-daemon --build-users-group=guixbuild

The pre-inst-env script sets up all the environment variables necessary to support this, including PATH and GUILE_LOAD_PATH.

Note that ./pre-inst-env guix pull does not upgrade the local source tree; it simply updates the ~/.config/guix/current symlink (see Invoking guix pull).  Run git pull instead if you want to upgrade your local source tree.

Sometimes, especially if you have recently updated your repository, running ./pre-inst-env will print a message similar to the following example:

     ;;; note: source file /home/user/projects/guix/guix/progress.scm
     ;;;       newer than compiled /home/user/projects/guix/guix/progress.go

This is only a note and you can safely ignore it.  You can get rid of the message by running make -j4.  Until you do, Guile will run slightly slower because it will interpret the code instead of using prepared Guile object (.go) files.

You can run make automatically as you work using watchexec from the watchexec package.  For example, to build again each time you update a package file, run watchexec -w gnu/packages -- make -j4.

The Perfect Setup
=================

The Perfect Setup to hack on Guix is basically the perfect setup used for Guile hacking (see Using Guile in Emacs (Guile Reference Manual)).  First, you need more than an editor, you need Emacs (https://www.gnu.org/software/emacs), empowered by the wonderful Geiser (https://nongnu.org/geiser/).  To set that up, run:

     guix install emacs guile emacs-geiser emacs-geiser-guile

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, M-. to jump to an object definition, a REPL to try out your code, and more (see Introduction (Geiser User Manual)).  For convenient Guix development, make sure to augment Guile’s load path so that it finds source files from your checkout:

     ;; Assuming the Guix checkout is in ~/src/guix.
     (with-eval-after-load 'geiser-guile
       (add-to-list 'geiser-guile-load-path "~/src/guix"))

To actually edit the code, Emacs already has a neat Scheme mode.  But in addition to that, you must not miss Paredit (https://www.emacswiki.org/emacs/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.

We also provide templates for common git commit messages and package definitions in the etc/snippets directory.  These templates can be used to expand short trigger strings to interactive text snippets. If you use YASnippet (https://joaotavora.github.io/yasnippet/), you may want to add the etc/snippets/yas snippets directory to the YAS-SNIPPET-DIRS variable.  If you use Tempel (https://github.com/minad/tempel/), you may want to add the etc/snippets/tempel/* path to the TEMPEL-PATH variable in Emacs.

     ;; Assuming the Guix checkout is in ~/src/guix.
     ;; Yasnippet configuration
     (with-eval-after-load 'yasnippet
       (add-to-list 'yas-snippet-dirs "~/src/guix/etc/snippets/yas"))
     ;; Tempel configuration
     (with-eval-after-load 'tempel
        ;; Ensure tempel-path is a list -- it may also be a string.
        (unless (listp 'tempel-path)
          (setq tempel-path (list tempel-path)))
        (add-to-list 'tempel-path "~/src/guix/etc/snippets/tempel/*"))

The commit message snippets depend on Magit (https://magit.vc/) to display staged files.  When editing a commit message type add followed by TAB to insert a commit message template for adding a package; type update followed by TAB to insert a template for updating a package; type https followed by TAB to insert a template for changing the home page URI of a package to HTTPS.

The main snippet for scheme-mode is triggered by typing package... followed by TAB.  This snippet also inserts the trigger string origin..., which can be expanded further.  The origin snippet in turn may insert other trigger strings ending on ..., which also can be expanded further.

We additionally provide insertion and automatic update of a copyright in etc/copyright.el.  You may want to set your full name, mail, and load a file.

     (setq user-full-name "Alice Doe")
     (setq user-mail-address "alice@mail.org")
     ;; Assuming the Guix checkout is in ~/src/guix.
     (load-file "~/src/guix/etc/copyright.el")

To insert a copyright at the current line invoke M-x guix-copyright.

To update a copyright you need to specify a copyright-names-regexp.

     (setq copyright-names-regexp
           (format "%s <%s>" user-full-name user-mail-address))

You can check if your copyright is up to date by evaluating M-x copyright-update.  If you want to do it automatically after each buffer save then add (add-hook 'after-save-hook 'copyright-update) in Emacs.

Packaging Guidelines
====================

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 source code tarballs---typically tar.gz files that contain all the source files.  Adding a package to the distribution means essentially two things: adding a recipe that describes how to build the package, including a list of other packages required to build it, and adding package metadata along with that recipe, such as a description and licensing information.

In Guix all this information is embodied in 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 (see Package Modules). However, in-depth Scheme knowledge is not a prerequisite for creating packages.  For more information on package definitions, see Defining Packages.

Once a package definition is in place, stored in a file in the Guix source tree, it can be tested using the guix build command (see Invoking guix build).  For example, assuming the new package is called gnew, you may run this command from the Guix build tree (see Running Guix Before It Is Installed):

     ./pre-inst-env guix build gnew --keep-failed

Using --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 --log-file, to access the build log.

If the package is unknown to the guix command, it may be that the source file contains a syntax error, or lacks a 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:

     ./pre-inst-env guile -c '(use-modules (gnu packages gnew))'

Once your package builds correctly, please send us a patch (see 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 our continuous integration system (https://SUBSTITUTE-SERVER-1).

Users can obtain the new package definition simply by running guix pull (see Invoking guix pull).  When SUBSTITUTE-SERVER-1 is done building the package, installing the package automatically downloads binaries from there (see Substitutes).  The only place where human intervention is needed is to review and apply the patch.

Software Freedom
----------------

The GNU operating system has been developed so that users can have freedom in their computing.  GNU is free software, meaning that users have the four essential freedoms (https://www.gnu.org/philosophy/free-sw.html): 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 free software distribution guidelines (https://www.gnu.org/distros/free-system-distribution-guidelines.html).  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 origin form of the package (see Defining Packages).  This way, guix build --source returns the ``freed'' source rather than the unmodified upstream source.

Package Naming
--------------

A package actually has two names associated with it. First, there is the name of the Scheme variable, the one following 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 name field of a package definition.  This name is used by package management commands such as guix package and 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 gnunet, and SDL_net as 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 s-shell and not s.  Feel free to ask your fellow hackers for inspiration.

We do not add lib prefixes for library packages, unless these are already part of the official project name.  But see Python Modules and Perl Modules for special rules concerning modules for the Python and Perl languages.

Font package names are handled differently, see Fonts.

Version Numbers
---------------

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 Package Naming for the most recent version; previous versions use the same name, suffixed by - 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:

     (define-public gtk+
       (package
         (name "gtk+")
         (version "3.9.12")
         ...))
     (define-public gtk+-2
       (package
         (name "gtk+")
         (version "2.24.20")
         ...))

If we also wanted GTK+ 3.8.2, this would be packaged as

     (define-public gtk+-3.8
       (package
         (name "gtk+")
         (version "3.8.2")
         ...))

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 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 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:

     2.0.11-3.cabba9e
       ^    ^    ^
       |    |    `-- upstream commit ID
       |    |
       |    `--- Guix package revision
       |
     latest upstream version

It is a good idea to strip commit identifiers in the 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 git-fetch or hg-fetch (see below).  It is best to use the full commit identifiers in origins, though, to avoid ambiguities. A typical package definition may look like this:

     (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..."))
                     (file-name (git-file-name name version))))
           ;; ...
           )))

 -- Scheme Procedure: git-version VERSION REVISION COMMIT
     Return the version string for packages using git-fetch.

          (git-version "0.2.3" "0" "93818c936ee7e2f1ba1b315578bde363a7d43d05")
          => "0.2.3-0.93818c9"

 -- Scheme Procedure: hg-version VERSION REVISION CHANGESET
     Return the version string for packages using hg-fetch.  It works in the same way as git-version.

Synopses and Descriptions
-------------------------

As we have seen before, each package in GNU Guix includes a synopsis and a description (see Defining Packages).  Synopses and descriptions are important: They are what 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 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.

Descriptions can include Texinfo markup, which is useful to introduce ornaments such as @code or @dfn, bullet lists, or hyperlinks (see Overview (GNU Texinfo)).  However you should be careful when using some characters for example @ and curly braces which are the basic special characters in Texinfo (see Special Characters (GNU Texinfo)).  User interfaces such as guix show take care of rendering it appropriately.

Synopses and descriptions are translated by volunteers at Weblate (https://translate.fedoraproject.org/projects/guix/packages) 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 xgettext to extract them as translatable strings, synopses and descriptions must be literal strings.  This means that you cannot use string-append or format to construct these strings:

     (package
       ;; ...
       (synopsis "This is translatable")
       (description (string-append "This is " "*not*" " translatable.")))

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 (see xgettext Invocation (GNU Gettext)):

     ;; 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. ...")

Snippets versus Phases
----------------------

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 origin record documentation for more information (see origin Reference).

Emacs Packages
--------------

Emacs packages should preferably use the Emacs build system (see 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 #:tests? argument to #true.  By default, the command to run the test is make check, but any command can be specified via the #:test-command argument.  The #:test-command argument expects a list containing a command and its arguments, to be invoked during the check phase.

The Elisp dependencies of Emacs packages are typically provided as propagated-inputs when required at run time.  As for other packages, build or test dependencies should be specified as native-inputs.

Emacs packages sometimes depend on resources directories that should be installed along the Elisp files.  The #:include argument can be used for that purpose, by specifying a list of regexps to match.  The best practice when using the #:include argument is to extend rather than override its default value (accessible via the %default-include variable).  As an example, a yasnippet extension package typically include a snippets directory, which could be copied to the installation directory using:

     #:include (cons "^snippets/" %default-include)

When encountering problems, it is wise to check for the presence of the Package-Requires extension header in the package main source file, and whether any dependencies and their versions listed therein are satisfied.

Python Modules
--------------

We currently package Python 2 and Python 3, under the Scheme variable names python-2 and python as explained in 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 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 python-foo.  If it is compiled with Python 2, we name it 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 python, we drop this; for instance, the module python-dateutil is packaged under the names python-dateutil and python2-dateutil.  If the project name starts with py (e.g. pytz), we keep it and prefix it as described above.

Specifying Dependencies
.......................

Dependency information for Python packages is usually available in the package source tree, with varying degrees of accuracy: in the setup.py file, in requirements.txt, or in tox.ini.

Your mission, when writing a recipe for a Python package, is to map these dependencies to the appropriate type of ``input'' (see inputs).  Although the pypi importer normally does a good job (see Invoking guix import), you may want to check the following check list to determine which dependency goes where.

  * We currently package Python 2 with setuptools and pip installed like Python 3.4 has per default.  Thus you don't need to specify either of these as an input.  guix lint will warn you if you do.

  * Python dependencies required at run time go into propagated-inputs.  They are typically defined with the install_requires keyword in setup.py, or in the requirements.txt file.

  * Python packages required only at build time---e.g., those listed with the setup_requires keyword in setup.py---or only for testing---e.g., those in tests_require---go into 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 pytest, mock, and nose test frameworks.  Of course if any of these packages is also required at run-time, it needs to go to propagated-inputs.

  * Anything that does not fall in the previous categories goes to inputs, for example programs or C libraries required for building Python packages containing C extensions.

  * If a Python package has optional dependencies (extras_require), it is up to you to decide whether to add them or not, based on their usefulness/overhead ratio (see guix size).

Perl Modules
------------

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 :: by dashes and prepend the prefix perl-. So the class XML::Parser becomes perl-xml-parser. Modules containing several classes keep their lowercase upstream name and are also prepended by perl-.  Such modules tend to have the word perl somewhere in their name, which gets dropped in favor of the prefix.  For instance, libwww-perl becomes perl-libwww.

Java Packages
-------------

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 java-.  If a project already contains the word java, we drop this; for instance, the package ngsjava is packaged under the name java-ngs.

For Java packages containing a single class or a small class hierarchy, we use the lowercase class name, replace all occurrences of . by dashes and prepend the prefix java-.  So the class apache.commons.cli becomes package java-apache-commons-cli.

Rust Crates
-----------

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 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 rust-clap-2, rust-rand-0.6.

Because of the difficulty in reusing rust packages as pre-compiled inputs for other packages the Cargo build system (see cargo-build-system) presents the #:cargo-inputs and cargo-development-inputs keywords as build system arguments.  It would be helpful to think of these as similar to propagated-inputs and native-inputs.  Rust dependencies and build-dependencies should go in #:cargo-inputs, and dev-dependencies should go in #:cargo-development-inputs.  If a Rust package links to other libraries then the standard placement in 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 #: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.

Elm Packages
------------

Elm applications can be named like other software: their names need not mention Elm.

Packages in the Elm sense (see elm-build-system under Build Systems) are required use names of the format AUTHOR/PROJECT, where both the AUTHOR and the PROJECT may contain hyphens internally, and the AUTHOR sometimes contains uppercase letters.

To form the Guix package name from the upstream name, we follow a convention similar to Python packages (see Python Modules), adding an elm- prefix unless the name would already begin with 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 'upstream-name property when necessary so that guix import elm will work correctly (see Invoking guix import). The most notable scenarios when explicitly specifying the upstream name is necessary are:

 1. When the AUTHOR is elm and the PROJECT contains one or more hyphens, as with elm/virtual-dom; and

 2. When the AUTHOR contains hyphens or uppercase letters, as with Elm-Canvas/raster-shapes---unless the AUTHOR is elm-explorations, which is handled as a special case, so packages like elm-explorations/markdown do not need to use the 'upstream-name property.

The module (guix build-system elm) provides the following utilities for working with names and related conventions:

 -- Scheme procedure: elm-package-origin ELM-NAME VERSION
     HASH
     Returns a Git origin using the repository naming and tagging regime required for a published Elm package with the upstream name ELM-NAME at version VERSION with sha256 checksum HASH.

     For example:

          (package
            (name "elm-html")
            (version "1.0.0")
            (source
             (elm-package-origin
              "elm/html"
              version
              (base32 "15k1679ja57vvlpinpv06znmrxy09lbhzfkzdc89i01qa8c4gb4a")))
            ...)

 -- Scheme procedure: elm->package-name ELM-NAME
     Returns the Guix-style package name for an Elm package with upstream name ELM-NAME.

     Note that there is more than one possible ELM-NAME for which elm->package-name will produce a given result.

 -- Scheme procedure: guix-package->elm-name PACKAGE
     Given an Elm PACKAGE, returns the possibly-inferred upstream name, or #f the upstream name is not specified via the 'upstream-name property and can not be inferred by infer-elm-package-name.

 -- Scheme procedure: infer-elm-package-name GUIX-NAME
     Given the GUIX-NAME of an Elm package, returns the inferred upstream name, or #f if the upstream name can't be inferred.  If the result is not #f, supplying it to elm->package-name would produce GUIX-NAME.

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 font-; it is followed by the foundry name and a dash - 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 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 font-liberation-sans and so on; but as they are distributed together under a common name, we prefer to package them together as 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 -ttf for TrueType fonts, -otf for OpenType fonts and -type1 for PostScript Type 1 fonts.

Coding Style
============

In general our code follows the GNU Coding Standards (see GNU Coding Standards).  However, they do not say much about Scheme, so here are some additional rules.

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 memoize procedure.

Modules
-------

Guile modules that are meant to be used on the builder side must live in the (guix build ...) 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 (gnu ...) name space rather than (guix ...).

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 car, cdr, 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 define-record-type*) rather than abuse lists.  In addition, it should use pattern matching, via Guile’s (ice-9 match) module, especially when matching lists (see Pattern Matching (GNU Guile Reference Manual)).

Formatting Code
---------------

When writing Scheme code, we follow common wisdom among Scheme programmers.  In general, we follow the Riastradh's Lisp Style Rules (https://mumble.net/~campbell/scheme/style.txt).  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 substitute* macro, have special indentation rules.  These are defined in the .dir-locals.el file, which Emacs automatically uses.  Also note that Emacs-Guix provides guix-devel-mode mode that indents and highlights Guix code properly (see Development (The Emacs-Guix Reference Manual)).

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:

     ./pre-inst-env guix style PACKAGE

See Invoking guix style, for more information.

If you are editing code with Vim, we recommend that you run :set autoindent so that your code is automatically indented as you type. Additionally, paredit.vim (https://www.vim.org/scripts/script.php?script_id=3998) 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 (guix build ...) name space, though.

Procedures should not have more than four positional parameters.  Use keyword parameters for procedures that take more than four parameters.

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 git format-patch sent to the guix-patches@gnu.org mailing list (see Submitting patches to a project (Git User Manual)). Contributors are encouraged to take a moment to set some Git repository options (see Configuring Git) first, which can improve the readability of patches.  Seasoned Guix developers may also want to look at the section on commit access (see Commit Access).

This mailing list is backed by a Debbugs instance, which allows us to keep track of submissions (see 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 NNN@debbugs.gnu.org, where NNN is the tracking number (see Sending a Patch Series).

Please write commit logs in the ChangeLog format (see Change Logs (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:

 1. When generating your patches with git format-patch or git send-email, we recommend using the option --base=, perhaps with the value 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.

 2. 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 gpg --verify command.

 3. Take some time to provide an adequate synopsis and description for the package.  See Synopses and Descriptions, for some guidelines.

 4. Run guix lint PACKAGE, where PACKAGE is the name of the new or modified package, and fix any errors it reports (see Invoking guix lint).

 5. Run guix style PACKAGE to format the new package definition according to the project's conventions (see Invoking guix style).

 6. Make sure the package builds on your platform, using guix build PACKAGE.

 7. 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 qemu-binfmt-service-type to emulate them.  In order to enable it, add the virtualization service module and the following service to the list of services in your operating-system configuration:

          (service qemu-binfmt-service-type
           (qemu-binfmt-configuration
             (platforms (lookup-qemu-platforms "arm" "aarch64"))))

     Then reconfigure your system.

     You can then build packages for different platforms by specifying the --system option.  For example, to build the "hello" package for the armhf or aarch64 architectures, you would run the following commands, respectively:

          guix build --system=armhf-linux --rounds=2 hello
          guix build --system=aarch64-linux --rounds=2 hello

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

 9. Take a look at the profile reported by guix size (see 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 (see Packages with Multiple Outputs), and which optional dependencies should be used.  In particular, avoid adding texlive as a dependency: because of its extreme size, use the texlive-tiny package or texlive-union procedure instead.

 10. For important changes, check that dependent packages (if applicable) are not affected by the change; guix refresh --list-dependent PACKAGE will help you do that (see Invoking guix refresh).

     Depending on the number of dependent packages and thus the amount of rebuilding induced, commits go to different branches, along these lines:

     300 dependent packages or less
          master branch (non-disruptive changes).

     between 300 and 1,800 dependent packages
          staging branch (non-disruptive changes).  This branch is intended to be merged in master every 6 weeks or so.  Topical changes (e.g., an update of the GNOME stack) can instead go to a specific branch (say, gnome-updates).  This branch is not expected to be buildable or usable until late in its development process.

     more than 1,800 dependent packages
          core-updates branch (may include major and potentially disruptive changes).  This branch is intended to be merged in master every 6 months or so.  This branch is not expected to be buildable or usable until late in its development process.

     All these branches are tracked by our build farm (https://SUBSTITUTE-SERVER-1) and merged into 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 staging or core-updates branches, they will be forked and renamed with the suffix -frozen, at which time only bug fixes may be pushed to the frozen branches.  The core-updates and 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.

 11. 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 (see Invoking guix build):

          guix build --rounds=2 my-package

     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 guix challenge (see Invoking guix challenge).  You may run it once the package has been committed and built by 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 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 uname or /proc files.

 12. When writing documentation, please use gender-neutral wording when referring to people, such as singular ``they'', ``their'', ``them'' (https://en.wikipedia.org/wiki/Singular_they), and so forth.

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

 14. Please follow our code formatting rules, possibly running guix style script to do that automatically for you (see Formatting Code).

 15. When possible, use mirrors in the source URL (see 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 name field in the URL: it is not very useful and if the name changes, the URL will probably be wrong.

 16. Check if Guix builds (see Building from Git) and address the warnings, especially those about use of undefined symbols.

 17. Make sure your changes do not break Guix and simulate a guix pull with:

          guix pull --url=/path/to/your/checkout --profile=/tmp/guix.master

When posting a patch to the mailing list, use [PATCH] ... as a subject, if your patch is to be applied on a branch other than master, say core-updates, specify it in the subject like [PATCH core-updates] ....  You may use your email client or the git send-email command (see 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 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 NNN-done@debbugs.gnu.org.

Configuring Git
---------------

If you have not done so already, you may wish to set a name and email that will be associated with your commits (see Telling Git your name (Git User Manual)).  If you wish to use a different name or email just for commits in this repository, you can use git config --local, or edit .git/config in the repository instead of ~/.gitconfig.

We provide some default settings in 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 .git/config in your checkout, or by telling Git to include the whole file:

     git config --local include.path ../etc/git/gitconfig

From then on, any changes to etc/git/gitconfig would automatically take effect.

Since the first patch in a series must be sent separately (see Sending a Patch Series), it can also be helpful to tell git format-patch to handle the e-mail threading instead of git send-email:

     git config --local format.thread shallow
     git config --local sendemail.thread no

Sending a Patch Series
----------------------

When sending a patch series (e.g., using git send-email), please first send one message to guix-patches@gnu.org, and then send subsequent patches to NNN@debbugs.gnu.org to make sure they are kept together.  See the Debbugs documentation (https://debbugs.gnu.org/Advanced.html) for more information.  You can install git send-email with guix install git:send-email.

Tracking Bugs and Patches
=========================

This section describes how the Guix project tracks its bug reports and patch submissions.

The Issue Tracker
-----------------

Bug reports and patch submissions are currently tracked using the Debbugs instance at https://bugs.gnu.org.  Bug reports are filed against the guix ``package'' (in Debbugs parlance), by sending email to bug-guix@gnu.org, while patch submissions are filed against the guix-patches package by sending email to guix-patches@gnu.org (see Submitting Patches).

Debbugs User Interfaces
-----------------------

A web interface (actually two web interfaces!) are available to browse issues:

  * https://issues.guix.gnu.org provides a pleasant interface (The web interface at https://issues.guix.gnu.org is powered by Mumi, a nice piece of software written in Guile, and you can help!  See https://git.elephly.net/gitweb.cgi?p=software/mumi.git.) to browse bug reports and patches, and to participate in discussions;

  * https://bugs.gnu.org/guix lists bug reports;

  * https://bugs.gnu.org/guix-patches lists patch submissions.

To view discussions related to issue number N, go to https://issues.guix.gnu.org/N or https://bugs.gnu.org/N.

If you use Emacs, you may find it more convenient to interact with issues using debbugs.el, which you can install with:

     guix install emacs-debbugs

For example, to list all open issues on guix-patches, hit:

     C-u M-x debbugs-gnu RET RET guix-patches RET n y

See Debbugs User Guide, for more information on this nifty tool!

Debbugs Usertags
----------------

Debbugs provides a feature called 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 (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 guix-patches) tagged with the usertag powerpc64le-linux for the user guix, open a URL like the following in a web browser: 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 guix.  The following usertags currently exist for that user:

powerpc64le-linux
     The purpose of this usertag is to make it easy to find the issues that matter most for the powerpc64le-linux system type.  Please assign this usertag to bugs or patches that affect 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 powerpc64le-linux system type, even if the issue affects other system types, too.

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.

If you're a committer and you want to add a usertag, just start using it with the 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.

Commit Access
=============

Everyone can contribute to Guix without having commit access (see 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.

Applying for Commit Access
--------------------------

When you deem it necessary, consider applying for commit access by following these steps:

 1. Find three committers who would vouch for you.  You can view the list of committers at https://savannah.gnu.org/project/memberlist.php?group=guix.  Each of them should email a statement to 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 not a judgment on the value of your work, so a refusal should rather be interpreted as ``let's try again later''.

 2. Send 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 https://emailselfdefense.fsf.org/en/, for an introduction to public-key cryptography with GnuPG.

     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 ~/.gnupg/gpg.conf (see GPG Esoteric Options (The GNU Privacy Guard Manual)):

          digest-algo sha512

 3. Maintainers ultimately decide whether to grant you commit access, usually following your referrals' recommendation.

 4. If and once you've been given access, please send a message to 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.

          Before you can push for the first time, maintainers must:

           1. add your OpenPGP key to the keyring branch;

           2. add your OpenPGP fingerprint to the .guix-authorizations file of the branch(es) you will commit to.

 5. Make sure to read the rest of this section and... profit!

     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!

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 keys.openpgp.org.  To configure Git to automatically sign commits, run:

     git config commit.gpgsign true

     # Substitute the fingerprint of your public PGP key.
     git config user.signingkey CABBA6EA1DC0FF33

To check that commits are signed with correct key, use:

     make authenticate

You can prevent yourself from accidentally pushing unsigned or signed with the wrong key commits to Savannah by using the pre-push Git hook located at etc/git/pre-push:

     cp etc/git/pre-push .git/hooks/pre-push

It additionally calls make check-channel-news to be sure news.scm file is correct.

Commit Policy
-------------

If you get commit access, please make sure to follow the policy below (discussions of the policy can take place on guix-devel@gnu.org).

Non-trivial patches should always be posted to guix-patches@gnu.org (trivial patches include fixing typos, etc.).  This mailing list fills the patch-tracking database (see 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 (guix-commits@gnu.org), so people can notice.  Before pushing your changes, make sure to run git pull --rebase.

When pushing a commit on behalf of somebody else, please add a Signed-off-by line at the end of the commit log message---e.g., with git am --signoff.  This improves tracking of who did what.

When adding channel news entries (see Writing Channel News), make sure they are well-formed by running the following command right before pushing:

     make check-channel-news

For anything else, please post to guix-patches@gnu.org and leave time for a review, without committing anything (see 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.

Addressing Issues
-----------------

Peer review (see Submitting Patches) and tools such as guix lint (see Invoking guix lint) and the test suite (see 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 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.

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.

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 .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 (See https://guix.gnu.org/en/about for the current list of maintainers.  You can email them privately at 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 (see 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:

  * repeated violation of the commit policy stated above;

  * repeated failure to take peer criticism into account;

  * breaching trust through a series of grave incidents.

When maintainers resort to such a decision, they notify developers on guix-devel@gnu.org; inquiries may be sent to guix-maintainers@gnu.org.  Depending on the situation, the individual may still be welcome to contribute.

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 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!

Updating the Guix Package
=========================

It is sometimes desirable to update the guix package itself (the package defined in (gnu packages package-management)), for example to make new daemon features available for use by the guix-service-type service type.  In order to simplify this task, the following command can be used:

     make update-guix-package

The update-guix-package make target will use the last known commit corresponding to HEAD in your Guix checkout, compute the hash of the Guix sources corresponding to that commit and update the commit, revision and hash of the guix package definition.

To validate that the updated 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:

     ./pre-inst-env guix build guix

To guard against accidentally updating the 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, at your own peril, by setting the 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.

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 guix-patches@gnu.org.  Prepend [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.  See Submitting Patches for more information on how to send your patches.

To modify the documentation, you need to edit doc/guix.texi and doc/contributing.texi (which contains this documentation section), or doc/guix-cookbook.texi for the cookbook.  If you compiled the Guix repository before, you will have many more .texi files that are translations of these documents.  Do not modify them, the translation is managed through Weblate (https://translate.fedoraproject.org/projects/guix). See Translating Guix for more information.

To render documentation, you must first make sure that you ran ./configure in your source tree (see Running Guix Before It Is Installed).  After that you can run one of the following commands:

  * make doc/guix.info to compile the Info manual. You can check it with info doc/guix.info.

  * make doc/guix.html to compile the HTML version. You can point your browser to the relevant file in the doc/guix.html directory.

  * make doc/guix-cookbook.info for the cookbook Info manual.

  * make doc/guix-cookbook.html for the cookbook HTML version.

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 Weblate instance (https://translate.fedoraproject.org/projects/guix/) 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 hello package by typing guix show hello.  On the ``homepage'' line, you will see https://www.gnu.org/software/hello/ as the homepage.

Many GNU and non-GNU packages can be translated on the Translation Project (https://translationproject.org).  Some projects with multiple components have their own platform.  For instance, GNOME has its own platform, Damned Lies (https://l10n.gnome.org/).

Guix has five components hosted on Weblate.

  * guix contains all the strings from the Guix software (the guided system installer, the package manager, etc), excluding packages.

  * packages contains the synopsis (single-sentence description of a package) and description (longer description) of packages in Guix.

  * website contains the official Guix website, except for blog posts and multimedia content.

  * documentation-manual corresponds to this manual.

  * documentation-cookbook is the component for the cookbook.

General Directions
..................

Once you get an account, you should be able to select a component from the guix project (https://translate.fedoraproject.org/projects/guix/), 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 GNU Gettext (https://www.gnu.org/software/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 Poedit (https://poedit.net/) is one example, and (after logging in) upload (https://docs.weblate.org/en/latest/user/files.html) the changed file.  There is also a special PO editing mode (https://www.emacswiki.org/emacs/PoMode) 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 documentation (https://docs.weblate.org/en/latest/) to familiarize yourself with the platform.

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!

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 ~ followed by one or more characters.

     When printing the string, Guile replaces the special formatting symbols with actual values.  For instance, the string ambiguous package specification `~a' would be substituted to contain said package specification instead of ~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 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 package '~a' has been superseded by '~a' by '~a' superseeds package '~a', because the meaning would be reversed.  If FOO is superseded by BAR, the translation would read '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.  See Formatted Output (GNU Guile Reference Manual), for more information on formatting in Guile.

packages

     Package descriptions occasionally contain Texinfo markup (see Synopses and Descriptions).   Texinfo markup looks like @code{rm -rf}, @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, as it contains literal code that do not change with language.  You can translate the content of formatting markup such as @emph, @i, @itemize, @item.  However, do not translate the name of the markup, or it will not be recognized.  Do not translate the word after @end, it is the name of the markup that is closed at this position (e.g. @itemize ... @end itemize).

documentation-manual and documentation-cookbook

     The first step to ensure a successful translation of the manual is to find and translate the following strings first:

       * version.texi: Translate this string as version-xx.texi, where xx is your language code (the one shown in the URL on weblate).

       * contributing.texi: Translate this string as contributing.xx.texi, where xx is the same language 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 Top as its translation.

     Translating these strings first ensure we can include your translation in the guix repository without breaking the make process or the guix pull machinery.

     The manual and the cookbook both use Texinfo.  As for 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, @file, @var, @value, etc.  You should translate the content of formatting markup such as @emph, @i, etc.

     The manual contains sections that can be referred to by name by @ref, @xref and @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 @pxref{Defining Packages,,, guix, GNU Guix Reference Manual}, you would replace Defining Packages with the title of that section in the translated manual 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 guix with guix.xx where xx is your language code.  GNU Guix Reference Manual is the text of the link.  You can translate it however you wish.

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.

          #. 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>."

     Note that you need to include the same markups.  You cannot skip any.

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.

Outside of Weblate
..................

Currently, some parts of Guix cannot be translated on Weblate, help wanted!

  * guix pull news can be translated in 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. See Writing Channel News, for more information about channel news.

  * Guix blog posts cannot currently be translated.

  * The installer script (for foreign distributions) is entirely in English.

  * Some of the libraries Guix uses cannot be translated or are translated outside of the Guix project.  Guile itself is not internationalized.

  * Other manuals linked from this manual or the cookbook might not be translated.

Conditions for Inclusion
........................

There are no conditions for adding new translations of the guix and 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.

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

  * New po files for the guix and packages components must be registered by adding the new language to po/guix/LINGUAS or po/packages/LINGUAS.

  * New po files for the documentation-manual component must be registered by adding the file name to DOC_PO_FILES in po/doc/local.mk, the generated %D%/guix.xx.texi manual to info_TEXINFOS in doc/local.mk and the generated %D%/guix.xx.texi and %D%/contributing.xx.texi to TRANSLATED_INFO also in doc/local.mk.

  * New po files for the documentation-cookbook component must be registered by adding the file name to DOC_COOKBOOK_PO_FILES in po/doc/local.mk, the generated %D%/guix-cookbook.xx.texi manual to info_TEXINFOS in doc/local.mk and the generated %D%/guix-cookbook.xx.texi to TRANSLATED_INFO also in doc/local.mk.

  * New po files for the website component must be added to the guix-artwork repository, in website/po/. website/po/LINGUAS and website/po/ietf-tags.scm must be updated accordingly (see website/i18n-howto.txt for more information on the process).