X-Git-Url: http://git.hcoop.net/jackhill/guix/guix.git/blobdiff_plain/15fba3b13d543bbc1f13907e659c354a5b6f28ec..61dd2c1bde9fff379dfbce06ae495543db5b7324:/doc/contributing.texi diff --git a/doc/contributing.texi b/doc/contributing.texi index 6500bfa3a1..d67e632520 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -3,7 +3,7 @@ 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}). @@ -29,6 +29,7 @@ choice. * 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 @@ -126,10 +127,10 @@ 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 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}. +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: @@ -166,14 +167,15 @@ actually installing them. So that you can distinguish between your ``end-user'' hat and your ``motley'' costume. To that end, all the command-line tools can be used even if you have not -run @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}). -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): +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 $ ./pre-inst-env guix build hello @@ -240,7 +242,7 @@ Manual}). First, you need more than an editor, you need 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 @@ -431,7 +433,7 @@ upstream source. @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 @@ -444,6 +446,14 @@ 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}. +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 @@ -522,9 +532,11 @@ 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: +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 @@ -543,6 +555,20 @@ definition may look like this: ))) @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 @@ -592,8 +618,8 @@ 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 +@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. @@ -645,14 +671,14 @@ more information (@pxref{origin Reference}). 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 are no +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 +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. +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 @@ -801,10 +827,10 @@ To prevent namespace collisions we prefix all other Rust packages with the 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, @@ -1008,21 +1034,21 @@ Make sure the package builds on your platform, using @code{guix build 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 @@ -1053,7 +1079,7 @@ and which optional dependencies should be used. In particular, avoid adding 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}). @@ -1071,12 +1097,14 @@ rebuilding induced, commits go to different branches, along these lines: @code{staging} branch (non-disruptive changes). This branch is intended 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,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 -6 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-URL}, @@ -1085,10 +1113,12 @@ 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. @@ -1167,6 +1197,11 @@ MIME attachments. You are advised to pay attention if your email client changes anything like line breaks or indentation which could potentially break the patches. +Expect some delay when you submit your very first patch to +@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}. @@ -1371,6 +1406,12 @@ 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. +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, @@ -1413,3 +1454,266 @@ 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.2>Defining-Packages.html as native <2>Guile modules." +msgstr "Pakete werden als reine <2>Guile-Module <1>definiert<1.1>de<1.2>Pakete-definieren.html." +@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