We want to provide a warm, friendly, and harassment-free environment, so
that anyone can contribute to the best of their abilities. To this end
our project uses a ``Contributor Covenant'', which was adapted from
-@url{http://contributor-covenant.org/}. You can find a local version in
+@url{https://contributor-covenant.org/}. You can find a local version in
the @file{CODE-OF-CONDUCT} file in the source tree.
Contributors are not required to use their legal name in patches and
* Building from Git:: The latest and greatest.
* Running Guix Before It Is Installed:: Hacker tricks.
* The Perfect Setup:: The right tools.
+* Packaging Guidelines:: Growing the distribution.
* Coding Style:: Hygiene of the contributor.
* Submitting Patches:: Share your work.
+* Tracking Bugs and Patches:: Using Debbugs.
+* Commit Access:: Pushing to the official repository.
@end menu
@node Building from Git
git clone https://git.savannah.gnu.org/git/guix.git
@end example
-When building Guix from a checkout,
-the following packages are required in addition to those mentioned in
-the installation instructions (@pxref{Requirements}).
+@cindex authentication, of a Guix checkout
+How do you ensure that you obtained a genuine copy of the repository?
+Guix itself provides a tool to @dfn{authenticate} your checkout, but you
+must first make sure this tool is genuine in order to ``bootstrap'' the
+trust chain. To do that, run:
-@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 (optional)}.
-@end itemize
+@c XXX: Adjust instructions when there's a known tag to start from.
+@example
+git verify-commit `git log --format=%H build-aux/git-authenticate.scm`
+@end example
+
+The output must look something like:
+
+@example
+gpg: Signature made Fri 27 Dec 2019 01:27:41 PM CET
+gpg: using RSA key 3CE464558A84FDC69DB40CFB090B11993D9AEBB5
+@dots{}
+gpg: Signature made Fri 27 Dec 2019 01:25:22 PM CET
+gpg: using RSA key 3CE464558A84FDC69DB40CFB090B11993D9AEBB5
+@dots{}
+@end example
+
+@noindent
+... meaning that changes to this file are all signed with key
+@code{3CE464558A84FDC69DB40CFB090B11993D9AEBB5} (you may need to fetch
+this key from a key server, if you have not done it yet).
+
+From there on, you can authenticate all the commits included in your
+checkout by running:
+
+@example
+make authenticate
+@end example
+
+The first run takes a couple of minutes, but subsequent runs are faster.
+
+@quotation Note
+You are advised to run @command{make authenticate} after every
+@command{git pull} invocation. This ensures you keep receiving valid
+changes to the repository
+@end quotation
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
hack on Guix:
@example
-guix environment guix
+guix environment guix --pure
@end example
@xref{Invoking guix environment}, for more information on that command.
-Extra dependencies can be added with @option{--ad-hoc}:
+
+If you are unable to use Guix when building Guix from a checkout, the
+following are the required packages in addition to those mentioned in the
+installation instructions (@pxref{Requirements}).
+
+@itemize
+@item @url{https://gnu.org/software/autoconf/, GNU Autoconf};
+@item @url{https://gnu.org/software/automake/, GNU Automake};
+@item @url{https://gnu.org/software/gettext/, GNU Gettext};
+@item @url{https://gnu.org/software/texinfo/, GNU Texinfo};
+@item @url{https://www.graphviz.org/, Graphviz};
+@item @url{https://www.gnu.org/software/help2man/, GNU Help2man (optional)}.
+@end itemize
+
+On Guix, extra dependencies can be added by instead running @command{guix
+environment} with @option{--ad-hoc}:
@example
-guix environment guix --ad-hoc help2man git strace
+guix environment guix --pure --ad-hoc help2man git strace
@end example
Run @command{./bootstrap} to generate the build system infrastructure
Then, run @command{./configure} as usual. Make sure to pass
@code{--localstatedir=@var{directory}} where @var{directory} is the
@code{localstatedir} value used by your current installation (@pxref{The
-Store}, for information about this).
+Store}, for information about this). We recommend to use the value
+@code{/var}.
Finally, you have to invoke @code{make check} to run tests
(@pxref{Running the Test Suite}). If anything
``end-user'' hat and your ``motley'' costume.
To that end, all the command-line tools can be used even if you have not
-run @code{make install}. To do that, prefix each command with
+run @code{make install}. To do that, you first need to have an environment
+with all the dependencies available (@pxref{Building from Git}), and then
+simply prefix each command with
@command{./pre-inst-env} (the @file{pre-inst-env} script lives in the
-top build tree of Guix), as in@footnote{The @option{-E} flag to
+top build tree of Guix; it is generated by @command{./configure}).
+An example@footnote{The @option{-E} flag to
@command{sudo} guarantees that @code{GUILE_LOAD_PATH} is correctly set
such that @command{guix-daemon} and the tools it uses can find the Guile
modules they need.}:
@end example
@noindent
-Similarly, for a Guile session using the Guix modules:
+Similarly, an example for a Guile session using the Guix modules:
@example
$ ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))'
The Perfect Setup to hack on Guix is basically the perfect setup used
for Guile hacking (@pxref{Using Guile in Emacs,,, guile, Guile Reference
Manual}). First, you need more than an editor, you need
-@url{http://www.gnu.org/software/emacs, Emacs}, empowered by the
-wonderful @url{http://nongnu.org/geiser/, Geiser}.
+@url{https://www.gnu.org/software/emacs, Emacs}, empowered by the
+wonderful @url{https://nongnu.org/geiser/, Geiser}. To set that up, run:
+
+@example
+guix package -i emacs guile emacs-geiser
+@end example
Geiser allows for interactive and incremental development from within
Emacs: code compilation and evaluation from within buffers, access to
To actually edit the code, Emacs already has a neat Scheme mode. But in
addition to that, you must not miss
-@url{http://www.emacswiki.org/emacs/ParEdit, Paredit}. It provides
+@url{https://www.emacswiki.org/emacs/ParEdit, Paredit}. It provides
facilities to directly operate on the syntax tree, such as raising an
s-expression or wrapping it, swallowing or rejecting the following
s-expression, etc.
@cindex reducing boilerplate
We also provide templates for common git commit messages and package
definitions in the @file{etc/snippets} directory. These templates can
-be used with @url{http://joaotavora.github.io/yasnippet/, YASnippet} to
+be used with @url{https://joaotavora.github.io/yasnippet/, YASnippet} to
expand short trigger strings to interactive text snippets. You may want
to add the snippets directory to the @var{yas-snippet-dirs} variable in
Emacs.
display staged files. When editing a commit message type @code{add}
followed by @kbd{TAB} to insert a commit message template for adding a
package; type @code{update} followed by @kbd{TAB} to insert a template
-for updating a package.
+for updating a package; type @code{https} followed by @kbd{TAB} to
+insert a template for changing the home page URI of a package to HTTPS.
The main snippet for @code{scheme-mode} is triggered by typing
@code{package...} followed by @kbd{TAB}. This snippet also inserts the
@code{origin} snippet in turn may insert other trigger strings ending on
@code{...}, which also can be expanded further.
+@cindex insert or update copyright
+@cindex @code{M-x guix-copyright}
+@cindex @code{M-x copyright-update}
+Additionaly we provide insertion and automatic update of a copyright in
+@file{etc/copyright.el}. You may want to set your full name, mail, and
+load a file.
+
+@lisp
+(setq user-full-name "Alice Doe")
+(setq user-mail-address "alice@@mail.org")
+;; @r{Assuming the Guix checkout is in ~/src/guix.}
+(load-file "~/src/guix/etc/copyright.el")
+@end lisp
+
+To insert a copyright at the current line invoke @code{M-x guix-copyright}.
+
+To update a copyright you need to specify a @code{copyright-names-regexp}.
+
+@lisp
+(setq copyright-names-regexp
+ (format "%s <%s>" user-full-name user-mail-address))
+@end lisp
+
+You can check if your copyright is up to date by evaluating @code{M-x
+copyright-update}. If you want to do it automatically after each buffer
+save then add @code{(add-hook 'after-save-hook 'copyright-update)} in
+Emacs.
+
+@node Packaging Guidelines
+@section Packaging Guidelines
+
+@cindex packages, creating
+The GNU distribution is nascent and may well lack some of your favorite
+packages. This section describes how you can help make the distribution
+grow.
+
+Free software packages are usually distributed in the form of
+@dfn{source code tarballs}---typically @file{tar.gz} files that contain
+all the source files. Adding a package to the distribution means
+essentially two things: adding a @dfn{recipe} that describes how to
+build the package, including a list of other packages required to build
+it, and adding @dfn{package metadata} along with that recipe, such as a
+description and licensing information.
+
+In Guix all this information is embodied in @dfn{package definitions}.
+Package definitions provide a high-level view of the package. They are
+written using the syntax of the Scheme programming language; in fact,
+for each package we define a variable bound to the package definition,
+and export that variable from a module (@pxref{Package Modules}).
+However, in-depth Scheme knowledge is @emph{not} a prerequisite for
+creating packages. For more information on package definitions,
+@pxref{Defining Packages}.
+
+Once a package definition is in place, stored in a file in the Guix
+source tree, it can be tested using the @command{guix build} command
+(@pxref{Invoking guix build}). For example, assuming the new package is
+called @code{gnew}, you may run this command from the Guix build tree
+(@pxref{Running Guix Before It Is Installed}):
+
+@example
+./pre-inst-env guix build gnew --keep-failed
+@end example
+
+Using @code{--keep-failed} makes it easier to debug build failures since
+it provides access to the failed build tree. Another useful
+command-line option when debugging is @code{--log-file}, to access the
+build log.
+
+If the package is unknown to the @command{guix} command, it may be that
+the source file contains a syntax error, or lacks a @code{define-public}
+clause to export the package variable. To figure it out, you may load
+the module from Guile to get more information about the actual error:
+
+@example
+./pre-inst-env guile -c '(use-modules (gnu packages gnew))'
+@end example
+
+Once your package builds correctly, please send us a patch
+(@pxref{Submitting Patches}). Well, if you need help, we will be happy to
+help you too. Once the patch is committed in the Guix repository, the
+new package automatically gets built on the supported platforms by
+@url{@value{SUBSTITUTE-SERVER}, our continuous integration system}.
+
+@cindex substituter
+Users can obtain the new package definition simply by running
+@command{guix pull} (@pxref{Invoking guix pull}). When
+@code{@value{SUBSTITUTE-SERVER}} is done building the package, installing the
+package automatically downloads binaries from there
+(@pxref{Substitutes}). The only place where human intervention is
+needed is to review and apply the patch.
+
+
+@menu
+* Software Freedom:: What may go into the distribution.
+* Package Naming:: What's in a name?
+* Version Numbers:: When the name is not enough.
+* Synopses and Descriptions:: Helping users find the right package.
+* Python Modules:: A touch of British comedy.
+* Perl Modules:: Little pearls.
+* Java Packages:: Coffee break.
+* Rust Crates:: Beware of oxidation.
+* Fonts:: Fond of fonts.
+@end menu
+
+@node Software Freedom
+@subsection Software Freedom
+
+@c Adapted from http://www.gnu.org/philosophy/philosophy.html.
+@cindex free software
+The GNU operating system has been developed so that users can have
+freedom in their computing. GNU is @dfn{free software}, meaning that
+users have the @url{https://www.gnu.org/philosophy/free-sw.html,four
+essential freedoms}: to run the program, to study and change the program
+in source code form, to redistribute exact copies, and to distribute
+modified versions. Packages found in the GNU distribution provide only
+software that conveys these four freedoms.
+
+In addition, the GNU distribution follow the
+@url{https://www.gnu.org/distros/free-system-distribution-guidelines.html,free
+software distribution guidelines}. Among other things, these guidelines
+reject non-free firmware, recommendations of non-free software, and
+discuss ways to deal with trademarks and patents.
+
+Some otherwise free upstream package sources contain a small and optional
+subset that violates the above guidelines, for instance because this subset
+is itself non-free code. When that happens, the offending items are removed
+with appropriate patches or code snippets in the @code{origin} form of the
+package (@pxref{Defining Packages}). This way, @code{guix
+build --source} returns the ``freed'' source rather than the unmodified
+upstream source.
+
+
+@node Package Naming
+@subsection Package Naming
+
+@cindex package name
+A package has actually two names associated with it:
+First, there is the name of the @emph{Scheme variable}, the one following
+@code{define-public}. By this name, the package can be made known in the
+Scheme code, for instance as input to another package. Second, there is
+the string in the @code{name} field of a package definition. This name
+is used by package management commands such as
+@command{guix package} and @command{guix build}.
+
+Both are usually the same and correspond to the lowercase conversion of
+the project name chosen upstream, with underscores replaced with
+hyphens. For instance, GNUnet is available as @code{gnunet}, and
+SDL_net as @code{sdl-net}.
+
+We do not add @code{lib} prefixes for library packages, unless these are
+already part of the official project name. But @pxref{Python
+Modules} and @ref{Perl Modules} for special rules concerning modules for
+the Python and Perl languages.
+
+Font package names are handled differently, @pxref{Fonts}.
+
+
+@node Version Numbers
+@subsection Version Numbers
+
+@cindex package version
+We usually package only the latest version of a given free software
+project. But sometimes, for instance for incompatible library versions,
+two (or more) versions of the same package are needed. These require
+different Scheme variable names. We use the name as defined
+in @ref{Package Naming}
+for the most recent version; previous versions use the same name, suffixed
+by @code{-} and the smallest prefix of the version number that may
+distinguish the two versions.
+
+The name inside the package definition is the same for all versions of a
+package and does not contain any version number.
+
+For instance, the versions 2.24.20 and 3.9.12 of GTK+ may be packaged as follows:
+
+@lisp
+(define-public gtk+
+ (package
+ (name "gtk+")
+ (version "3.9.12")
+ ...))
+(define-public gtk+-2
+ (package
+ (name "gtk+")
+ (version "2.24.20")
+ ...))
+@end lisp
+If we also wanted GTK+ 3.8.2, this would be packaged as
+@lisp
+(define-public gtk+-3.8
+ (package
+ (name "gtk+")
+ (version "3.8.2")
+ ...))
+@end lisp
+
+@c See <https://lists.gnu.org/archive/html/guix-devel/2016-01/msg00425.html>,
+@c for a discussion of what follows.
+@cindex version number, for VCS snapshots
+Occasionally, we package snapshots of upstream's version control system
+(VCS) instead of formal releases. This should remain exceptional,
+because it is up to upstream developers to clarify what the stable
+release is. Yet, it is sometimes necessary. So, what should we put in
+the @code{version} field?
+
+Clearly, we need to make the commit identifier of the VCS snapshot
+visible in the version string, but we also need to make sure that the
+version string is monotonically increasing so that @command{guix package
+--upgrade} can determine which version is newer. Since commit
+identifiers, notably with Git, are not monotonically increasing, we add
+a revision number that we increase each time we upgrade to a newer
+snapshot. The resulting version string looks like this:
+
+@example
+2.0.11-3.cabba9e
+ ^ ^ ^
+ | | `-- upstream commit ID
+ | |
+ | `--- Guix package revision
+ |
+latest upstream version
+@end example
+
+It is a good idea to strip commit identifiers in the @code{version}
+field to, say, 7 digits. It avoids an aesthetic annoyance (assuming
+aesthetics have a role to play here) as well as problems related to OS
+limits such as the maximum shebang length (127 bytes for the Linux
+kernel). It is best to use the full commit identifiers in
+@code{origin}s, though, to avoid ambiguities. A typical package
+definition may look like this:
+
+@lisp
+(define my-package
+ (let ((commit "c3f29bc928d5900971f65965feaae59e1272a3f7")
+ (revision "1")) ;Guix package revision
+ (package
+ (version (git-version "0.9" revision commit))
+ (source (origin
+ (method git-fetch)
+ (uri (git-reference
+ (url "git://example.org/my-package.git")
+ (commit commit)))
+ (sha256 (base32 "1mbikn@dots{}"))
+ (file-name (git-file-name name version))))
+ ;; @dots{}
+ )))
+@end lisp
+
+@node Synopses and Descriptions
+@subsection Synopses and Descriptions
+
+@cindex package description
+@cindex package synopsis
+As we have seen before, each package in GNU@tie{}Guix includes a
+synopsis and a description (@pxref{Defining Packages}). Synopses and
+descriptions are important: They are what @command{guix package
+--search} searches, and a crucial piece of information to help users
+determine whether a given package suits their needs. Consequently,
+packagers should pay attention to what goes into them.
+
+Synopses must start with a capital letter and must not end with a
+period. They must not start with ``a'' or ``the'', which usually does
+not bring anything; for instance, prefer ``File-frobbing tool'' over ``A
+tool that frobs files''. The synopsis should say what the package
+is---e.g., ``Core GNU utilities (file, text, shell)''---or what it is
+used for---e.g., the synopsis for GNU@tie{}grep is ``Print lines
+matching a pattern''.
+
+Keep in mind that the synopsis must be meaningful for a very wide
+audience. For example, ``Manipulate alignments in the SAM format''
+might make sense for a seasoned bioinformatics researcher, but might be
+fairly unhelpful or even misleading to a non-specialized audience. It
+is a good idea to come up with a synopsis that gives an idea of the
+application domain of the package. In this example, this might give
+something like ``Manipulate nucleotide sequence alignments'', which
+hopefully gives the user a better idea of whether this is what they are
+looking for.
+
+Descriptions should take between five and ten lines. Use full
+sentences, and avoid using acronyms without first introducing them.
+Please avoid marketing phrases such as ``world-leading'',
+``industrial-strength'', and ``next-generation'', and avoid superlatives
+like ``the most advanced''---they are not helpful to users looking for a
+package and may even sound suspicious. Instead, try to be factual,
+mentioning use cases and features.
+
+@cindex Texinfo markup, in package descriptions
+Descriptions can include Texinfo markup, which is useful to introduce
+ornaments such as @code{@@code} or @code{@@dfn}, bullet lists, or
+hyperlinks (@pxref{Overview,,, texinfo, GNU Texinfo}). However you
+should be careful when using some characters for example @samp{@@} and
+curly braces which are the basic special characters in Texinfo
+(@pxref{Special Characters,,, texinfo, GNU Texinfo}). User interfaces
+such as @command{guix package --show} take care of rendering it
+appropriately.
+
+Synopses and descriptions are translated by volunteers
+@uref{https://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 Modules
+@subsection Python Modules
+
+@cindex python
+We currently package Python 2 and Python 3, under the Scheme variable names
+@code{python-2} and @code{python} as explained in @ref{Version Numbers}.
+To avoid confusion and naming clashes with other programming languages, it
+seems desirable that the name of a package for a Python module contains
+the word @code{python}.
+
+Some modules are compatible with only one version of Python, others with
+both. If the package Foo is compiled with Python 3, we name it
+@code{python-foo}. If it is compiled with Python 2, we name it
+@code{python2-foo}. Packages should be added when they are necessary;
+we don't add Python 2 variants of the package unless we are going to use
+them.
+
+If a project already contains the word @code{python}, we drop this;
+for instance, the module python-dateutil is packaged under the names
+@code{python-dateutil} and @code{python2-dateutil}. If the project name
+starts with @code{py} (e.g.@: @code{pytz}), we keep it and prefix it as
+described above.
+
+@subsubsection Specifying Dependencies
+@cindex inputs, for Python packages
+
+Dependency information for Python packages is usually available in the
+package source tree, with varying degrees of accuracy: in the
+@file{setup.py} file, in @file{requirements.txt}, or in @file{tox.ini}.
+
+Your mission, when writing a recipe for a Python package, is to map
+these dependencies to the appropriate type of ``input'' (@pxref{package
+Reference, inputs}). Although the @code{pypi} importer normally does a
+good job (@pxref{Invoking guix import}), you may want to check the
+following check list to determine which dependency goes where.
+
+@itemize
+
+@item
+We currently package Python 2 with @code{setuptools} and @code{pip}
+installed like Python 3.4 has per default. Thus you don't need to
+specify either of these as an input. @command{guix lint} will warn you
+if you do.
+
+@item
+Python dependencies required at run time go into
+@code{propagated-inputs}. They are typically defined with the
+@code{install_requires} keyword in @file{setup.py}, or in the
+@file{requirements.txt} file.
+
+@item
+Python packages required only at build time---e.g., those listed with
+the @code{setup_requires} keyword in @file{setup.py}---or only for
+testing---e.g., those in @code{tests_require}---go into
+@code{native-inputs}. The rationale is that (1) they do not need to be
+propagated because they are not needed at run time, and (2) in a
+cross-compilation context, it's the ``native'' input that we'd want.
+
+Examples are the @code{pytest}, @code{mock}, and @code{nose} test
+frameworks. Of course if any of these packages is also required at
+run-time, it needs to go to @code{propagated-inputs}.
+
+@item
+Anything that does not fall in the previous categories goes to
+@code{inputs}, for example programs or C libraries required for building
+Python packages containing C extensions.
+
+@item
+If a Python package has optional dependencies (@code{extras_require}),
+it is up to you to decide whether to add them or not, based on their
+usefulness/overhead ratio (@pxref{Submitting Patches, @command{guix
+size}}).
+
+@end itemize
+
+
+@node Perl Modules
+@subsection Perl Modules
+
+@cindex perl
+Perl programs standing for themselves are named as any other package,
+using the lowercase upstream name.
+For Perl packages containing a single class, we use the lowercase class name,
+replace all occurrences of @code{::} by dashes and prepend the prefix
+@code{perl-}.
+So the class @code{XML::Parser} becomes @code{perl-xml-parser}.
+Modules containing several classes keep their lowercase upstream name and
+are also prepended by @code{perl-}. Such modules tend to have the word
+@code{perl} somewhere in their name, which gets dropped in favor of the
+prefix. For instance, @code{libwww-perl} becomes @code{perl-libwww}.
+
+
+@node Java Packages
+@subsection Java Packages
+
+@cindex java
+Java programs standing for themselves are named as any other package,
+using the lowercase upstream name.
+
+To avoid confusion and naming clashes with other programming languages,
+it is desirable that the name of a package for a Java package is
+prefixed with @code{java-}. If a project already contains the word
+@code{java}, we drop this; for instance, the package @code{ngsjava} is
+packaged under the name @code{java-ngs}.
+
+For Java packages containing a single class or a small class hierarchy,
+we use the lowercase class name, replace all occurrences of @code{.} by
+dashes and prepend the prefix @code{java-}. So the class
+@code{apache.commons.cli} becomes package
+@code{java-apache-commons-cli}.
+
+
+@node Rust Crates
+@subsection Rust Crates
+
+@cindex rust
+Rust programs standing for themselves are named as any other package, using the
+lowercase upstream name.
+
+To prevent namespace collisions we prefix all other Rust packages with the
+@code{rust-} prefix. The name should be changed to lowercase as appropriate and
+dashes should remain in place.
+
+In the rust ecosystem it is common for multiple incompatible versions of a
+package to be used at any given time, so all packages should have a versioned
+suffix. If a package has passed version 1.0.0 then just the major version
+number is sufficient (e.g.@: @code{rust-clap-2}), otherwise the version suffix
+should contain both the major and minor version (e.g.@: @code{rust-rand-0.6}).
+
+Because of the difficulty in reusing rust packages as pre-compiled inputs for
+other packages the Cargo build system (@pxref{Build Systems,
+@code{cargo-build-system}}) presents the @code{#:cargo-inputs} and
+@code{cargo-development-inputs} keywords as build system arguments. It would be
+helpful to think of these as similar to @code{propagated-inputs} and
+@code{native-inputs}. Rust @code{dependencies} and @code{build-dependencies}
+should go in @code{#:cargo-inputs}, and @code{dev-dependencies} should go in
+@code{#:cargo-development-inputs}. If a Rust package links to other libraries
+then the standard placement in @code{inputs} and the like should be used.
+
+Care should be taken to ensure the correct version of dependencies are used; to
+this end we try to refrain from skipping the tests or using @code{#:skip-build?}
+when possible. Of course this is not always possible, as the package may be
+developed for a different Operating System, depend on features from the Nightly
+Rust compiler, or the test suite may have atrophied since it was released.
+
+
+@node Fonts
+@subsection Fonts
+
+@cindex fonts
+For fonts that are in general not installed by a user for typesetting
+purposes, or that are distributed as part of a larger software package,
+we rely on the general packaging rules for software; for instance, this
+applies to the fonts delivered as part of the X.Org system or fonts that
+are part of TeX Live.
+
+To make it easier for a user to search for fonts, names for other packages
+containing only fonts are constructed as follows, independently of the
+upstream package name.
+
+The name of a package containing only one font family starts with
+@code{font-}; it is followed by the foundry name and a dash @code{-}
+if the foundry is known, and the font family name, in which spaces are
+replaced by dashes (and as usual, all upper case letters are transformed
+to lower case).
+For example, the Gentium font family by SIL is packaged under the name
+@code{font-sil-gentium}.
+
+For a package containing several font families, the name of the collection
+is used in the place of the font family name.
+For instance, the Liberation fonts consist of three families,
+Liberation Sans, Liberation Serif and Liberation Mono.
+These could be packaged separately under the names
+@code{font-liberation-sans} and so on; but as they are distributed together
+under a common name, we prefer to package them together as
+@code{font-liberation}.
+
+In the case where several formats of the same font family or font collection
+are packaged separately, a short form of the format, prepended by a dash,
+is added to the package name. We use @code{-ttf} for TrueType fonts,
+@code{-otf} for OpenType fonts and @code{-type1} for PostScript Type 1
+fonts.
+
@node Coding Style
@section Coding Style
@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
+@url{https://mumble.net/~campbell/scheme/style.txt, Riastradh's Lisp
Style Rules}. This document happens to describe the conventions mostly
used in Guile’s code too. It is very thoughtful and well written, so
please do read it.
Thus, access to the repository is not strictly necessary. We welcome
contributions in the form of patches as produced by @code{git
format-patch} sent to the @email{guix-patches@@gnu.org} mailing list.
+Seasoned Guix developers may also want to look at the section on commit
+access (@pxref{Commit Access}).
-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}).
+This mailing list is backed by a Debbugs instance, which allows us to
+keep track of submissions (@pxref{Tracking Bugs and Patches}). Each
+message sent to that mailing list gets a new tracking number assigned;
+people can then follow up on the submission by sending email to
+@code{@var{NNN}@@debbugs.gnu.org}, where @var{NNN} is the tracking
+number (@pxref{Sending a Patch Series}).
Please write commit logs in the ChangeLog format (@pxref{Change Logs,,,
standards, GNU Coding Standards}); you can check the commit history for
Make sure the package builds on your platform, using @code{guix build
@var{package}}.
+@item
+We recommend you also try building the package on other supported
+platforms. As you may not have access to actual hardware platforms, we
+recommend using the @code{qemu-binfmt-service-type} to emulate them. In
+order to enable it, add the following service to the list of services in
+your @code{operating-system} configuration:
+
+@lisp
+(service qemu-binfmt-service-type
+ (qemu-binfmt-configuration
+ (platforms (lookup-qemu-platforms "arm" "aarch64"))
+ (guix-support? #t)))
+@end lisp
+
+Then reconfigure your system.
+
+You can then build packages for different platforms by specifying the
+@code{--system} option. For example, to build the "hello" package for
+the armhf, aarch64, or mips64 architectures, you would run the following
+commands, respectively:
+@example
+guix build --system=armhf-linux --rounds=2 hello
+guix build --system=aarch64-linux --rounds=2 hello
+@end example
+
@item
@cindex bundling
Make sure the package does not use bundled copies of software already
(@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.
+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
@item 300 dependent packages or less
@code{master} branch (non-disruptive changes).
-@item between 300 and 1,200 dependent packages
+@item between 300 and 1,800 dependent packages
@code{staging} branch (non-disruptive changes). This branch is intended
-to be merged in @code{master} every 3 weeks or so. Topical changes
+to be merged in @code{master} every 6 weeks or so. Topical changes
(e.g., an update of the GNOME stack) can instead go to a specific branch
(say, @code{gnome-updates}).
-@item more than 1,200 dependent packages
+@item more than 1,800 dependent packages
@code{core-updates} branch (may include major and potentially disruptive
changes). This branch is intended to be merged in @code{master} every
-2.5 months or so.
+6 months or so.
@end table
-All these branches are @uref{https://hydra.gnu.org/project/gnu,
+All these branches are @uref{@value{SUBSTITUTE-SERVER},
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
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{hydra.gnu.org} to check whether it obtains the same
+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
@command{etc/indent-code.el} script to do that automatically for you
(@pxref{Formatting Code}).
+@item
+When possible, use mirrors in the source URL (@pxref{Invoking guix download}).
+Use reliable URLs, not generated ones. For instance, GitHub archives are not
+necessarily identical from one generation to the next, so in this case it's
+often better to clone the repository. Don't use the @command{name} field in
+the URL: it is not very useful and if the name changes, the URL will probably
+be wrong.
+
+@item
+Check if Guix builds (@pxref{Building from Git}) and address the
+warnings, especially those about use of undefined symbols.
+
+@item
+Make sure your changes do not break Guix and simulate a @code{guix pull} with:
+@example
+guix pull --url=/path/to/your/checkout --profile=/tmp/guix.master
+@end example
+
@end enumerate
When posting a patch to the mailing list, use @samp{[PATCH] @dots{}} as
-a subject. 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.
+a subject, if your patch is to be applied on a branch other than
+@code{master}, say @code{core-updates}, specify it in the subject like
+@samp{[PATCH core-updates] @dots{}}. You may use your email client or
+the @command{git send-email} command (@pxref{Sending a Patch Series}).
+We prefer to get patches in plain text messages, either inline or as
+MIME attachments. You are advised to pay attention if your email client
+changes anything like line breaks or indentation which could potentially
+break the patches.
When a bug is resolved, please close the thread by sending an email to
@email{@var{NNN}-done@@debbugs.gnu.org}.
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.
+for more information. You can install @command{git send-email} with
+@command{guix install git:send-email}.
@c Debbugs bug: https://debbugs.gnu.org/db/15/15361.html
+
+@node Tracking Bugs and Patches
+@section Tracking Bugs and Patches
+
+@cindex bug reports, tracking
+@cindex patch submissions, tracking
+@cindex issue tracking
+@cindex Debbugs, issue tracking system
+Bug reports and patch submissions are currently tracked using the
+Debbugs instance at @uref{https://bugs.gnu.org}. Bug reports are filed
+against the @code{guix} ``package'' (in Debbugs parlance), by sending
+email to @email{bug-guix@@gnu.org}, while patch submissions are filed
+against the @code{guix-patches} package by sending email to
+@email{guix-patches@@gnu.org} (@pxref{Submitting Patches}).
+
+A web interface (actually @emph{two} web interfaces!) are available to
+browse issues:
+
+@itemize
+@item
+@url{https://bugs.gnu.org/guix} lists bug reports;
+@item
+@url{https://bugs.gnu.org/guix-patches} lists patch submissions.
+@end itemize
+
+You can also access both of these @i{via} the (nicer)
+@url{https://issues.guix.gnu.org} interface@footnote{The web interface
+at @url{https://issues.guix.gnu.org} is powered by Mumi, a nice piece of
+software written in Guile, and you can help! See
+@url{https://git.elephly.net/gitweb.cgi?p=software/mumi.git}.}. To view
+discussions related to issue number @var{n}, go to
+@indicateurl{https://issues.guix.gnu.org/issue/@var{n}} or
+@indicateurl{https://bugs.gnu.org/@var{n}}.
+
+If you use Emacs, you may find it more convenient to interact with
+issues using @file{debbugs.el}, which you can install with:
+
+@example
+guix install emacs-debbugs
+@end example
+
+For example, to list all open issues on @code{guix-patches}, hit:
+
+@example
+@kbd{C-u} @kbd{M-x} debbugs-gnu @kbd{RET} @kbd{RET} guix-patches @kbd{RET} n y
+@end example
+
+@xref{Top,,, debbugs-ug, Debbugs User Guide}, for more information on
+this nifty tool!
+
+@node Commit Access
+@section Commit Access
+
+@cindex commit access, for developers
+For frequent contributors, having write access to the repository is
+convenient. When you deem it necessary, consider applying for commit
+access by following these steps:
+
+@enumerate
+@item
+Find three committers who would vouch for you. You can view the list of
+committers at
+@url{https://savannah.gnu.org/project/memberlist.php?group=guix}. Each
+of them should email a statement to @email{guix-maintainers@@gnu.org} (a
+private alias for the collective of maintainers), signed with their
+OpenPGP key.
+
+Committers are expected to have had some interactions with you as a
+contributor and to be able to judge whether you are sufficiently
+familiar with the project's practices. It is @emph{not} a judgment on
+the value of your work, so a refusal should rather be interpreted as
+``let's try again later''.
+
+@item
+Send @email{guix-maintainers@@gnu.org} a message stating your intent,
+listing the three committers who support your application, signed with
+the OpenPGP key you will use to sign commits, and giving its fingerprint
+(see below). See @uref{https://emailselfdefense.fsf.org/en/}, for an
+introduction to public-key cryptography with GnuPG.
+
+@c See <https://sha-mbles.github.io/>.
+Set up GnuPG such that it never uses the SHA1 hash algorithm for digital
+signatures, which is known to be unsafe since 2019, for instance by
+adding the following line to @file{~/.gnupg/gpg.conf} (@pxref{GPG
+Esoteric Options,,, gnupg, The GNU Privacy Guard Manual}):
+
+@example
+digest-algo sha512
+@end example
+
+@item
+Maintainers ultimately decide whether to grant you commit access,
+usually following your referrals' recommendation.
+
+@item
+@cindex OpenPGP, signed commits
+If and once you've been given access, please send a message to
+@email{guix-devel@@gnu.org} to say so, again signed with the OpenPGP key
+you will use to sign commits (do that before pushing your first commit).
+That way, everyone can notice and ensure you control that OpenPGP key.
+
+@quotation Important
+Before you can push for the first time, maintainers must:
+
+@enumerate
+@item
+add your OpenPGP key to the @code{keyring} branch;
+@item
+add your OpenPGP fingerprint to the @file{.guix-authorizations} file of
+the branch(es) you will commit to.
+@end enumerate
+@end quotation
+
+@item
+Make sure to read the rest of this section and... profit!
+@end enumerate
+
+@quotation Note
+Maintainers are happy to give commit access to people who have been
+contributing for some time and have a track record---don't be shy and
+don't underestimate your work!
+
+However, note that the project is working towards a more automated patch
+review and merging system, which, as a consequence, may lead us to have
+fewer people with commit access to the main repository. Stay tuned!
+@end quotation
+
+If you get commit access, please make sure to follow
+the policy below (discussions of the policy can take place on
+@email{guix-devel@@gnu.org}).
+
+Non-trivial patches should always be posted to
+@email{guix-patches@@gnu.org} (trivial patches include fixing typos,
+etc.). This mailing list fills the patch-tracking database
+(@pxref{Tracking Bugs and Patches}).
+
+For patches that just add a new package, and a simple one, it's OK to
+commit, if you're confident (which means you successfully built it in a
+chroot setup, and have done a reasonable copyright and license
+auditing). Likewise for package upgrades, except upgrades that trigger
+a lot of rebuilds (for example, upgrading GnuTLS or GLib). We have a
+mailing list for commit notifications (@email{guix-commits@@gnu.org}),
+so people can notice. Before pushing your changes, make sure to run
+@code{git pull --rebase}.
+
+All commits that are pushed to the central repository on Savannah must
+be signed with an OpenPGP key, and the public key should be uploaded to
+your user account on Savannah and to public key servers, such as
+@code{keys.openpgp.org}. To configure Git to automatically sign
+commits, run:
+
+@example
+git config commit.gpgsign true
+git config user.signingkey CABBA6EA1DC0FF33
+@end example
+
+You can prevent yourself from accidentally pushing unsigned commits to
+Savannah by using the pre-push Git hook called located at
+@file{etc/git/pre-push}:
+
+@example
+cp etc/git/pre-push .git/hooks/pre-push
+@end example
+
+When pushing a commit on behalf of somebody else, please add a
+@code{Signed-off-by} line at the end of the commit log message---e.g.,
+with @command{git am --signoff}. This improves tracking of who did
+what.
+
+When adding channel news entries (@pxref{Channels, Writing Channel
+News}), make sure they are well-formed by running the following command
+right before pushing:
+
+@example
+make check-channel-news
+@end example
+
+For anything else, please post to @email{guix-patches@@gnu.org} and
+leave time for a review, without committing anything (@pxref{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.
+
+One last thing: the project keeps moving forward because committers not
+only push their own awesome changes, but also offer some of their time
+@emph{reviewing} and pushing other people's changes. As a committer,
+you're welcome to use your expertise and commit rights to help other
+contributors, too!
HCoop / jackhill / guix / guix.git / blobdiff