This project is a cooperative effort, and we need your help to make it
grow! Please get in touch with us on @email{guix-devel@@gnu.org} and
-@code{#guix} on the Freenode IRC network. We welcome ideas, bug
+@code{#guix} on the Libera Chat IRC network. We welcome ideas, bug
reports, patches, and anything that may be helpful to the project. We
particularly welcome help on packaging (@pxref{Packaging Guidelines}).
* Submitting Patches:: Share your work.
* Tracking Bugs and Patches:: Using Debbugs.
* Commit Access:: Pushing to the official repository.
+* Updating the Guix Package:: Updating the Guix package definition.
+* Translating Guix:: Make Guix speak your native language.
@end menu
@node Building from Git
@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:
+To do that, run @command{guix git authenticate}, passing it the commit
+and OpenPGP fingerprint of the @dfn{channel introduction}
+(@pxref{Invoking guix git authenticate}):
-@c XXX: Adjust instructions when there's a known tag to start from.
+@c The commit and fingerprint below must match those of the channel
+@c introduction in '%default-channels'.
@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{}
+git fetch origin keyring:keyring
+guix git authenticate 9edb3f66fd807b096b48283debdcddccfea34bad \
+ "BBB0 2DDF 2CEA F6A8 0D1D E643 A2A0 6DF2 A33A 54FA"
@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:
+This command completes with exit code zero on success; it prints an
+error message and exits with a non-zero code otherwise.
-@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
+As you can see, there is a chicken-and-egg problem: you first need to
+have Guix installed. Typically you would install Guix System
+(@pxref{System Installation}) or Guix on top of another distro
+(@pxref{Binary Installation}); in either case, you would verify the
+OpenPGP signature on the installation medium. This ``bootstraps'' the
+trust chain.
The easiest way to set up a development environment for Guix is, of
course, by using Guix! The following command starts a new shell where
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). We recommend to use the value
-@code{/var}.
+Store}, for information about this), usually @file{/var}. Note that you
+will probably not run @command{make install} at the end (you don't have
+to) but it's still important to pass the right @code{localstatedir}.
+
+Finally, you have to invoke @code{make && make check} to build Guix and
+run the tests (@pxref{Running the Test Suite}). If anything fails, take
+a look at installation instructions (@pxref{Installation}) or send a
+message to the @email{guix-devel@@gnu.org, mailing list}.
+
+From there on, you can authenticate all the commits included in your
+checkout by running:
+
+@example
+make authenticate
+@end example
+
+The first run takes a couple of minutes, but subsequent runs are faster.
-Finally, you have to invoke @code{make check} to run tests
-(@pxref{Running the Test Suite}). If anything
-fails, take a look at installation instructions (@pxref{Installation})
-or send a message to the @email{guix-devel@@gnu.org, mailing list}.
+Or, when your configuration for your local Git repository doesn't match
+the default one, you can provide the reference for the @code{keyring}
+branch through the variable @code{GUIX_GIT_KEYRING}. The following
+example assumes that you have a Git remote called @samp{myremote}
+pointing to the official repository:
+
+@example
+make authenticate GUIX_GIT_KEYRING=myremote/keyring
+@end example
+
+@quotation Note
+You are advised to run @command{make authenticate} after every
+@command{git pull} invocation. This ensures you keep receiving valid
+changes to the repository.
+@end quotation
@node Running Guix Before It Is Installed
``end-user'' hat and your ``motley'' costume.
To that end, all the command-line tools can be used even if you have not
-run @code{make install}. To do that, you first need to have an environment
-with all the dependencies available (@pxref{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; 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.}:
+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; it
+is generated by running @command{./bootstrap} followed by
+@command{./configure}). As an example, here is how you would build the
+@code{hello} package as defined in your working tree (this assumes
+@command{guix-daemon} is already running on your system; it's OK if it's
+a different version):
@example
-$ sudo -E ./pre-inst-env guix-daemon --build-users-group=guixbuild
$ ./pre-inst-env guix build hello
@end example
$1 = 361
@end example
+If you are hacking on the daemon and its supporting code or if
+@command{guix-daemon} is not already running on your system, you can
+launch it straight from the build tree@footnote{The @option{-E} flag to
+@command{sudo} guarantees that @code{GUILE_LOAD_PATH} is correctly set
+such that @command{guix-daemon} and the tools it uses can find the Guile
+modules they need.}:
+
+@example
+$ sudo -E ./pre-inst-env guix-daemon --build-users-group=guixbuild
+@end example
+
The @command{pre-inst-env} script sets up all the environment variables
necessary to support this, including @env{PATH} and @env{GUILE_LOAD_PATH}.
wonderful @url{https://nongnu.org/geiser/, Geiser}. To set that up, run:
@example
-guix package -i emacs guile emacs-geiser
+guix package -i emacs guile emacs-geiser emacs-geiser-guile
@end example
Geiser allows for interactive and incremental development from within
@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
+We additionally provide insertion and automatic update of a copyright in
@file{etc/copyright.el}. You may want to set your full name, mail, and
load a file.
(@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}.
+@url{@value{SUBSTITUTE-URL}, our continuous integration system}.
@cindex substituter
Users can obtain the new package definition simply by running
* Package Naming:: What's in a name?
* Version Numbers:: When the name is not enough.
* Synopses and Descriptions:: Helping users find the right package.
+* Snippets versus Phases:: Whether to use a snippet, or a build phase.
+* Emacs Packages:: Your Elisp fix.
* Python Modules:: A touch of British comedy.
* Perl Modules:: Little pearls.
* Java Packages:: Coffee break.
@subsection Package Naming
@cindex package name
-A package has actually two names associated with it:
+A package actually has two names associated with it.
First, there is the name of the @emph{Scheme variable}, the one following
@code{define-public}. By this name, the package can be made known in the
Scheme code, for instance as input to another package. Second, there is
hyphens. For instance, GNUnet is available as @code{gnunet}, and
SDL_net as @code{sdl-net}.
+A noteworthy exception to this rule is when the project name is only a
+single character, or if an older maintained project with the same name
+already exists---regardless of whether it has already been packaged for
+Guix. Use common sense to make such names unambiguous and meaningful.
+For example, Guix's package for the shell called ``s'' upstream is
+@code{s-shell} and @emph{not} @code{s}. Feel free to ask your fellow
+hackers for inspiration.
+
We do not add @code{lib} prefixes for library packages, unless these are
already part of the official project name. But @pxref{Python
Modules} and @ref{Perl Modules} for special rules concerning modules for
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:
+kernel). There are helper functions for doing this for packages using
+@code{git-fetch} or @code{hg-fetch} (see below). 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
)))
@end lisp
+@deffn {Scheme Procedure} git-version @var{VERSION} @var{REVISION} @var{COMMIT}
+Return the version string for packages using @code{git-fetch}.
+
+@lisp
+(git-version "0.2.3" "0" "93818c936ee7e2f1ba1b315578bde363a7d43d05")
+@result{} "0.2.3-0.93818c9"
+@end lisp
+@end deffn
+
+@deffn {Scheme Procedure} hg-version @var{VERSION} @var{REVISION} @var{CHANGESET}
+Return the version string for packages using @code{hg-fetch}. It works
+in the same way as @code{git-version}.
+@end deffn
+
@node Synopses and Descriptions
@subsection Synopses and Descriptions
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
+@uref{https://translate.fedoraproject.org/projects/guix/packages, at
+Weblate} so that as many users as possible can read them in
their native language. User interfaces search them and display them in
the language specified by the current locale.
special comments like this (@pxref{xgettext Invocation,,, gettext, GNU
Gettext}):
-@example
+@lisp
;; TRANSLATORS: "X11 resize-and-rotate" should not be translated.
(description "ARandR is designed to provide a simple visual front end
for the X11 resize-and-rotate (RandR) extension. @dots{}")
-@end example
+@end lisp
+
+@node Snippets versus Phases
+@subsection Snippets versus Phases
+
+@cindex snippets, when to use
+The boundary between using an origin snippet versus a build phase to
+modify the sources of a package can be elusive. Origin snippets are
+typically used to remove unwanted files such as bundled libraries,
+nonfree sources, or to apply simple substitutions. The source derived
+from an origin should produce a source that can be used to build the
+package on any system that the upstream package supports (i.e., act as
+the corresponding source). In particular, origin snippets must not
+embed store items in the sources; such patching should rather be done
+using build phases. Refer to the @code{origin} record documentation for
+more information (@pxref{origin Reference}).
+
+@node Emacs Packages
+@subsection Emacs Packages
+
+@cindex emacs, packaging
+@cindex elisp, packaging
+Emacs packages should preferably use the Emacs build system
+(@pxref{emacs-build-system}), for uniformity and the benefits provided
+by its build phases, such as the auto-generation of the autoloads file
+and the byte compilation of the sources. Because there is no
+standardized way to run a test suite for Emacs packages, tests are
+disabled by default. When a test suite is available, it should be
+enabled by setting the @code{#:tests?} argument to @code{#true}. By
+default, the command to run the test is @command{make check}, but any
+command can be specified via the @code{#:test-command} argument. The
+@code{#:test-command} argument expects a list containing a command and
+its arguments, to be invoked during the @code{check} phase.
+
+The Elisp dependencies of Emacs packages are typically provided as
+@code{propagated-inputs} when required at run time. As for other
+packages, build or test dependencies should be specified as
+@code{native-inputs}.
+
+Emacs packages sometimes depend on resources directories that should be
+installed along the Elisp files. The @code{#:include} argument can be
+used for that purpose, by specifying a list of regexps to match. The
+best practice when using the @code{#:include} argument is to extend
+rather than override its default value (accessible via the
+@code{%default-include} variable). As an example, a yasnippet extension
+package typically include a @file{snippets} directory, which could be
+copied to the installation directory using:
+
+@lisp
+#:include (cons "^snippets/" %default-include))
+@end lisp
+When encountering problems, it is wise to check for the presence of the
+@code{Package-Requires} extension header in the package main source
+file, and whether any dependencies and their versions listed therein are
+satisfied.
@node Python Modules
@subsection Python Modules
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}).
+package to be used at any given time, so all package definitions should have a
+versioned suffix. The versioned suffix is the left-most non-zero digit (and
+any leading zeros, of course). This follows the ``caret'' version scheme
+intended by Cargo. Examples@: @code{rust-clap-2}, @code{rust-rand-0.6}.
Because of the difficulty in reusing rust packages as pre-compiled inputs for
other packages the Cargo build system (@pxref{Build Systems,
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.
+especially when matching lists (@pxref{Pattern Matching,,, guile, GNU
+Guile Reference Manual}).
@node Formatting Code
@subsection Formatting Code
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:
+order to enable it, add the @code{virtualization} service module and 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)))
+ (platforms (lookup-qemu-platforms "arm" "aarch64"))))
@end lisp
Then reconfigure your system.
You can then build packages for different platforms by specifying the
@code{--system} option. For example, to build the "hello" package for
-the armhf, aarch64, or mips64 architectures, you would run the following
+the armhf or aarch64 architectures, you would run the following
commands, respectively:
@example
guix build --system=armhf-linux --rounds=2 hello
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.
+the @code{texlive-tiny} package or @code{texlive-union} procedure instead.
@item
-For important changes, check that dependent package (if applicable) are
+For important changes, check that dependent packages (if applicable) are
not affected by the change; @code{guix refresh --list-dependent
@var{package}} will help you do that (@pxref{Invoking guix refresh}).
@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}).
+(say, @code{gnome-updates}). This branch is not expected to be
+buildable or usable until late in its development process.
-@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. This branch is not expected to be buildable or usable
+until late in its development process.
@end table
-All these branches are @uref{@value{SUBSTITUTE-SERVER},
+All these branches are @uref{@value{SUBSTITUTE-URL},
tracked by our build farm} and merged into @code{master} once
everything has been successfully built. This allows us to fix issues
before they hit users, and to reduce the window during which pre-built
binaries are not available.
-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.
+When we decide to start building the @code{staging} or
+@code{core-updates} branches, they will be forked and renamed with the
+suffix @code{-frozen}, at which time only bug fixes may be pushed to the
+frozen branches. The @code{core-updates} and @code{staging} branches
+will remain open to accept patches for the next cycle. Please ask on
+the mailing list or IRC if unsure where to place a patch.
@c TODO: It would be good with badges on the website that tracks these
@c branches. Or maybe even a status page.
changes anything like line breaks or indentation which could potentially
break the patches.
+Expect some delay when you submit your very first patch to
+@email{guix-patches@@gnu.org}. You have to wait until you get an
+acknowledgement with the assigned tracking number. Future acknowledgements
+should not be delayed.
+
When a bug is resolved, please close the thread by sending an email to
@email{@var{NNN}-done@@debbugs.gnu.org}.
@itemize
@item
+@url{https://issues.guix.gnu.org} provides a pleasant
+interface@footnote{The web interface at
+@url{https://issues.guix.gnu.org} is powered by Mumi, a nice piece of
+software written in Guile, and you can help! See
+@url{https://git.elephly.net/gitweb.cgi?p=software/mumi.git}.} to browse
+bug reports and patches, and to participate in discussions;
+@item
@url{https://bugs.gnu.org/guix} lists bug reports;
@item
@url{https://bugs.gnu.org/guix-patches} lists patch submissions.
@end itemize
-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
+To view discussions related to issue number @var{n}, go to
+@indicateurl{https://issues.guix.gnu.org/@var{n}} or
@indicateurl{https://bugs.gnu.org/@var{n}}.
If you use Emacs, you may find it more convenient to interact with
That last part is subject to being adjusted, allowing individuals to commit
directly on non-controversial changes on parts they’re familiar with.
+In order to reduce the possibility of mistakes, committers will have
+their Savannah account removed from the Guix Savannah project and their
+key removed from @file{.guix-authorizations} after 12 months of
+inactivity; they can ask to regain commit access by emailing the
+maintainers, without going through the vouching process.
+
One last thing: the project keeps moving forward because committers not
only push their own awesome changes, but also offer some of their time
@emph{reviewing} and pushing other people's changes. As a committer,
you're welcome to use your expertise and commit rights to help other
contributors, too!
+
+@node Updating the Guix Package
+@section Updating the Guix Package
+
+@cindex update-guix-package, updating the guix package
+It is sometimes desirable to update the @code{guix} package itself (the
+package defined in @code{(gnu packages package-management)}), for
+example to make new daemon features available for use by the
+@code{guix-service-type} service type. In order to simplify this task,
+the following command can be used:
+
+@example
+make update-guix-package
+@end example
+
+The @code{update-guix-package} make target will use the last known
+@emph{commit} corresponding to @code{HEAD} in your Guix checkout,
+compute the hash of the Guix sources corresponding to that commit and
+update the @code{commit}, @code{revision} and hash of the @code{guix}
+package definition.
+
+To validate that the updated @code{guix} package hashes are correct and
+that it can be built successfully, the following command can be run from
+the directory of your Guix checkout:
+
+@example
+./pre-inst-env guix build guix
+@end example
+
+To guard against accidentally updating the @code{guix} package to a
+commit that others can't refer to, a check is made that the commit used
+has already been pushed to the Savannah-hosted Guix git repository.
+
+This check can be disabled, @emph{at your own peril}, by setting the
+@code{GUIX_ALLOW_ME_TO_USE_PRIVATE_COMMIT} environment variable. When
+this variable is set, the updated package source is also added to the
+store. This is used as part of the release process of Guix.
+
+@cindex translation
+@cindex l10n
+@cindex i18n
+@cindex native language support
+@node Translating Guix
+@section Translating Guix
+
+Writing code and packages is not the only way to provide a meaningful
+contribution to Guix. Translating to a language you speak is another
+example of a valuable contribution you can make. This section is designed
+to describe the translation process. It gives you advice on how you can
+get involved, what can be translated, what mistakes you should avoid and
+what we can do to help you!
+
+Guix is a big project that has multiple components that can be translated.
+We coordinate the translation effort on a
+@uref{https://translate.fedoraproject.org/projects/guix/,Weblate instance}
+hosted by our friends at Fedora. You will need an account to submit
+translations.
+
+Some of the software packaged in Guix also contain translations. We do not
+host a translation platform for them. If you want to translate a package
+provided by Guix, you should contact their developers or find the information
+on their website. As an example, you can find the homepage of the
+@code{hello} package by typing @code{guix show hello}. On the ``homepage''
+line, you will see @url{https://www.gnu.org/software/hello/} as the homepage.
+
+Many GNU and non-GNU packages can be translated on the
+@uref{https://translationproject.org,Translation Project}. Some projects
+with multiple components have their own platform. For instance, GNOME has
+its own platform, @uref{https://l10n.gnome.org/,Damned Lies}.
+
+Guix has five components hosted on Weblate.
+
+@itemize
+@item @code{guix} contains all the strings from the Guix software (the
+ guided system installer, the package manager, etc), excluding packages.
+@item @code{packages} contains the synopsis (single-sentence description
+ of a package) and description (longer description) of packages in Guix.
+@item @code{website} contains the official Guix website, except for
+ blog posts and multimedia content.
+@item @code{documentation-manual} corresponds to this manual.
+@item @code{documentation-cookbook} is the component for the cookbook.
+@end itemize
+
+@subsubheading General Directions
+
+Once you get an account, you should be able to select a component from
+@uref{https://translate.fedoraproject.org/projects/guix/,the guix project},
+and select a language. If your language does not appear in the list, go
+to the bottom and click on the ``Start new translation'' button. Select
+the language you want to translate to from the list, to start your new
+translation.
+
+Like lots of other free software packages, Guix uses
+@uref{https://www.gnu.org/software/gettext,GNU Gettext} for its translations,
+with which translatable strings are extracted from the source code to so-called
+PO files.
+
+Even though PO files are text files, changes should not be made with a text
+editor but with PO editing software. Weblate integrates PO editing
+functionality. Alternatively, translators can use any of various
+free-software tools for filling in translations, of which
+@uref{https://poedit.net/,Poedit} is one example, and (after logging in)
+@uref{https://docs.weblate.org/en/latest/user/files.html,upload} the changed
+file. There is also a special
+@uref{https://www.emacswiki.org/emacs/PoMode,PO editing mode} for users of GNU
+Emacs. Over time translators find out what software they are happy with and
+what features they need.
+
+On Weblate, you will find various links to the editor, that will show various
+subsets (or all) of the strings. Have a look around and at the
+@uref{https://docs.weblate.org/en/latest/,documentation} to familiarize
+yourself with the platform.
+
+@subsubheading Translation Components
+
+In this section, we provide more detailed guidance on the translation
+process, as well as details on what you should or should not do. When in
+doubt, please contact us, we will be happy to help!
+
+@table @asis
+@item guix
+Guix is written in the Guile programming language, and some strings contain
+special formatting that is interpreted by Guile. These special formatting
+should be highlighted by Weblate. They start with @code{~} followed by one
+or more characters.
+
+When printing the string, Guile replaces the special formatting symbols with
+actual values. For instance, the string @samp{ambiguous package specification
+`~a'} would be substituted to contain said package specification instead of
+@code{~a}. To properly translate this string, you must keep the formatting
+code in your translation, although you can place it where it makes sense in
+your language. For instance, the French translation says @samp{spécification
+du paquet « ~a » ambiguë} because the adjective needs to be placed in the
+end of the sentence.
+
+If there are multiple formatting symbols, make sure to respect the order.
+Guile does not know in which order you intended the string to be read, so it
+will substitute the symbols in the same order as the English sentence.
+
+As an example, you cannot translate @samp{package '~a' has been superseded by
+'~a'} by @samp{'~a' superseeds package '~a'}, because the meaning would be
+reversed. If @var{foo} is superseded by @var{bar}, the translation would read
+@samp{'foo' superseeds package 'bar'}. To work around this problem, it
+is possible to use more advanced formatting to select a given piece of data,
+instead of following the default English order. @xref{Formatted Output,,,
+guile, GNU Guile Reference Manual}, for more information on formatting in Guile.
+
+@item packages
+
+Package descriptions occasionally contain Texinfo markup (@pxref{Synopses
+and Descriptions}). Texinfo markup looks like @samp{@@code@{rm -rf@}},
+@samp{@@emph@{important@}}, etc. When translating, please leave markup as is.
+
+The characters after ``@@'' form the name of the markup, and the text between
+``@{'' and ``@}'' is its content. In general, you should not translate the
+content of markup like @code{@@code}, as it contains literal code that do not
+change with language. You can translate the content of formatting markup such
+as @code{@@emph}, @code{@@i}, @code{@@itemize}, @code{@@item}. However, do
+not translate the name of the markup, or it will not be recognized. Do
+not translate the word after @code{@@end}, it is the name of the markup that
+is closed at this position (e.g.@: @code{@@itemize ... @@end itemize}).
+
+@item documentation-manual and documentation-cookbook
+
+The first step to ensure a successful translation of the manual is to find
+and translate the following strings @emph{first}:
+
+@itemize
+@item @code{version.texi}: Translate this string as @code{version-xx.texi},
+ where @code{xx} is your language code (the one shown in the URL on
+ weblate).
+@item @code{contributing.texi}: Translate this string as
+ @code{contributing.xx.texi}, where @code{xx} is the same language code.
+@item @code{Top}: Do not translate this string, it is important for Texinfo.
+ If you translate it, the document will be empty (missing a Top node).
+ Please look for it, and register @code{Top} as its translation.
+@end itemize
+
+Translating these strings first ensure we can include your translation in
+the guix repository without breaking the make process or the
+@command{guix pull} machinery.
+
+The manual and the cookbook both use Texinfo. As for @code{packages}, please
+keep Texinfo markup as is. There are more possible markup types in the manual
+than in the package descriptions. In general, do not translate the content
+of @code{@@code}, @code{@@file}, @code{@@var}, @code{@@value}, etc. You
+should translate the content of formatting markup such as @code{@@emph},
+@code{@@i}, etc.
+
+The manual contains sections that can be referred to by name by @code{@@ref},
+@code{@@xref} and @code{@@pxref}. We have a mechanism in place so you do
+not have to translate their content. If you keep the English title, we will
+automatically replace it with your translation of that title. This ensures
+that Texinfo will always be able to find the node. If you decide to change
+the translation of the title, the references will automatically be updated
+and you will not have to update them all yourself.
+
+When translating references from the cookbook to the manual, you need to
+replace the name of the manual and the name of the section. For instance,
+to translate @code{@@pxref@{Defining Packages,,, guix, GNU Guix Reference
+Manual@}}, you would replace @code{Defining Packages} with the title of that
+section in the translated manual @emph{only} if that title is translated.
+If the title is not translated in your language yet, do not translate it here,
+or the link will be broken. Replace @code{guix} with @code{guix.xx} where
+@code{xx} is your language code. @code{GNU Guix Reference Manual} is the
+text of the link. You can translate it however you wish.
+
+@item website
+
+The website pages are written using SXML, an s-expression version of HTML,
+the basic language of the web. We have a process to extract translatable
+strings from the source, and replace complex s-expressions with a more familiar
+XML markup, where each markup is numbered. Translators can arbitrarily change
+the ordering, as in the following example.
+
+@example
+#. TRANSLATORS: Defining Packages is a section name
+#. in the English (en) manual.
+#: apps/base/templates/about.scm:64
+msgid "Packages are <1>defined<1.1>en</1.1><1.2>Defining-Packages.html</1.2></1> as native <2>Guile</2> modules."
+msgstr "Pakete werden als reine <2>Guile</2>-Module <1>definiert<1.1>de</1.1><1.2>Pakete-definieren.html</1.2></1>."
+@end example
+
+Note that you need to include the same markups. You cannot skip any.
+@end table
+
+In case you make a mistake, the component might fail to build properly with your
+language, or even make guix pull fail. To prevent that, we have a process
+in place to check the content of the files before pushing to our repository.
+We will not be able to update the translation for your language in Guix, so
+we will notify you (through weblate and/or by email) so you get a chance to
+fix the issue.
+
+@subsubheading Outside of Weblate
+
+Currently, some parts of Guix cannot be translated on Weblate, help wanted!
+
+@itemize
+@item @command{guix pull} news can be translated in @file{news.scm}, but is not
+ available from Weblate. If you want to provide a translation, you
+ can prepare a patch as described above, or simply send us your
+ translation with the name of the news entry you translated and your
+ language. @xref{Writing Channel News}, for more information about
+ channel news.
+@item Guix blog posts cannot currently be translated.
+@item The installer script (for foreign distributions) is entirely in English.
+@item Some of the libraries Guix uses cannot be translated or are translated
+ outside of the Guix project. Guile itself is not internationalized.
+@item Other manuals linked from this manual or the cookbook might not be
+ translated.
+@end itemize
+
+@subsubheading Translation Infrastructure
+
+Weblate is backed by a git repository from which it discovers new strings to
+translate and pushes new and updated translations. Normally, it would be
+enough to give it commit access to our repositories. However, we decided
+to use a separate repository for two reasons. First, we would have to give
+Weblate commit access and authorize its signing key, but we do not trust it
+in the same way we trust guix developers, especially since we do not manage
+the instance ourselves. Second, if translators mess something up, it can
+break the generation of the website and/or guix pull for all our users,
+independently of their language.
+
+For these reasons, we use a dedicated repository to host translations, and we
+synchronize it with our guix and artworks repositories after checking no issue
+was introduced in the translation.
+
+Developers can download the latest PO files from weblate in the Guix
+repository by running the @command{make download-po} command. It will
+automatically download the latest files from weblate, reformat them to a
+canonical form, and check they do not contain issues. The manual needs to be
+built again to check for additional issues that might crash Texinfo.
+
+Before pushing new translation files, developers should add them to the
+make machinery so the translations are actually available. The process
+differs for the various components.
+
+@itemize
+@item New po files for the @code{guix} and @code{packages} components must
+ be registered by adding the new language to @file{po/guix/LINGUAS} or
+ @file{po/packages/LINGUAS}.
+@item New po files for the @code{documentation-manual} component must be
+ registered by adding the file name to @code{DOC_PO_FILES} in
+ @file{po/doc/local.mk}, the generated @file{%D%/guix.xx.texi} manual to
+ @code{info_TEXINFOS} in @file{doc/local.mk} and the generated
+ @file{%D%/guix.xx.texi} and @file{%D%/contributing.xx.texi} to
+ @code{TRANSLATED_INFO} also in @file{doc/local.mk}.
+@item New po files for the @code{documentation-cookbook} component must be
+ registered by adding the file name to @code{DOC_COOKBOOK_PO_FILES} in
+ @file{po/doc/local.mk}, the generated @file{%D%/guix-cookbook.xx.texi}
+ manual to @code{info_TEXINFOS} in @file{doc/local.mk} and the generated
+ @file{%D%/guix-cookbook.xx.texi} to @code{TRANSLATED_INFO} also
+ in @file{doc/local.mk}.
+@item New po files for the @code{website} component must be added to the
+ @code{guix-artwork} repository, in @file{website/po/}.
+ @file{website/po/LINGUAS} and @file{website/po/ietf-tags.scm} must
+ be updated accordingly (see @file{website/i18n-howto.txt} for more
+ information on the process).
+@end itemize
HCoop / jackhill / guix / guix.git / blobdiff