贡献
**

这个项目是大家合作的成果，我们需要你的帮助以更好地发展。请通过 guix-devel@gnu.org 和 Freenode IRC 上的 #guix 联系我们。我们欢迎您的想法、bug反馈、补丁，以及任何可能对项目有帮助的贡献。我们特别欢迎帮助我们打包（see 打包指导）。

我们希望提供一个温暖、友好，并且没有骚扰的的环境，这样每个人都能尽最大努力贡献。为了这个目的，我们的项目遵循“贡献者契约”，这个契约是根据 http://contributor-covenant.org/制定的。你可以在源代码目录里的 CODE-OF-CONDUCT文件里找到一份本地版。

贡献者在提交补丁和网上交流时不需要使用法律认可的名字。他们可以使用任何名字或者假名。

从Git编译
======

如果你想折腾Guix本身，建议使用Git仓库里最新的版本：

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

当从Git检出构建Guix时，除安装指导（see Requirements）里提及的软件包之外还需要这些包。

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

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

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

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

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

  * GNU Help2man （可选） (http://www.gnu.org/software/help2man/)。

设置Guix开发环境的最简单的方式当然是使用Guix！下面这些命令启动一个shell，所有的依赖和环境变量都为折腾Guix设置好了：

     guix environment guix

这个命令更多的信息请参考see Invoking guix environment。额外的依赖可以通过 --ad-hoc选项添加：

     guix environment guix --ad-hoc help2man git strace

运行 ./bootstrap 以使用Autoconf和Automake生成编译系统的基础框架。如果你的得到这样的错误：

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

它可能意味着Autoconf无法找到由pkg-config提供的pkg.m4。请确保pkg.m4 可用。由Guile提供的guile.m4宏也类似。假如你的Automake安装在 /usr/local，那么它不会从/usr/share里寻找.m4文件。这种情况下，你必须执行下面这个命令：

     export ACLOCAL_PATH=/usr/share/aclocal

参考see Macro Search Path (The GNU Automake Manual).

然后，像正常一样运行./configure。确保提供 --localstatedir=DIRECTORY参数，DIRECTORY是你当前系统的 localstatedir的值。（see The Store）

最后，用make check执行测试（see Running the Test Suite）。如果遇到任何错误，请参考“安装指导”（see Installation）或者给邮件列表发邮件。

在安装之前运行Guix
===========

为了保持一个合适的工作环境，你会发现在你的本地代码树里测试修改而不用安装它们会很有用。TODO: So that you can distinguish between your ``end-user'' hat and your ``motley'' costume.

这样，即使你没有运行make install，所有的命令行工具都可以使用。为此，你先要有一个包含全部依赖的环境（see 从Git编译），然后，为所有的命令添加前缀./pre-inst-env（pre-inst-env脚本在Guix编译树的最顶层，它由 ./configure生成），如 (sudo命令的-E参数确保GUILE_LOAD_PATH被正确设置，从而guix-daemon和它使用的工具可以找到它们需要的Guile模块。)：

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

类似的，对于使用Guix模块的Guile会话：

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

     ;;; ("x86_64-linux")

... and for a REPL (see Using Guile Interactively (Guile Reference Manual)):

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

pre-inst-env脚本设置为此好了所有必要的的环境变量，包括PATH和 GUILE_LOAD_PATH。

./pre-inst-env guix pull 不 会更新本地源代码树，它只更新符号链接~/.config/guix/current (see Invoking guix pull)。如果你想更新本地源代码树，请运行git pull。

完美的配置
=====

折腾Guix的完美配置也是折腾Guile的完美配置see Using Guile in Emacs (Guile Reference Manual))。首先，你需要的不仅是一个编辑器，你需要 Emacs (http://www.gnu.org/software/emacs)，以及美妙的 Geiser (http://nongnu.org/geiser/)。为此，请运行：

     guix package -i emacs guile emacs-geiser

Geiser允许在Emacs里进行交互式的、增长式的开发：buffer里的代码补全和执行，获取一行的文档（docstrings），上下文敏感的补全，M-.跳转到对象定义，测试代码的 REPL，及更多（see Introduction (Geiser User Manual)）。为了方便的 Guix开发，请确保修改Guile的加载路径（load path）以使其能从你的项目里找到源代码文件。

     ;; 假设Guix项目在 ~/src/guix.
     (with-eval-after-load 'geiser-guile
       (add-to-list 'geiser-guile-load-path "~/src/guix"))

真正编辑代码时别忘了Emacs自带了方便的Scheme模式。而且，一定不要错过 Paredit (http://www.emacswiki.org/emacs/ParEdit)。它提供了直接操作语法树的的功能，例如，用S-表达式替换父节点，为S-表达式添加、删除前后的括号，删除后面的S- 表达式，等等。

在etc/snippets文件夹里，我们还为普通的git commit信息和软件包定义提供模板。这些模板可以通过YASnippet (http://joaotavora.github.io/yasnippet/)使用，它可以把短的触发字符串扩展成交互式的文字片段。你可能希望将这个文件夹添加到Emacs的 YAS-SNIPPET-DIRS变量里。

     ;; 假设Guix项目在 ~/src/guix.
     (with-eval-after-load 'yasnippet
       (add-to-list 'yas-snippet-dirs "~/src/guix/etc/snippets"))

commit信息片段显示staged文件需要依赖Magit (https://magit.vc/)。编辑commit信息时，输入add，然后按TAB就可以插入一段用于新增软件包的模板；输入 update，然后按TAB可以插入一段更新软件包的模板；输入https然后按TAB可以插入一段修改主页URI为HTTPS的模板。

scheme-mode最重要的模板可以通过输入package...，然后按TAB触发。这个片段还插入了触发字符串origin...，以进一步展开。origin片段更进一步的可能插入其它以...结尾的触发字符串，它们可以被继续展开。

打包指导
====

这个GNU发行版正在开发的早期阶段，可能缺少一些你喜欢的软件。这个章节介绍你可以怎样帮助这个发行版成长。

自由软件通常以源代码包的形式分发，通常是包含完整代码的tar.gz包。添加软件包到这个发行版意味着两件事：添加描述如何编译包的配方和一系列依赖软件，以及添加配方之外的软件包元数据，如一段文字描述和证书信息。

在Guix里所有这些信息都包含在软件包定义里。软件包定义提供了软件包的高层视角。它们使用Scheme编程语言编写，事实上，对每个软件包我们都定义一个绑定到软件包定义的的变量，并且从模块（see Package Modules）中导出那个变量。然而，深入的Scheme 知识不是创建软件包的前提条件。若要了解软件包的更多信息，see Defining Packages。

一旦软件包定义准备好了，并且包存在Guix代码树的一个文件里，你可以用guix build (see Invoking guix build)命令测试它。假设这个新软件包的名字叫做 gnew，你可以在Guix编译树里运行这个命令(see 在安装之前运行Guix)：

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

使用--keep-failed参数会保留失败的编译树，这可以使调试编译错误更容易。 --log-file也是一个调试时很有用的参数，它可以用来访问编译日志。

如果guix命令找不到这个软件包，那可能是因为源文件包含语法错误，或者缺少导出软件包的define-public语句。为了查找错误，你可以用Guile导入这个模块以了解这个错误的详情：

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

一旦你的软件包可以正确编译，请给我们发送补丁（see 提交补丁）。当然，如果你需要帮助，我们也会很乐意帮助你。一旦补丁被提交到Guix仓库里，这个新的软件包会被自动地在支持的平台上编译our continuous integration system (http://hydra.gnu.org/jobset/gnu/master)。

用户可以通过运行guix pull命令获取最新的软件包定义（see Invoking guix pull）。当SUBSTITUTE-SERVER编译好这些软件包之后，安装这些软件包时会自动从服务器（see Substitutes）上下载编译好的二进制包。唯一需要人工干预的地方是评审和应用代码补丁。

软件自由
----

开发GNU操作系统是为了用户拥有计算的自由。GNU是自由软件，这意味着它有四项重要的自由 (http://www.gnu.org/philosophy/free-sw.html)：运行程序的自由，以源代码形式学习和修改程序的自由，原样重新分发副本的自由，和分发修改后的版本的自由。GNU发行版里包含的软件包只提供遵守这四项自由的软件。

此外，GNU发行版遵循自由软 件发行版准则 (http://www.gnu.org/distros/free-system-distribution-guidelines.html)。这些准则拒绝非自由的固件和对非自由软件的推荐，并讨论解决商标和专利的方法。

某些上游的软件包源代码包含一小部分违反上述准则的可选的子集，比如这个子集本身就是非自由代码。这时，这些讨厌的代码需要用合适的补丁或者软件包定义（see Defining Packages）里的origin里的代码片段移除。这样，guix build --source就可以返回自由的源代码而不是未经修改的上游源代码。

软件包命名
-----

一个软件包事实上有两个名字：第一个是Scheme变量的名字，即用 define-public定义的名字。通过这个名字，软件包可以被Scheme代码找到，如用作其它软件包的输入。第二个名字是软件包定义里的name属性的字符串值。这个名字用于软件包管理命令，如：guix package，guix build

两个名字通常是相同的，常是上游项目名字转成小写字母并把下划线替换成连字符的结果。比如，GNUnet转成gnunet，SDL_net转成sdl-net。

我们不给库软件包添加lib前缀，除非它是项目官方名字的一部分。但是 see Python模块和Perl模块有关于Python和Perl语言的特殊规则。

字体软件包的名字处理起来不同，see 字体.

版本号
---

我们通常只为每个自由软件的最新版本打包。但是有时候，比如对于版本不兼容的库，需要有同一个软件包的两个或更多版本。它们需要使用不同的Scheme变量名。我们为最新的版本使用软件包命名里规定的名字，旧的版本使用加上后缀的名字，后缀是- 和可以区分开版本号的版本号的最小前缀。

软件包定义里的名字对于同一个软件包的所有版本都是相同的，并且不含有版本号。

例如，GTK+的2.24.20和3.9.12两个版本可以这样打包：

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

如果我们还需要GTK+ 3.8.2，就这样打包

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

有时候，我们为软件包上游的版本控制系统（VCS）的快照而不是正式发布版打包。这是特殊情况，因为决定哪个是稳定版的权力应该属于上游开发者。然而，有时候这是必须的。那么，我们该如何决定写在version里的版本号呢？

显然，我们需要让VCS快照的commit ID在版本号中体现出来，但是我们也需要确保版本号单调递增，以便guix package --upgrade决定哪个版本号更新。由于commit ID，尤其是Git的commit ID，不是单调递增的，我们添加一个每次升级快照时都手动增长的 revision数字。最后的版本号字符串看起来是这样：

     2.0.11-3.cabba9e
       ^    ^    ^
       |    |    `-- 上游的commit ID
       |    |
       |    `--- Guix软件包的revision
       |
     最新的上游版本号

把版本号里的commit ID截短，比如只取7个数字，是一个好主意。它避免了美学上的烦恼（假设美学在这里很重要），以及操作系统限制引起的问题（比如Linux内核的127字节）。尽管如此，在origin里最好使用完整的commit ID，以避免混淆。

     (define my-package
       (let ((commit "c3f29bc928d5900971f65965feaae59e1272a3f7")
             (revision "1"))          ;Guix软件包的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))))
           ;; ...
           )))

简介和描述
-----

我们已经看到，GNU Guix里的每个软件包都包含一个简介（synopsis）和一个描述（description）（see Defining Packages）。简介和描述很重要：它们是 guix package --search搜索的信息，并且是帮助用户决定一个软件包是否符合自己需求的重要信息。因此，打包的人应该关注怎样写它们的内容。

简介必须以大写字母开头，并且不能以句号结尾。它们不能以 ``a'' 或者 ``the'' 等没有意义的词开头。例如 ``File-frobbing tool'' 要比 ``A tool that frobs files'' 更好。简介需要说明软件包是什么－－如 ``Core GNU utilities (file, text, shell)''，或者它的用途－－如 GNU grep 的简介是 ``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 package --show take care of rendering it appropriately.

Synopses and descriptions are translated by volunteers at the Translation Project (http://translationproject.org/domain/guix-packages.html) 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. ...")

Python模块
--------

We currently package Python 2 and Python 3, under the Scheme variable names python-2 and python as explained in 版本号.  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 compiles only with Python 3, we name it python-foo; if it compiles only with Python 2, we name it python2-foo. If it is compatible with both versions, we create two packages with the corresponding names.

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模块
------

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

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.

字体
--

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.

代码风格
====

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.

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

When writing Scheme code, we follow common wisdom among Scheme programmers. In general, we follow the Riastradh's Lisp Style Rules (http://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:

     ./etc/indent-code.el gnu/packages/FILE.scm PACKAGE

This automatically indents the definition of PACKAGE in gnu/packages/FILE.scm by running Emacs in batch mode.  To indent a whole file, omit the second argument:

     ./etc/indent-code.el gnu/services/FILE.scm

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.

提交补丁
====

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.

This mailing list is backed by a Debbugs instance accessible at https://bugs.gnu.org/guix-patches, which allows us to keep track of submissions.  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. 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.

 2. Take some time to provide an adequate synopsis and description for the package.  See 简介和描述, for some guidelines.

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

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

 5. 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 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" "mips64el"))
             (guix-support? #t)))

     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, aarch64, or mips64 architectures, you would run the following commands, respectively:

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

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

 7. 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 texlive-tiny or texlive-union instead.

 8. For important changes, check that dependent package (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,200 dependent packages
          staging branch (non-disruptive changes).  This branch is intended to be merged in master every 3 weeks or so.  Topical changes (e.g., an update of the GNOME stack) can instead go to a specific branch (say, gnome-updates).

     more than 1,200 dependent packages
          core-updates branch (may include major and potentially disruptive changes).  This branch is intended to be merged in master every 2.5 months or so.

     All these branches are tracked by our build farm (https://hydra.gnu.org/project/gnu) 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.

     Generally, branches other than master are considered frozen if there has been a recent evaluation, or there is a corresponding -next branch.  Please ask on the mailing list or IRC if unsure where to place a patch.

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

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

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

 12. Please follow our code formatting rules, possibly running the etc/indent-code.el script to do that automatically for you (see Formatting Code).

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

When posting a patch to the mailing list, use [PATCH] ... as a subject.  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.

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

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.