aboutsummaryrefslogtreecommitdiff
path: root/doc/contributing.zh_CN.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/contributing.zh_CN.texi')
-rw-r--r--doc/contributing.zh_CN.texi897
1 files changed, 0 insertions, 897 deletions
diff --git a/doc/contributing.zh_CN.texi b/doc/contributing.zh_CN.texi
deleted file mode 100644
index ba8a824cad..0000000000
--- a/doc/contributing.zh_CN.texi
+++ /dev/null
@@ -1,897 +0,0 @@
-@node 贡献
-@chapter 贡献
-
-这个项目是大家合作的成果,我们需要你的帮助以更好地发展。请通过
-@email{guix-devel@@gnu.org} 和 Freenode IRC 上的 @code{#guix} 联系我们。我们欢迎
-您的想法、bug反馈、补丁,以及任何可能对项目有帮助的贡献。我们特别欢迎帮助我们打
-包(@pxref{打包指导})。
-
-@cindex 行为准则和贡献者
-@cindex 贡献者契约
-我们希望提供一个温暖、友好,并且没有骚扰的的环境,这样每个人都能尽最大努力贡献。
-为了这个目的,我们的项目遵循“贡献者契约”,这个契约是根据
-@url{http://contributor-covenant.org/}制定的。你可以在源代码目录里的
-@file{CODE-OF-CONDUCT}文件里找到一份本地版。
-
-贡献者在提交补丁和网上交流时不需要使用法律认可的名字。他们可以使用任何名字或者假
-名。
-
-@menu
-* 从Git编译:: 最新的并且最好的.
-* 在安装之前运行Guix:: 黑客技巧。
-* 完美的配置:: 正确的工具。
-* 打包指导:: Growing the distribution.
-* 代码风格:: 开发者的卫生情况
-* 提交补丁:: 分享你的工作。
-@end menu
-
-@node 从Git编译
-@section 从Git编译
-
-如果你想折腾Guix本身,建议使用Git仓库里最新的版本:
-
-@example
-git clone https://git.savannah.gnu.org/git/guix.git
-@end example
-
-当从Git检出构建Guix时,除安装指导(@pxref{Requirements})里提及的软件包之外还需
-要这些包。
-
-@itemize
-@item @url{http://gnu.org/software/autoconf/, GNU Autoconf};
-@item @url{http://gnu.org/software/automake/, GNU Automake};
-@item @url{http://gnu.org/software/gettext/, GNU Gettext};
-@item @url{http://gnu.org/software/texinfo/, GNU Texinfo};
-@item @url{http://www.graphviz.org/, Graphviz};
-@item @url{http://www.gnu.org/software/help2man/, GNU Help2man (可选)}。
-@end itemize
-
-设置Guix开发环境的最简单的方式当然是使用Guix!下面这些命令启动一个shell,所有的
-依赖和环境变量都为折腾Guix设置好了:
-
-@example
-guix environment guix
-@end example
-
-这个命令更多的信息请参考@xref{Invoking guix environment}。额外的依赖可以通过
-@option{--ad-hoc}选项添加:
-
-@example
-guix environment guix --ad-hoc help2man git strace
-@end example
-
-运行 @command{./bootstrap} 以使用Autoconf和Automake生成编译系统的基础框架。如果
-你的得到这样的错误:
-
-@example
-configure.ac:46: error: possibly undefined macro: PKG_CHECK_MODULES
-@end example
-
-@noindent
-它可能意味着Autoconf无法找到由pkg-config提供的@file{pkg.m4}。请确保@file{pkg.m4}
-可用。由Guile提供的@file{guile.m4}宏也类似。假如你的Automake安装在
-@file{/usr/local},那么它不会从@file{/usr/share}里寻找@file{.m4}文件。这种情况下,
-你必须执行下面这个命令:
-
-@example
-export ACLOCAL_PATH=/usr/share/aclocal
-@end example
-
-参考@xref{Macro Search Path,,, automake, The GNU Automake Manual}.
-
-然后,像正常一样运行@command{./configure}。确保提供
-@code{--localstatedir=@var{directory}}参数,@var{directory}是你当前系统的
-@code{localstatedir}的值。(@pxref{The Store})
-
-最后,用@code{make check}执行测试(@pxref{Running the Test Suite})。如果遇到任
-何错误,请参考“安装指导”(@pxref{Installation})或者给
-@email{guix-devel@@gnu.org, 邮件列表}发邮件。
-
-
-@node 在安装之前运行Guix
-@section 在安装之前运行Guix
-
-为了保持一个合适的工作环境,你会发现在你的本地代码树里测试修改而不用安装它们会很
-有用。TODO: So that you can distinguish between your ``end-user'' hat and your
-``motley'' costume.
-
-这样,即使你没有运行@code{make install},所有的命令行工具都可以使用。为此,你先
-要有一个包含全部依赖的环境(@pxref{从Git编译}),然后,为所有的命令添加
-前缀@command{./pre-inst-env}(@file{pre-inst-env}脚本在Guix编译树的最顶层,它由
-@command{./configure}生成),如@footnote{@command{sudo}命令的@option{-E}参数
-确保@code{GUILE_LOAD_PATH}被正确设置,从而@command{guix-daemon}和它使用的工具可
-以找到它们需要的Guile模块。}:
-
-@example
-$ sudo -E ./pre-inst-env guix-daemon --build-users-group=guixbuild
-$ ./pre-inst-env guix build hello
-@end example
-
-@noindent
-类似的,对于使用Guix模块的Guile会话:
-
-@example
-$ ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))'
-
-;;; ("x86_64-linux")
-@end example
-
-@noindent
-@cindex REPL
-@cindex read-eval-print loop
-@dots{} and for a REPL (@pxref{Using Guile Interactively,,, guile, Guile
-Reference Manual}):
-
-@example
-$ ./pre-inst-env guile
-scheme@@(guile-user)> ,use(guix)
-scheme@@(guile-user)> ,use(gnu)
-scheme@@(guile-user)> (define snakes
- (fold-packages
- (lambda (package lst)
- (if (string-prefix? "python"
- (package-name package))
- (cons package lst)
- lst))
- '()))
-scheme@@(guile-user)> (length snakes)
-$1 = 361
-@end example
-
-@command{pre-inst-env}脚本设置为此好了所有必要的的环境变量,包括@env{PATH}和
-@env{GUILE_LOAD_PATH}。
-
-@command{./pre-inst-env guix pull} @emph{不} 会更新本地源代码树,它只更新符号链
-接@file{~/.config/guix/current} (@pxref{Invoking guix pull})。如果你想更新本地源
-代码树,请运行@command{git pull}。
-
-
-@node 完美的配置
-@section 完美的配置
-
-折腾Guix的完美配置也是折腾Guile的完美配置@pxref{Using Guile in Emacs,,, guile,
-Guile Reference Manual})。首先,你需要的不仅是一个编辑器,你需要
-@url{http://www.gnu.org/software/emacs, Emacs},以及美妙的
-@url{http://nongnu.org/geiser/, Geiser}。为此,请运行:
-
-@example
-guix package -i emacs guile emacs-geiser
-@end example
-
-Geiser允许在Emacs里进行交互式的、增长式的开发:buffer里的代码补全和执行,获取一
-行的文档(docstrings),上下文敏感的补全,@kbd{M-.}跳转到对象定义,测试代码的
-REPL,及更多(@pxref{Introduction,,, geiser, Geiser User Manual})。为了方便的
-Guix开发,请确保修改Guile的加载路径(load path)以使其能从你的项目里找到源代码文
-件。
-
-@lisp
-;; @r{假设Guix项目在 ~/src/guix.}
-(with-eval-after-load 'geiser-guile
- (add-to-list 'geiser-guile-load-path "~/src/guix"))
-@end lisp
-
-真正编辑代码时别忘了Emacs自带了方便的Scheme模式。而且,一定不要错过
-@url{http://www.emacswiki.org/emacs/ParEdit, Paredit}。它提供了直接操作语法树的
-的功能,例如,用S-表达式替换父节点,为S-表达式添加、删除前后的括号,删除后面的S-
-表达式,等等。
-
-@cindex 代码片段
-@cindex 模板
-@cindex reducing boilerplate
-在@file{etc/snippets}文件夹里,我们还为普通的git commit信息和软件包定义提供模板。
-这些模板可以通过@url{http://joaotavora.github.io/yasnippet/, YASnippet}使用,它
-可以把短的触发字符串扩展成交互式的文字片段。你可能希望将这个文件夹添加到Emacs的
-@var{yas-snippet-dirs}变量里。
-
-@lisp
-;; @r{假设Guix项目在 ~/src/guix.}
-(with-eval-after-load 'yasnippet
- (add-to-list 'yas-snippet-dirs "~/src/guix/etc/snippets"))
-@end lisp
-
-commit信息片段显示staged文件需要依赖@url{https://magit.vc/, Magit}。编辑commit信
-息时,输入@code{add},然后按@kbd{TAB}就可以插入一段用于新增软件包的模板;输入
-@code{update},然后按@kbd{TAB}可以插入一段更新软件包的模板;输入@code{https}然后
-按@kbd{TAB}可以插入一段修改主页URI为HTTPS的模板。
-
-@code{scheme-mode}最重要的模板可以通过输入@code{package...},然后按@kbd{TAB}触发。
-这个片段还插入了触发字符串@code{origin...},以进一步展开。@code{origin}片段更进
-一步的可能插入其它以@code{...}结尾的触发字符串,它们可以被继续展开。
-
-
-@node 打包指导
-@section 打包指导
-
-@cindex 软件包, 创建
-这个GNU发行版正在开发的早期阶段,可能缺少一些你喜欢的软件。这个章节介绍你可以怎
-样帮助这个发行版成长。
-
-自由软件通常以@dfn{源代码包}的形式分发,通常是包含完整代码的@file{tar.gz}包。添
-加软件包到这个发行版意味着两件事:添加描述如何编译包的@dfn{配方}和一系列依赖软件,
-以及添加配方之外的@dfn{软件包元数据},如一段文字描述和证书信息。
-
-在Guix里所有这些信息都包含在@dfn{软件包定义}里。软件包定义提供了软件包的高层视角。
-它们使用Scheme编程语言编写,事实上,对每个软件包我们都定义一个绑定到软件包定义的
-的变量,并且从模块(@pxref{Package Modules})中导出那个变量。然而,深入的Scheme
-知识@emph{不}是创建软件包的前提条件。若要了解软件包的更多信息,@pxref{Defining
-Packages}。
-
-一旦软件包定义准备好了,并且包存在Guix代码树的一个文件里,你可以用@command{guix
-build} (@pxref{Invoking guix build})命令测试它。假设这个新软件包的名字叫做
-@code{gnew},你可以在Guix编译树里运行这个命令(@pxref{在安装之前运行Guix}):
-
-@example
-./pre-inst-env guix build gnew --keep-failed
-@end example
-
-使用@code{--keep-failed}参数会保留失败的编译树,这可以使调试编译错误更容易。
-@code{--log-file}也是一个调试时很有用的参数,它可以用来访问编译日志。
-
-如果@command{guix}命令找不到这个软件包,那可能是因为源文件包含语法错误,或者缺少
-导出软件包的@code{define-public}语句。为了查找错误,你可以用Guile导入这个模块以
-了解这个错误的详情:
-
-@example
-./pre-inst-env guile -c '(use-modules (gnu packages gnew))'
-@end example
-
-一旦你的软件包可以正确编译,请给我们发送补丁(@pxref{提交补丁})。当然,
-如果你需要帮助,我们也会很乐意帮助你。一旦补丁被提交到Guix仓库里,这个新的软件包
-会被自动地在支持的平台上编译@url{http://hydra.gnu.org/jobset/gnu/master, our
-continuous integration system}。
-
-@cindex substituter
-用户可以通过运行@command{guix pull}命令获取最新的软件包定义(@pxref{Invoking
-guix pull})。当@code{@value{SUBSTITUTE-SERVER}}编译好这些软件包之后,安装这些软
-件包时会自动从服务器(@pxref{Substitutes})上下载编译好的二进制包。唯一需要人工
-干预的地方是评审和应用代码补丁。
-
-
-@menu
-* 软件自由:: 什么可以进入这个发行版。
-* 软件包命名:: 名字里包含什么?
-* 版本号:: 当名字不够时
-* 简介和描述:: 帮助用户寻找合适的软件包
-* Python模块:: 接触英式的喜剧
-* Perl模块:: 小珍珠。
-* Java包:: 喝咖啡休息。
-* 字体:: 字体的乐趣。
-@end menu
-
-@node 软件自由
-@subsection 软件自由
-
-@c ===========================================================================
-@c
-@c This file was generated with po4a. Translate the source file.
-@c
-@c ===========================================================================
-@c Adapted from http://www.gnu.org/philosophy/philosophy.html.
-@cindex 自由软件
-开发GNU操作系统是为了用户拥有计算的自由。GNU是@dfn{自由软件},这意味着它有
-@url{http://www.gnu.org/philosophy/free-sw.html,四项重要的自由}:运行程序的自由,
-以源代码形式学习和修改程序的自由,原样重新分发副本的自由,和分发修改后的版本的自
-由。GNU发行版里包含的软件包只提供遵守这四项自由的软件。
-
-此外,GNU发行版遵循
-@url{http://www.gnu.org/distros/free-system-distribution-guidelines.html,自由软
-件发行版准则}。这些准则拒绝非自由的固件和对非自由软件的推荐,并讨论解决商标和专
-利的方法。
-
-某些上游的软件包源代码包含一小部分违反上述准则的可选的子集,比如这个子集本身就是
-非自由代码。这时,这些讨厌的代码需要用合适的补丁或者软件包定义(@pxref{Defining
-Packages})里的@code{origin}里的代码片段移除。这样,@code{guix build --source}就
-可以返回自由的源代码而不是未经修改的上游源代码。
-
-
-@node 软件包命名
-@subsection 软件包命名
-
-@cindex 软件包名字
-一个软件包事实上有两个名字:第一个是@emph{Scheme变量}的名字,即用
-@code{define-public}定义的名字。通过这个名字,软件包可以被Scheme代码找到,如用作
-其它软件包的输入。第二个名字是软件包定义里的@code{name}属性的字符串值。这个名字
-用于软件包管理命令,如:@command{guix package},@command{guix build}
-
-两个名字通常是相同的,常是上游项目名字转成小写字母并把下划线替换成连字符的结果。
-比如,GNUnet转成@code{gnunet},SDL_net转成@code{sdl-net}。
-
-我们不给库软件包添加@code{lib}前缀,除非它是项目官方名字的一部分。但是
-@pxref{Python模块}和@ref{Perl模块}有关于Python和Perl语言的特殊规则。
-
-字体软件包的名字处理起来不同,@pxref{字体}.
-
-
-@node 版本号
-@subsection 版本号
-
-@cindex 软件包版本
-我们通常只为每个自由软件的最新版本打包。但是有时候,比如对于版本不兼容的库,需要
-有同一个软件包的两个或更多版本。它们需要使用不同的Scheme变量名。我们为最新的版本
-使用@ref{软件包命名}里规定的名字,旧的版本使用加上后缀的名字,后缀是@code{-}
-和可以区分开版本号的版本号的最小前缀。
-
-软件包定义里的名字对于同一个软件包的所有版本都是相同的,并且不含有版本号。
-
-例如,GTK+的2.24.20和3.9.12两个版本可以这样打包:
-
-@example
-(define-public gtk+
- (package
- (name "gtk+")
- (version "3.9.12")
- ...))
-(define-public gtk+-2
- (package
- (name "gtk+")
- (version "2.24.20")
- ...))
-@end example
-如果我们还需要GTK+ 3.8.2,就这样打包
-@example
-(define-public gtk+-3.8
- (package
- (name "gtk+")
- (version "3.8.2")
- ...))
-@end example
-
-@c See <https://lists.gnu.org/archive/html/guix-devel/2016-01/msg00425.html>,
-@c for a discussion of what follows.
-@cindex 用于版本控制快照的版本号
-有时候,我们为软件包上游的版本控制系统(VCS)的快照而不是正式发布版打包。这是特
-殊情况,因为决定哪个是稳定版的权力应该属于上游开发者。然而,有时候这是必须的。那
-么,我们该如何决定写在@code{version}里的版本号呢?
-
-显然,我们需要让VCS快照的commit ID在版本号中体现出来,但是我们也需要确保版本号单
-调递增,以便@command{guix package --upgrade}决定哪个版本号更新。由于commit ID,
-尤其是Git的commit ID,不是单调递增的,我们添加一个每次升级快照时都手动增长的
-revision数字。最后的版本号字符串看起来是这样:
-
-@example
-2.0.11-3.cabba9e
- ^ ^ ^
- | | `-- 上游的commit ID
- | |
- | `--- Guix软件包的revision
- |
-最新的上游版本号
-@end example
-
-把@code{版本号}里的commit ID截短,比如只取7个数字,是一个好主意。它避免了美学上
-的烦恼(假设美学在这里很重要),以及操作系统限制引起的问题(比如Linux内核的127字
-节)。尽管如此,在@code{origin}里最好使用完整的commit ID,以避免混淆。
-
-@example
-(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@dots{}"))
- (file-name (git-file-name name version))))
- ;; @dots{}
- )))
-@end example
-
-@node 简介和描述
-@subsection 简介和描述
-
-@cindex 软件包描述
-@cindex 软件包简介
-我们已经看到,GNU@tie{}Guix里的每个软件包都包含一个简介(synopsis)和一个描述
-(description)(@pxref{Defining Packages})。简介和描述很重要:它们是
-@command{guix package --search}搜索的信息,并且是帮助用户决定一个软件包是否符合
-自己需求的重要信息。因此,打包的人应该关注怎样写它们的内容。
-
-简介必须以大写字母开头,并且不能以句号结尾。它们不能以 ``a'' 或者 ``the'' 等没有
-意义的词开头。例如 ``File-frobbing tool'' 要比 ``A tool that frobs files'' 更好。
-简介需要说明软件包是什么--如 ``Core GNU utilities (file, text, shell)'',或者
-它的用途--如 GNU@tie{}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.
-
-@cindex Texinfo markup, in package descriptions
-Descriptions can include Texinfo markup, which is useful to introduce
-ornaments such as @code{@@code} or @code{@@dfn}, bullet lists, or hyperlinks
-(@pxref{Overview,,, texinfo, GNU Texinfo}). However you should be careful
-when using some characters for example @samp{@@} and curly braces which are
-the basic special characters in Texinfo (@pxref{Special Characters,,,
-texinfo, GNU Texinfo}). User interfaces such as @command{guix package
---show} take care of rendering it appropriately.
-
-Synopses and descriptions are translated by volunteers
-@uref{http://translationproject.org/domain/guix-packages.html, at the
-Translation Project} so that as many users as possible can read them in
-their native language. User interfaces search them and display them in the
-language specified by the current locale.
-
-To allow @command{xgettext} to extract them as translatable strings,
-synopses and descriptions @emph{must be literal strings}. This means that
-you cannot use @code{string-append} or @code{format} to construct these
-strings:
-
-@lisp
-(package
- ;; @dots{}
- (synopsis "This is translatable")
- (description (string-append "This is " "*not*" " translatable.")))
-@end lisp
-
-Translation is a lot of work so, as a packager, please pay even more
-attention to your synopses and descriptions as every change may entail
-additional work for translators. In order to help them, it is possible to
-make recommendations or instructions visible to them by inserting special
-comments like this (@pxref{xgettext Invocation,,, gettext, GNU Gettext}):
-
-@example
-;; TRANSLATORS: "X11 resize-and-rotate" should not be translated.
-(description "ARandR is designed to provide a simple visual front end
-for the X11 resize-and-rotate (RandR) extension. @dots{}")
-@end example
-
-
-@node Python模块
-@subsection Python模块
-
-@cindex python
-We currently package Python 2 and Python 3, under the Scheme variable names
-@code{python-2} and @code{python} as explained in @ref{版本号}. To
-avoid confusion and naming clashes with other programming languages, it
-seems desirable that the name of a package for a Python module contains the
-word @code{python}.
-
-Some modules are compatible with only one version of Python, others with
-both. If the package Foo compiles only with Python 3, we name it
-@code{python-foo}; if it compiles only with Python 2, we name it
-@code{python2-foo}. If it is compatible with both versions, we create two
-packages with the corresponding names.
-
-If a project already contains the word @code{python}, we drop this; for
-instance, the module python-dateutil is packaged under the names
-@code{python-dateutil} and @code{python2-dateutil}. If the project name
-starts with @code{py} (e.g.@: @code{pytz}), we keep it and prefix it as
-described above.
-
-@subsubsection Specifying Dependencies
-@cindex inputs, for Python packages
-
-Dependency information for Python packages is usually available in the
-package source tree, with varying degrees of accuracy: in the
-@file{setup.py} file, in @file{requirements.txt}, or in @file{tox.ini}.
-
-Your mission, when writing a recipe for a Python package, is to map these
-dependencies to the appropriate type of ``input'' (@pxref{package Reference,
-inputs}). Although the @code{pypi} importer normally does a good job
-(@pxref{Invoking guix import}), you may want to check the following check
-list to determine which dependency goes where.
-
-@itemize
-
-@item
-We currently package Python 2 with @code{setuptools} and @code{pip}
-installed like Python 3.4 has per default. Thus you don't need to specify
-either of these as an input. @command{guix lint} will warn you if you do.
-
-@item
-Python dependencies required at run time go into @code{propagated-inputs}.
-They are typically defined with the @code{install_requires} keyword in
-@file{setup.py}, or in the @file{requirements.txt} file.
-
-@item
-Python packages required only at build time---e.g., those listed with the
-@code{setup_requires} keyword in @file{setup.py}---or only for
-testing---e.g., those in @code{tests_require}---go into
-@code{native-inputs}. The rationale is that (1) they do not need to be
-propagated because they are not needed at run time, and (2) in a
-cross-compilation context, it's the ``native'' input that we'd want.
-
-Examples are the @code{pytest}, @code{mock}, and @code{nose} test
-frameworks. Of course if any of these packages is also required at
-run-time, it needs to go to @code{propagated-inputs}.
-
-@item
-Anything that does not fall in the previous categories goes to
-@code{inputs}, for example programs or C libraries required for building
-Python packages containing C extensions.
-
-@item
-If a Python package has optional dependencies (@code{extras_require}), it is
-up to you to decide whether to add them or not, based on their
-usefulness/overhead ratio (@pxref{提交补丁, @command{guix size}}).
-
-@end itemize
-
-
-@node Perl模块
-@subsection Perl模块
-
-@cindex perl
-Perl programs standing for themselves are named as any other package, using
-the lowercase upstream name. For Perl packages containing a single class,
-we use the lowercase class name, replace all occurrences of @code{::} by
-dashes and prepend the prefix @code{perl-}. So the class @code{XML::Parser}
-becomes @code{perl-xml-parser}. Modules containing several classes keep
-their lowercase upstream name and are also prepended by @code{perl-}. Such
-modules tend to have the word @code{perl} somewhere in their name, which
-gets dropped in favor of the prefix. For instance, @code{libwww-perl}
-becomes @code{perl-libwww}.
-
-
-@node Java包
-@subsection Java包
-
-@cindex java
-Java programs standing for themselves are named as any other package, using
-the lowercase upstream name.
-
-To avoid confusion and naming clashes with other programming languages, it
-is desirable that the name of a package for a Java package is prefixed with
-@code{java-}. If a project already contains the word @code{java}, we drop
-this; for instance, the package @code{ngsjava} is packaged under the name
-@code{java-ngs}.
-
-For Java packages containing a single class or a small class hierarchy, we
-use the lowercase class name, replace all occurrences of @code{.} by dashes
-and prepend the prefix @code{java-}. So the class @code{apache.commons.cli}
-becomes package @code{java-apache-commons-cli}.
-
-
-@node 字体
-@subsection 字体
-
-@cindex fonts
-For fonts that are in general not installed by a user for typesetting
-purposes, or that are distributed as part of a larger software package, we
-rely on the general packaging rules for software; for instance, this applies
-to the fonts delivered as part of the X.Org system or fonts that are part of
-TeX Live.
-
-To make it easier for a user to search for fonts, names for other packages
-containing only fonts are constructed as follows, independently of the
-upstream package name.
-
-The name of a package containing only one font family starts with
-@code{font-}; it is followed by the foundry name and a dash @code{-} if the
-foundry is known, and the font family name, in which spaces are replaced by
-dashes (and as usual, all upper case letters are transformed to lower
-case). For example, the Gentium font family by SIL is packaged under the
-name @code{font-sil-gentium}.
-
-For a package containing several font families, the name of the collection
-is used in the place of the font family name. For instance, the Liberation
-fonts consist of three families, Liberation Sans, Liberation Serif and
-Liberation Mono. These could be packaged separately under the names
-@code{font-liberation-sans} and so on; but as they are distributed together
-under a common name, we prefer to package them together as
-@code{font-liberation}.
-
-In the case where several formats of the same font family or font collection
-are packaged separately, a short form of the format, prepended by a dash, is
-added to the package name. We use @code{-ttf} for TrueType fonts,
-@code{-otf} for OpenType fonts and @code{-type1} for PostScript Type 1
-fonts.
-
-
-@node 代码风格
-@section 代码风格
-
-In general our code follows the GNU Coding Standards (@pxref{Top,,,
-standards, GNU Coding Standards}). However, they do not say much about
-Scheme, so here are some additional rules.
-
-@menu
-* Programming Paradigm:: How to compose your elements.
-* Modules:: Where to store your code?
-* Data Types and Pattern Matching:: Implementing data structures.
-* Formatting Code:: Writing conventions.
-@end menu
-
-@node Programming Paradigm
-@subsection Programming Paradigm
-
-Scheme code in Guix is written in a purely functional style. One exception
-is code that involves input/output, and procedures that implement low-level
-concepts, such as the @code{memoize} procedure.
-
-@node Modules
-@subsection Modules
-
-Guile modules that are meant to be used on the builder side must live in the
-@code{(guix build @dots{})} name space. They must not refer to other Guix
-or GNU modules. However, it is OK for a ``host-side'' module to use a
-build-side module.
-
-Modules that deal with the broader GNU system should be in the @code{(gnu
-@dots{})} name space rather than @code{(guix @dots{})}.
-
-@node Data Types and Pattern Matching
-@subsection Data Types and Pattern Matching
-
-The tendency in classical Lisp is to use lists to represent everything, and
-then to browse them ``by hand'' using @code{car}, @code{cdr}, @code{cadr},
-and co. There are several problems with that style, notably the fact that
-it is hard to read, error-prone, and a hindrance to proper type error
-reports.
-
-Guix code should define appropriate data types (for instance, using
-@code{define-record-type*}) rather than abuse lists. In addition, it should
-use pattern matching, via Guile’s @code{(ice-9 match)} module, especially
-when matching lists.
-
-@node Formatting Code
-@subsection Formatting Code
-
-@cindex formatting code
-@cindex coding style
-When writing Scheme code, we follow common wisdom among Scheme programmers.
-In general, we follow the @url{http://mumble.net/~campbell/scheme/style.txt,
-Riastradh's Lisp Style Rules}. This document happens to describe the
-conventions mostly used in Guile’s code too. It is very thoughtful and well
-written, so please do read it.
-
-Some special forms introduced in Guix, such as the @code{substitute*} macro,
-have special indentation rules. These are defined in the
-@file{.dir-locals.el} file, which Emacs automatically uses. Also note that
-Emacs-Guix provides @code{guix-devel-mode} mode that indents and highlights
-Guix code properly (@pxref{Development,,, emacs-guix, The Emacs-Guix
-Reference Manual}).
-
-@cindex indentation, of code
-@cindex formatting, of code
-If you do not use Emacs, please make sure to let your editor knows these
-rules. To automatically indent a package definition, you can also run:
-
-@example
-./etc/indent-code.el gnu/packages/@var{file}.scm @var{package}
-@end example
-
-@noindent
-This automatically indents the definition of @var{package} in
-@file{gnu/packages/@var{file}.scm} by running Emacs in batch mode. To
-indent a whole file, omit the second argument:
-
-@example
-./etc/indent-code.el gnu/services/@var{file}.scm
-@end example
-
-@cindex Vim, Scheme code editing
-If you are editing code with Vim, we recommend that you run @code{:set
-autoindent} so that your code is automatically indented as you type.
-Additionally, @uref{https://www.vim.org/scripts/script.php?script_id=3998,
-@code{paredit.vim}} may help you deal with all these parentheses.
-
-We require all top-level procedures to carry a docstring. This requirement
-can be relaxed for simple private procedures in the @code{(guix build
-@dots{})} name space, though.
-
-Procedures should not have more than four positional parameters. Use
-keyword parameters for procedures that take more than four parameters.
-
-
-@node 提交补丁
-@section 提交补丁
-
-Development is done using the Git distributed version control system. Thus,
-access to the repository is not strictly necessary. We welcome
-contributions in the form of patches as produced by @code{git format-patch}
-sent to the @email{guix-patches@@gnu.org} mailing list.
-
-This mailing list is backed by a Debbugs instance accessible at
-@uref{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 @code{@var{NNN}@@debbugs.gnu.org}, where @var{NNN} is the tracking
-number (@pxref{Sending a Patch Series}).
-
-Please write commit logs in the ChangeLog format (@pxref{Change Logs,,,
-standards, GNU Coding Standards}); you can check the commit history for
-examples.
-
-Before submitting a patch that adds or modifies a package definition, please
-run through this check list:
-
-@enumerate
-@item
-If the authors of the packaged software provide a cryptographic signature
-for the release tarball, make an effort to verify the authenticity of the
-archive. For a detached GPG signature file this would be done with the
-@code{gpg --verify} command.
-
-@item
-Take some time to provide an adequate synopsis and description for the
-package. @xref{简介和描述}, for some guidelines.
-
-@item
-Run @code{guix lint @var{package}}, where @var{package} is the name of the
-new or modified package, and fix any errors it reports (@pxref{Invoking guix
-lint}).
-
-@item
-Make sure the package builds on your platform, using @code{guix build
-@var{package}}.
-
-@item
-We recommend you also try building the package on other supported
-platforms. As you may not have access to actual hardware platforms, we
-recommend using the @code{qemu-binfmt-service-type} to emulate them. In
-order to enable it, add the following service to the list of services in
-your @code{operating-system} configuration:
-
-@example
-(service qemu-binfmt-service-type
- (qemu-binfmt-configuration
- (platforms (lookup-qemu-platforms "arm" "aarch64" "mips64el"))
- (guix-support? #t)))
-@end example
-
-Then reconfigure your system.
-
-You can then build packages for different platforms by specifying the
-@code{--system} option. For example, to build the "hello" package for the
-armhf, aarch64, or mips64 architectures, you would run the following
-commands, respectively:
-@example
-guix build --system=armhf-linux --rounds=2 hello
-guix build --system=aarch64-linux --rounds=2 hello
-guix build --system=mips64el-linux --rounds=2 hello
-@end example
-
-@item
-@cindex bundling
-Make sure the package does not use bundled copies of software already
-available as separate packages.
-
-Sometimes, packages include copies of the source code of their dependencies
-as a convenience for users. However, as a distribution, we want to make
-sure that such packages end up using the copy we already have in the
-distribution, if there is one. This improves resource usage (the dependency
-is built and stored only once), and allows the distribution to make
-transverse changes such as applying security updates for a given software
-package in a single place and have them affect the whole system---something
-that bundled copies prevent.
-
-@item
-Take a look at the profile reported by @command{guix size} (@pxref{Invoking
-guix size}). This will allow you to notice references to other packages
-unwillingly retained. It may also help determine whether to split the
-package (@pxref{Packages with Multiple Outputs}), and which optional
-dependencies should be used. In particular, avoid adding @code{texlive} as
-a dependency: because of its extreme size, use @code{texlive-tiny} or
-@code{texlive-union} instead.
-
-@item
-For important changes, check that dependent package (if applicable) are not
-affected by the change; @code{guix refresh --list-dependent @var{package}}
-will help you do that (@pxref{Invoking guix refresh}).
-
-@c See <https://lists.gnu.org/archive/html/guix-devel/2016-10/msg00933.html>.
-@cindex branching strategy
-@cindex rebuild scheduling strategy
-Depending on the number of dependent packages and thus the amount of
-rebuilding induced, commits go to different branches, along these lines:
-
-@table @asis
-@item 300 dependent packages or less
-@code{master} branch (non-disruptive changes).
-
-@item between 300 and 1,200 dependent packages
-@code{staging} branch (non-disruptive changes). This branch is intended to
-be merged in @code{master} every 3 weeks or so. Topical changes (e.g., an
-update of the GNOME stack) can instead go to a specific branch (say,
-@code{gnome-updates}).
-
-@item more than 1,200 dependent packages
-@code{core-updates} branch (may include major and potentially disruptive
-changes). This branch is intended to be merged in @code{master} every 2.5
-months or so.
-@end table
-
-All these branches are @uref{https://hydra.gnu.org/project/gnu, tracked by
-our build farm} and merged into @code{master} once everything has been
-successfully built. This allows us to fix issues before they hit users, and
-to reduce the window during which pre-built binaries are not available.
-
-@c TODO: It would be good with badges on the website that tracks these
-@c branches. Or maybe even a status page.
-Generally, branches other than @code{master} are considered @emph{frozen} if
-there has been a recent evaluation, or there is a corresponding @code{-next}
-branch. Please ask on the mailing list or IRC if unsure where to place a
-patch.
-
-@item
-@cindex determinism, of build processes
-@cindex reproducible builds, checking
-Check whether the package's build process is deterministic. This typically
-means checking whether an independent build of the package yields the exact
-same result that you obtained, bit for bit.
-
-A simple way to do that is by building the same package several times in a
-row on your machine (@pxref{Invoking guix build}):
-
-@example
-guix build --rounds=2 my-package
-@end example
-
-This is enough to catch a class of common non-determinism issues, such as
-timestamps or randomly-generated output in the build result.
-
-Another option is to use @command{guix challenge} (@pxref{Invoking guix
-challenge}). You may run it once the package has been committed and built
-by @code{@value{SUBSTITUTE-SERVER}} to check whether it obtains the same
-result as you did. Better yet: Find another machine that can build it and
-run @command{guix publish}. Since the remote build machine is likely
-different from yours, this can catch non-determinism issues related to the
-hardware---e.g., use of different instruction set extensions---or to the
-operating system kernel---e.g., reliance on @code{uname} or @file{/proc}
-files.
-
-@item
-When writing documentation, please use gender-neutral wording when referring
-to people, such as @uref{https://en.wikipedia.org/wiki/Singular_they,
-singular ``they''@comma{} ``their''@comma{} ``them''}, and so forth.
-
-@item
-Verify that your patch contains only one set of related changes. Bundling
-unrelated changes together makes reviewing harder and slower.
-
-Examples of unrelated changes include the addition of several packages, or a
-package update along with fixes to that package.
-
-@item
-Please follow our code formatting rules, possibly running the
-@command{etc/indent-code.el} script to do that automatically for you
-(@pxref{Formatting Code}).
-
-@item
-When possible, use mirrors in the source URL (@pxref{Invoking guix
-download}). Use reliable URLs, not generated ones. For instance, GitHub
-archives are not necessarily identical from one generation to the next, so
-in this case it's often better to clone the repository. Don't use the
-@command{name} field in the URL: it is not very useful and if the name
-changes, the URL will probably be wrong.
-
-@end enumerate
-
-When posting a patch to the mailing list, use @samp{[PATCH] @dots{}} as a
-subject. You may use your email client or the @command{git send-email}
-command (@pxref{Sending a Patch Series}). We prefer to get patches in plain
-text messages, either inline or as MIME attachments. You are advised to pay
-attention if your email client changes anything like line breaks or
-indentation which could potentially break the patches.
-
-When a bug is resolved, please close the thread by sending an email to
-@email{@var{NNN}-done@@debbugs.gnu.org}.
-
-@unnumberedsubsec Sending a Patch Series
-@anchor{Sending a Patch Series}
-@cindex patch series
-@cindex @code{git send-email}
-@cindex @code{git-send-email}
-
-@c Debbugs bug: https://debbugs.gnu.org/db/15/15361.html
-When sending a patch series (e.g., using @code{git send-email}), please
-first send one message to @email{guix-patches@@gnu.org}, and then send
-subsequent patches to @email{@var{NNN}@@debbugs.gnu.org} to make sure they
-are kept together. See @uref{https://debbugs.gnu.org/Advanced.html, the
-Debbugs documentation} for more information.