diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/contributing.texi | 178 | ||||
| -rw-r--r-- | doc/guix.texi | 170 |
2 files changed, 326 insertions, 22 deletions
diff --git a/doc/contributing.texi b/doc/contributing.texi index e656676c0f..5d5d50c3c0 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -26,6 +26,8 @@ choice. * 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 @@ -826,13 +828,15 @@ Development is done using the Git distributed version control system. Thus, access to the repository is not strictly necessary. We welcome contributions in the form of patches as produced by @code{git format-patch} sent to the @email{guix-patches@@gnu.org} mailing list. +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 @@ -1040,3 +1044,165 @@ they are kept together. See 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. + +@item +Maintainers ultimately decide whether to grant you commit access, +usually following your referrals' recommendation. + +@item +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. + +@c TODO: Add note about adding the fingerprint to the list of authorized +@c keys once that has stabilized. + +@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. + +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! diff --git a/doc/guix.texi b/doc/guix.texi index efc59c1aaf..d2038d18e1 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -21,7 +21,7 @@ @set SUBSTITUTE-URL https://@value{SUBSTITUTE-SERVER} @copying -Copyright @copyright{} 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019 Ludovic Courtès@* +Copyright @copyright{} 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020 Ludovic Courtès@* Copyright @copyright{} 2013, 2014, 2016 Andreas Enge@* Copyright @copyright{} 2013 Nikita Karetnikov@* Copyright @copyright{} 2014, 2015, 2016 Alex Kost@* @@ -29,7 +29,7 @@ Copyright @copyright{} 2015, 2016 Mathieu Lirzin@* Copyright @copyright{} 2014 Pierre-Antoine Rault@* Copyright @copyright{} 2015 Taylan Ulrich Bayırlı/Kammer@* Copyright @copyright{} 2015, 2016, 2017, 2019 Leo Famulari@* -Copyright @copyright{} 2015, 2016, 2017, 2018, 2019 Ricardo Wurmus@* +Copyright @copyright{} 2015, 2016, 2017, 2018, 2019, 2020 Ricardo Wurmus@* Copyright @copyright{} 2016 Ben Woodcroft@* Copyright @copyright{} 2016, 2017, 2018 Chris Marusich@* Copyright @copyright{} 2016, 2017, 2018, 2019 Efraim Flashner@* @@ -49,7 +49,7 @@ Copyright @copyright{} 2017 Christopher Allan Webber@* Copyright @copyright{} 2017, 2018, 2019 Marius Bakke@* Copyright @copyright{} 2017, 2019 Hartmut Goebel@* Copyright @copyright{} 2017, 2019 Maxim Cournoyer@* -Copyright @copyright{} 2017, 2018, 2019 Tobias Geerinckx-Rice@* +Copyright @copyright{} 2017, 2018, 2019, 2020 Tobias Geerinckx-Rice@* Copyright @copyright{} 2017 George Clemmer@* Copyright @copyright{} 2017 Andy Wingo@* Copyright @copyright{} 2017, 2018, 2019 Arun Isaac@* @@ -69,6 +69,7 @@ Copyright @copyright{} 2019 Jakob L. Kreuze@* Copyright @copyright{} 2019 Kyle Andrews@* Copyright @copyright{} 2019 Alex Griffin@* Copyright @copyright{} 2019 Guillaume Le Vaillant@* +Copyright @copyright{} 2020 Leo Prikler@* Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or @@ -2245,8 +2246,8 @@ bootloaders. Once you are done partitioning the target hard disk drive, you have to create a file system on the relevant partition(s)@footnote{Currently -Guix System only supports ext4 and btrfs file systems. In particular, code -that reads file system UUIDs and labels only works for these file system +Guix System only supports ext4, btrfs, and JFS file systems. In particular, +code that reads file system UUIDs and labels only works for these file system types.}. For the ESP, if you have one and assuming it is @file{/dev/sda1}, run: @@ -14154,8 +14155,8 @@ Package object of the Open vSwitch. @defvr {Scheme Variable} pagekite-service-type This is the service type for the @uref{https://pagekite.net, PageKite} service, a tunneling solution for making localhost servers publicly visible, even from -behind NAT or restrictive firewalls. The value for this service type is a -@code{pagekite-configuration} record. +behind restrictive firewalls or NAT without forwarded ports. The value for +this service type is a @code{pagekite-configuration} record. Here's an example exposing the local HTTP and SSH daemons: @@ -15951,6 +15952,58 @@ pcm.!default @{ See @uref{https://www.alsa-project.org/main/index.php/Asoundrc} for the details. +@deffn {Scheme Variable} pulseaudio-service-type +This is the type for the @uref{http://www.pulseaudio.org/, PulseAudio} +sound server. It exists to allow system overrides of the default settings +via @code{pulseaudio-configuration}, see below. + +@quotation Warning +This service on its own does not ensure, that the @code{pulseaudio} package +exists on your machine. It merely adds configuration files for it, as +detailed below. In the (admittedly unlikely) case, that you find yourself +without a @code{pulseaudio} package, consider enabling it through the +@code{alsa-service-type} above. +@end quotation +@end deffn + +@deftp {Data Type} pulseaudio-configuration +Data type representing the configuration for @code{pulseaudio-service}. + +@table @asis +@item @var{client-conf} (default: @code{'()}) +List of settings to set in @file{client.conf}. +Accepts a list of strings or a symbol-value pairs. A string will be +inserted as-is with a newline added. A pair will be formatted as +``key = value'', again with a newline added. + +@item @var{daemon-conf} (default: @code{'((flat-volumes . no))}) +List of settings to set in @file{daemon.conf}, formatted just like +@var{client-conf}. + +@item @var{script-file} (default: @code{(file-append pulseaudio "/etc/pulse/default.pa")}) +Script file to use as as @file{default.pa}. + +@item @var{system-script-file} (default: @code{(file-append pulseaudio "/etc/pulse/system.pa")}) +Script file to use as as @file{system.pa}. +@end table +@end deftp + +@deffn {Scheme Variable} ladspa-service-type +This service sets the @var{LADSPA_PATH} variable, so that programs, which +respect it, e.g. PulseAudio, can load LADSPA plugins. + +The following example will setup the service to enable modules from the +@code{swh-plugins} package: + +@lisp +(service ladspa-service-type + (ladspa-configuration (plugins (list swh-plugins)))) +@end lisp + +See @uref{http://plugin.org.uk/ladspa-swh/docs/ladspa-swh.html} for the +details. + +@end deffn @node Database Services @subsection Database Services @@ -21926,6 +21979,78 @@ The @code{(gnu services nfs)} module provides the following services, which are most commonly used in relation to mounting or exporting directory trees as @dfn{network file systems} (NFS). +While it is possible to use the individual components that together make +up a Network File System service, we recommended to configure an NFS +server with the @code{nfs-service-type}. + +@subsubheading NFS Service +@cindex NFS, server + +The NFS service takes care of setting up all NFS component services, +kernel configuration file systems, and installs configuration files in +the locations that NFS expects. + +@defvr {Scheme Variable} nfs-service-type +A service type for a complete NFS server. +@end defvr + +@deftp {Data Type} nfs-configuration +This data type represents the configuration of the NFS service and all +of its subsystems. + +It has the following parameters: +@table @asis +@item @code{nfs-utils} (default: @code{nfs-utils}) +The nfs-utils package to use. + +@item @code{nfs-version} (default: @code{#f}) +If a string value is provided, the @command{rpc.nfsd} daemon will be +limited to supporting the given version of the NFS protocol. + +@item @code{exports} (default: @code{'()}) +This is a list of directories the NFS server should export. Each entry +is a list consisting of two elements: a directory name and a string +containing all options. This is an example in which the directory +@file{/export} is served to all NFS clients as a read-only share: + +@lisp +(nfs-configuration + (exports + '(("/export" + "*(ro,insecure,no_subtree_check,crossmnt,fsid=0)")))) +@end lisp + +@item @code{rpcmountd-port} (default: @code{#f}) +The network port that the @command{rpc.mountd} daemon should use. + +@item @code{rpcstatd-port} (default: @code{#f}) +The network port that the @command{rpc.statd} daemon should use. + +@item @code{rpcbind} (default: @code{rpcbind}) +The rpcbind package to use. + +@item @code{idmap-domain} (default: @code{"localdomain"}) +The local NFSv4 domain name. + +@item @code{nfsd-port} (default: @code{2049}) +The network port that the @command{nfsd} daemon should use. + +@item @code{nfsd-threads} (default: @code{8}) +The number of threads used by the @command{nfsd} daemon. + +@item @code{pipefs-directory} (default: @code{"/var/lib/nfs/rpc_pipefs"}) +The directory where the pipefs file system is mounted. + +@item @code{debug} (default: @code{'()"}) +A list of subsystems for which debugging output should be enabled. This +is a list of symbols. Any of these symbols are valid: @code{nfsd}, +@code{nfs}, @code{rpc}, @code{idmap}, @code{statd}, or @code{mountd}. +@end table +@end deftp + +If you don't need a complete NFS service or prefer to build it yourself +you can use the individual component services that are documented below. + @subsubheading RPC Bind Service @cindex rpcbind @@ -22030,6 +22155,9 @@ The local NFSv4 domain name. This must be a string or @code{#f}. If it is @code{#f} then the daemon will use the host's fully qualified domain name. +@item @code{verbosity} (default: @code{0}) +The verbosity level of the daemon. + @end table @end deftp @@ -25958,26 +26086,36 @@ supported: Display available service type definitions that match the given regular expressions, sorted by relevance: +@cindex HDPI +@cindex HiDPI +@cindex resolution @example -$ guix system search console font +$ guix system search console name: console-fonts -location: gnu/services/base.scm:729:2 +location: gnu/services/base.scm:806:2 extends: shepherd-root -description: Install the given fonts on the specified ttys (fonts are -+ per virtual console on GNU/Linux). The value of this service is a list -+ of tty/font pairs like: +description: Install the given fonts on the specified ttys (fonts are per ++ virtual console on GNU/Linux). The value of this service is a list of ++ tty/font pairs. The font can be the name of a font provided by the `kbd' ++ package or any valid argument to `setfont', as in this example: + -+ '(("tty1" . "LatGrkCyr-8x16")) -relevance: 20 ++ '(("tty1" . "LatGrkCyr-8x16") ++ ("tty2" . (file-append ++ font-tamzen ++ "/share/kbd/consolefonts/TamzenForPowerline10x20.psf")) ++ ("tty3" . (file-append ++ font-terminus ++ "/share/consolefonts/ter-132n"))) ; for HDPI +relevance: 9 name: mingetty -location: gnu/services/base.scm:1048:2 +location: gnu/services/base.scm:1190:2 extends: shepherd-root description: Provide console login using the `mingetty' program. relevance: 2 name: login -location: gnu/services/base.scm:775:2 +location: gnu/services/base.scm:860:2 extends: pam description: Provide a console log-in service as specified by its + configuration value, a `login-configuration' object. |