diff options
Diffstat (limited to 'doc/contributing.texi')
| -rw-r--r-- | doc/contributing.texi | 867 |
1 files changed, 729 insertions, 138 deletions
diff --git a/doc/contributing.texi b/doc/contributing.texi index 66f4e86d0a..d4784de452 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -31,11 +31,15 @@ choice. * Coding Style:: Hygiene of the contributor. * Submitting Patches:: Share your work. * Tracking Bugs and Changes:: Keeping it all organized. +* Teams:: Coordinating efforts. +* Making Decisions:: Collectively choosing the way forward. * Commit Access:: Pushing to the official repository. * Reviewing the Work of Others:: Some guidelines for sharing reviews. * Updating the Guix Package:: Updating the Guix package definition. +* Deprecation Policy:: Commitments and tools for deprecation. * Writing Documentation:: Improving documentation in GNU Guix. * Translating Guix:: Make Guix speak your native language. +* Contributing to Guix's Infrastructure:: Make Guix ecosystem work better. @end menu @node Requirements @@ -235,29 +239,17 @@ more information. Then, run: @example -./configure --localstatedir=/var --sysconfdir=/etc +./configure @end example @noindent -... where @file{/var} is the normal @code{localstatedir} value -(@pxref{The Store}, for information about this) and @file{/etc} is the -normal @code{sysconfdir} value. 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} and @code{sysconfdir} -values, which get recorded in the @code{(guix config)} Guile module. - -When configuring Guix on a system that already has a Guix installation, -be sure to specify the same state directory as the existing installation -using the @option{--localstatedir} option of the @command{configure} -script (@pxref{Directory Variables, @code{localstatedir},, standards, -GNU Coding Standards}). Usually, this @var{localstatedir} option is set -to the value @file{/var}. The @command{configure} script protects -against unintended misconfiguration of @var{localstatedir} so you do not -inadvertently corrupt your store (@pxref{The Store}). The configuration -directory should also be configured by setting the @option{--sysconfdir} -option to the @file{/etc} value, which is the location used by Guix to -store for example the access control list of authorized machines and the -definition of offload machines. +Optionally, @code{--localstatedir} and @code{--sysconfdir} can also be +provided as arguments. By default, @code{localstatedir} is @file{/var} +(@pxref{The Store}, for information about this) and @code{sysconfdir} is +@file{/etc}. 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} and @code{sysconfdir} values, which get +recorded in the @code{(guix config)} Guile module. Finally, you can build Guix and, if you feel so inclined, run the tests (@pxref{Running the Test Suite}): @@ -276,25 +268,41 @@ From there on, you can authenticate all the commits included in your checkout by running: @example -make authenticate +guix git authenticate \ + 9edb3f66fd807b096b48283debdcddccfea34bad \ + "BBB0 2DDF 2CEA F6A8 0D1D E643 A2A0 6DF2 A33A 54FA" @end example The first run takes a couple of minutes, but subsequent runs are faster. +On subsequent runs, you can run the command without any arguments since +the @dfn{introduction} (the commit ID and OpenPGP fingerprints above) +will have been recorded@footnote{This requires a recent version of Guix, +from May 2024 or more recent.}: -Or, when your configuration for your local Git repository doesn't match +@example +guix git authenticate +@end example + +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 +branch @i{via} the @option{-k} option. 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 +guix git authenticate \ + -k myremote/keyring \ + 9edb3f66fd807b096b48283debdcddccfea34bad \ + "BBB0 2DDF 2CEA F6A8 0D1D E643 A2A0 6DF2 A33A 54FA" @end example +@xref{Invoking guix git authenticate}, for more information on this +command. + @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. +By default, hooks are installed such that @command{guix git +authenticate} is invoked anytime you run @command{git pull} or +@command{git push}. @end quotation After updating the repository, @command{make} might fail with an error @@ -408,6 +416,20 @@ computationally intensive or rather cheap, depending on whether substitutes are available for their dependencies (@pxref{Substitutes}). Some of them require a lot of storage space to hold VM images. +If you encounter an error like: + +@example +Compiling Scheme modules... +ice-9/eval.scm:142:16: In procedure compile-top-call: +error: all-system-tests: unbound variable +hint: Did you forget `(use-modules (gnu tests))'? +@end example + +@noindent +there may be inconsistencies in the work tree from previous builds. To +resolve this, try running @command{make clean-go} followed by +@command{make}. + Again in case of test failures, please send @email{bug-guix@@gnu.org} all the details. @@ -847,7 +869,7 @@ example, the @code{(guix scripts shell)} module exports the This contains supporting code for the importers and updaters (@pxref{Invoking guix import}, and @pxref{Invoking guix refresh}). For example, @code{(guix import pypi)} defines the interface to PyPI, which -is used by the @code{guix import pypi} command. +is used by the @command{guix import pypi} command. @end table The directories we have seen so far all live under @file{guix/}. The @@ -1883,17 +1905,19 @@ Take some time to provide an adequate synopsis and description for the package. @xref{Synopses and Descriptions}, for some guidelines. @item -Run @code{guix lint @var{package}}, where @var{package} is the +Run @command{guix lint @var{package}}, where @var{package} is the name of the new or modified package, and fix any errors it reports (@pxref{Invoking guix lint}). @item -Run @code{guix style @var{package}} to format the new package definition +Run @command{guix style @var{package}} to format the new package definition according to the project's conventions (@pxref{Invoking guix style}). @item -Make sure the package builds on your platform, using @code{guix build -@var{package}}. +Make sure the package builds on your platform, using @command{guix build +@var{package}}. Also build at least its direct dependents with +@command{guix build --dependents=1 @var{package}} +(@pxref{build-dependents, @command{guix build}}). @item We recommend you also try building the package on other supported @@ -1945,7 +1969,7 @@ adding @code{texlive} as a dependency: because of its extreme size, use @item Check that dependent packages (if applicable) are not affected by the -change; @code{guix refresh --list-dependent @var{package}} will help you +change; @command{guix refresh --list-dependent @var{package}} will help you do that (@pxref{Invoking guix refresh}). @item @@ -1997,7 +2021,7 @@ Please follow our code formatting rules, possibly running 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 +often better to clone the repository. Don't use the @code{name} field in the URL: it is not very useful and if the name changes, the URL will probably be wrong. @@ -2006,7 +2030,8 @@ 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: +Make sure your changes do not break Guix and simulate a @command{guix pull} +with: @example guix pull --url=/path/to/your/checkout --profile=/tmp/guix.master @end example @@ -2018,11 +2043,12 @@ 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. +You may use your email client, the @command{git send-email} command +(@pxref{Sending a Patch Series}) or the @command{mumi send-email} +command (@pxref{Debbugs User Interfaces}). 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. Expect some delay when you submit your very first patch to @email{guix-patches@@gnu.org}. You have to wait until you get an @@ -2035,7 +2061,6 @@ When a bug is resolved, please close the thread by sending an email to @menu * Configuring Git:: * Sending a Patch Series:: -* Teams:: @end menu @node Configuring Git @@ -2166,9 +2191,21 @@ with @command{git format-patch}. @example $ git format-patch -@var{NUMBER_COMMITS} -o outgoing \ - --cover-letter --base=auto + --cover-letter @end example +@quotation Note +@code{git format-patch} accepts a wide range of +@uref{https://git-scm.com/docs/gitrevisions, revision range} specifiers. +For example, if you are working in a branch, you could select all commits +in your branch starting at @code{master}. + +@example +$ git format-patch master..@var{MY_BRANCH} -o outgoing \ + --cover-letter +@end example +@end quotation + We can now send @emph{just} the cover letter to the @email{guix-patches@@gnu.org} address, which will create an issue that we can send the rest of the patches to. @@ -2203,44 +2240,6 @@ If need be, you may use @option{--cover-letter --annotate} to send another cover letter, e.g. for explaining what's changed since the last revision, and these changes are necessary. -@node Teams -@subsection Teams -@cindex teams - -There are several teams mentoring different parts of the Guix source -code. To list all those teams, you can run from a Guix checkout: - -@example -$ ./etc/teams.scm list-teams -id: mentors -name: Mentors -description: A group of mentors who chaperone contributions by newcomers. -members: -+ Christopher Baines <mail@@cbaines.net> -+ Ricardo Wurmus <rekado@@elephly.net> -+ Mathieu Othacehe <othacehe@@gnu.org> -+ jgart <jgart@@dismail.de> -+ Ludovic Courtès <ludo@@gnu.org> -@dots{} -@end example - -You can run the following command to have the @code{Mentors} team put in -CC of a patch series: - -@example -$ git send-email --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org \ - --header-cmd='etc/teams.scm cc-mentors-header-cmd' *.patch -@end example - -The appropriate team or teams can also be inferred from the modified -files. For instance, if you want to send the two latest commits of the -current Git repository to review, you can run: - -@example -$ guix shell -D guix -[env]$ git send-email --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org -2 -@end example - @node Tracking Bugs and Changes @section Tracking Bugs and Changes @@ -2298,9 +2297,9 @@ indication of its build status on various platforms. @cindex feature branches, coordination To help coordinate the merging of branches, you must create a new -guix-patches issue each time you wish to merge a branch (@pxref{The -Issue Tracker}). The title of the issue requesting to merge a branch -should have the following format: +guix-patches issue each time you create a branch (@pxref{The Issue +Tracker}). The title of the issue requesting to merge a branch should +have the following format: @cindex merge requests, template @example @@ -2308,20 +2307,51 @@ Request for merging "@var{name}" branch @end example The @url{https://qa.guix.gnu.org/, QA infrastructure} recognizes such -issues and lists the merge requests on its main page. Normally branches -will be merged in a ``first come, first merged'' manner, tracked through -the guix-patches issues. - -If you agree on a different order with those involved, you can track -this by updating which issues block@footnote{You can mark an issue as -blocked by another by emailing @email{control@@debbugs.gnu.org} with the -following line in the body of the email: @code{block XXXXX by YYYYY}. -Where @code{XXXXX} is the number for the blocked issue, and @code{YYYYY} -is the number for the issue blocking it.} which other issues. -Therefore, to know which branch is at the front of the queue, look for -the oldest issue, or the issue that isn't @dfn{blocked} by any other -branch merges. An ordered list of branches with the open issues is -available at @url{https://qa.guix.gnu.org}. +issues and lists the merge requests on its main page. The following +points apply to managing these branches: + +@enumerate +@item +The commits on the branch should be a combination of the patches +relevant to the branch. Patches not related to the topic of the branch +should go elsewhere. + +@item +Any changes that can be made on the master branch, should be made on the +master branch. If a commit can be split to apply part of the changes on +master, this is good to do. + +@item +It should be possible to re-create the branch by starting from master +and applying the relevant patches. + +@item +Avoid merging master in to the branch. Prefer rebasing or re-creating +the branch on top of an updated master revision. + +@item +Minimise the changes on master that are missing on the branch prior to +merging the branch in to master. This means that the state of the +branch better reflects the state of master should the branch be merged. + +@item +If you don't have commit access, create the ``Request for merging'' +issue and request that someone creates the branch. Include a list of +issues/patches to include on the branch. +@end enumerate + +Normally branches will be merged in a ``first come, first merged'' +manner, tracked through the guix-patches issues. If you agree on a +different order with those involved, you can track this by updating +which issues block@footnote{You can mark an issue as blocked by another +by emailing @email{control@@debbugs.gnu.org} with the following line in +the body of the email: @code{block XXXXX by YYYYY}. Where @code{XXXXX} +is the number for the blocked issue, and @code{YYYYY} is the number for +the issue blocking it.} which other issues. Therefore, to know which +branch is at the front of the queue, look for the oldest issue, or the +issue that isn't @dfn{blocked} by any other branch merges. An ordered +list of branches with the open issues is available at +@url{https://qa.guix.gnu.org}. Once a branch is at the front of the queue, wait until sufficient time has passed for the build farms to have processed the changes, and for @@ -2329,22 +2359,37 @@ the necessary testing to have happened. For example, you can check @indicateurl{https://qa.guix.gnu.org/branch/@var{branch}} to see information on some builds and substitute availability. +Once the branch has been merged, the issue should be closed and the +branch deleted. + +@cindex work-in-progress branches, wip +@cindex wip branches +Sometimes, a branch may be a work in progress, for example for larger +efforts such as updating the GNOME desktop. In these cases, the branch +name should reflect this by having the @samp{wip-} prefix. The QA +infrastructure will avoid building work-in-progress branches, so that +the available resources can be better focused on building the branches +that are ready to be merged. When the branch is no longer a work in +progress, it should be renamed, with the @samp{wip-} prefix removed, and +only then should the merge requests be created, as documented earlier. + @node Debbugs User Interfaces @subsection Debbugs User Interfaces @subsubsection Web interface +@cindex mumi, web interface for issues A web interface (actually @emph{two} web interfaces!) are available to browse issues: @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.savannah.gnu.org/cgit/guix/mumi.git}.} to browse -bug reports and patches, and to participate in discussions; +@url{https://issues.guix.gnu.org} provides a pleasant interface powered +by mumi@footnote{Mumi is a nice piece of software written in Guile, and +you can help! See +@url{https://git.savannah.gnu.org/cgit/guix/mumi.git}.} to browse bug +reports and patches, and to participate in discussions; mumi also has a +command-line interface as we will see below; @item @url{https://bugs.gnu.org/guix} lists bug reports; @item @@ -2355,12 +2400,17 @@ 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}}. -@subsubsection Command-line interface +@subsubsection Command-Line Interface +@cindex mumi command-line interface +@cindex mumi am +@cindex mumi compose +@cindex mumi send-email +@cindex mumi www Mumi also comes with a command-line interface that can be used to search -existing issues, open new issues and send patches. You do not need to -use Emacs to use the mumi command-line client. You interact with it -only on the command-line. +existing issues, open new issues, compose replies, apply and send +patches. You do not need to use Emacs to use the mumi command-line +client. You interact with it only on the command-line. To use the mumi command-line interface, navigate to a local clone of the Guix git repository, and drop into a shell with mumi, git and @@ -2397,8 +2447,61 @@ Pick an issue and make it the "current" issue. opened on 24 Jan 09:42 Z by Efraim Flashner @end example -Once an issue is the current issue, you can easily create and send -patches to it using +Once an issue is the current issue, you can open the issue in a web +browser, compose replies, apply patches, send patches, etc. with short +succinct commands. + +Open the issue in your web browser using + +@example +~/guix [env]$ mumi www +@end example + +Compose a reply using + +@example +~/guix [env]$ mumi compose +@end example + +Compose a reply and close the issue using + +@example +~/guix [env]$ mumi compose --close +@end example + +@command{mumi compose} opens your mail client by passing @samp{mailto:} +URIs to @command{xdg-open}. So, you need to have @command{xdg-open} set +up to open your mail client correctly. + +Apply the latest patchset from the issue using + +@example +~/guix [env]$ mumi am +@end example + +You may also apply a patchset of a specific version (say, v3) using + +@example +~/guix [env]$ mumi am v3 +@end example + +Or, you may apply a patch from a specific e-mail message. For example, +to apply the patch from the 4th message (message index starts from 0), +run + +@example +~/guix [env]$ mumi am @@4 +@end example + +@command{mumi am} is a wrapper around @command{git am}. You can pass +@command{git am} arguments to it after a @samp{--}. For example, to add +a Signed-off-by trailer, run + +@example +~/guix [env]$ mumi am -- -s +@end example + +Create and send patches to the issue using @example ~/guix [env]$ git format-patch origin/master @@ -2415,11 +2518,8 @@ To open a new issue, run ~/guix [env]$ mumi new @end example -and send patches - -@example -~/guix [env]$ mumi send-email foo.patch bar.patch -@end example +and send an email (using @command{mumi compose}) or patches (using +@command{mumi send-email}). @command{mumi send-email} is really a wrapper around @command{git send-email} that automates away all the nitty-gritty of sending patches. @@ -2435,7 +2535,7 @@ so by sending the first patch, polling the server for a response, and then sending the remaining patches. This polling can unfortunately take a few minutes. So, please be patient. -@subsubsection Emacs interface +@subsubsection Emacs Interface If you use Emacs, you may find it more convenient to interact with issues using @file{debbugs.el}, which you can install with: @@ -2556,6 +2656,102 @@ notifications that read like: where each RSS entry contains a link to the Cuirass build details page of the associated build. +@node Teams +@section Teams +@cindex teams + +To organize work on Guix, including but not just development efforts, +the project has a set of @dfn{teams}. Each team has its own focus and +interests and is the primary contact point for questions and +contributions in those areas. A team's primary mission is to coordinate +and review the work of individuals in its scope (@pxref{Reviewing the +Work of Others}); it can make decisions within its scope, in agreement +with other teams whenever there is overlap or a close connection, and in +accordance with other project rules such as seeking consensus +(@pxref{Making Decisions}). + +As an example, the Python team is responsible for core Python packaging +matters; it can decide to upgrade core Python packages in a dedicated +@code{python-team} branch, in collaboration with any team whose scope is +directly dependent on Python---e.g., the Science team---and following +branching rules (@pxref{Managing Patches and Branches}). The +Documentation team helps review changes to the documentation and can +initiate overarching documentation changes. The Translations team +organizes translation of Guix and its manual and coordinates efforts in +that area. The Core team is responsible for the development of core +functionality and interfaces of Guix; because of its central nature, +some of its work may require soliciting input from the community at +large and seeking consensus before enacting decisions that would affect +the entire community. + +Teams are defined in the @file{etc/teams.scm} file in the Guix +repository. The scope of each team is defined, when applicable, as a +set of files or as a regular expression matching file names. + +@cindex team membership +Anyone with interest in a team's domain and willing to contribute to its +work can apply to become a member by contacting current members by +email; commit access is not a precondition. Membership is formalized by +adding the person's name and email address to @file{etc/teams.scm}. +Members who have not been participating in the team's work for one year +or more may be removed; they are free to reapply for membership later. + +@cindex team creation +One or more people may propose the creation of a new team by reaching +out to the community by email at @email{guix-devel@@gnu.org}, clarifying +the intended scope and purpose. When consensus is reached on the +creation of this team, someone with commit access formalizes its +creation by adding it and its initial members to @file{etc/teams.scm}. + +To list existing teams, run the following command from a Guix checkout: + +@example +$ ./etc/teams.scm list-teams +id: mentors +name: Mentors +description: A group of mentors who chaperone contributions by newcomers. +members: ++ Charlie Smith <charlie@@example.org> +@dots{} +@end example + +@cindex mentoring +You can run the following command to have the Mentors team put in +CC of a patch series: + +@example +$ git send-email --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org \ + --header-cmd='etc/teams.scm cc-mentors-header-cmd' *.patch +@end example + +The appropriate team or teams can also be inferred from the modified +files. For instance, if you want to send the two latest commits of the +current Git repository to review, you can run: + +@example +$ guix shell -D guix +[env]$ git send-email --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org -2 +@end example + +@node Making Decisions +@section Making Decisions + +@cindex decision making +@cindex consensus seeking +It is expected from all contributors, and even more so from committers, +to help build consensus and make decisions based on consensus. By using +consensus, we are committed to finding solutions that everyone can live +with. It implies that no decision is made against significant concerns +and these concerns are actively resolved with proposals that work for +everyone. + +A contributor (who may or may not have commit access) wishing to block +a proposal bears a special responsibility for finding alternatives, +proposing ideas/code or explain the rationale for the status quo to +resolve the deadlock. To learn what consensus decision making means and +understand its finer details, you are encouraged to read +@url{https://www.seedsforchange.org.uk/consensus}. + @node Commit Access @section Commit Access @@ -2569,18 +2765,12 @@ project for at least 6 months. This ensures enough interactions with the contributor, which is essential for mentoring and assessing whether they are ready to become a committer. Commit access should not be thought of as a ``badge of honor'' but rather as a responsibility a -contributor is willing to take to help the project. It is expected from -all contributors, and even more so from committers, to help build -consensus and make decisions based on consensus. By using consensus, we -are committed to finding solutions that everyone can live with. It -implies that no decision is made against significant concerns and these -concerns are actively resolved with proposals that work for everyone. A -contributor (which may or may not have commit access) wishing to block a -proposal bears a special responsibility for finding alternatives, -proposing ideas/code or explain the rationale for the status quo to -resolve the deadlock. To learn what consensus decision making means and -understand its finer details, you are encouraged to read -@url{https://www.seedsforchange.org.uk/consensus}. +contributor is willing to take to help the project. + +Committers are in a position where they enact technical decisions. Such +decisions must be made by @emph{actively building consensus} among +interested parties and stakeholders. @xref{Making Decisions}, for more +on that. The following sections explain how to get commit access, how to be ready to push commits, and the policies and community expectations for commits @@ -2676,9 +2866,12 @@ git config user.signingkey CABBA6EA1DC0FF33 To check that commits are signed with correct key, use: @example -make authenticate +guix git authenticate @end example +@xref{Building from Git} for running the first authentication of a Guix +checkout. + To avoid accidentally pushing unsigned or signed with the wrong key commits to Savannah, make sure to configure Git according to @xref{Configuring Git}. @@ -2694,9 +2887,11 @@ Ensure you're aware of how the changes should be handled repository, especially for the @code{master} branch. If you're committing and pushing your own changes, try and wait at least -one week (two weeks for more significant changes) after you send them -for review. After this, if no one else is available to review them and -if you're confident about the changes, it's OK to commit. +one week (two weeks for more significant changes, up to one month for +changes such as removing a package---@pxref{package-removal-policy, +Package Removal}) after you send them for review. After this, if no one +else is available to review them and if you're confident about the +changes, it's OK to commit. 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., @@ -2794,12 +2989,14 @@ Perhaps the biggest action you can do to help GNU Guix grow as a project is to review the work contributed by others. You do not need to be a committer to do so; applying, reading the source, building, linting and running other people's series and sharing your comments about your -experience will give some confidence to committers. Basically, you must +experience will give some confidence to committers. You must ensure the check list found in the @ref{Submitting Patches} section has been correctly followed. A reviewed patch series should give the best chances for the proposed change to be merged faster, so if a change you would like to see merged hasn't yet been reviewed, this is the most -appropriate thing to do! +appropriate thing to do! If you would like to review changes in a +specific area and to receive notifications for incoming patches relevant +to that domain, consider joining the relevant team(s) (@pxref{Teams}). @cindex reviewing, guidelines Review comments should be unambiguous; be as clear and explicit as you @@ -2846,6 +3043,8 @@ preference for the color of the shed at the expense of progress made on the project to keep bikes dry.}. As a reviewer, try hard to explain the rationale for suggestions you make, and to understand and take into account the submitter's motivation for doing things in a certain way. +In other words, build consensus with everyone involved (@pxref{Making +Decisions}). @end enumerate @cindex LGTM, Looks Good To Me @@ -2853,7 +3052,7 @@ account the submitter's motivation for doing things in a certain way. @cindex Reviewed-by, git trailer When you deem the proposed change adequate and ready for inclusion within Guix, the following well understood/codified -@samp{Reviewed-by:@tie{}Your@tie{}Name<your-email@@example.com>} +@samp{Reviewed-by:@tie{}Your@tie{}Name@tie{}<your-email@@example.com>} @footnote{The @samp{Reviewed-by} Git trailer is used by other projects such as Linux, and is understood by third-party tools such as the @samp{b4 am} sub-command, which is able to retrieve the complete @@ -2865,7 +3064,8 @@ looks good to you: @itemize @item If the @emph{whole} series (containing multiple commits) looks good to -you, reply with @samp{Reviewed-by:@tie{}Your@tie{}Name<your-email@@example.com>} +you, reply with +@samp{Reviewed-by:@tie{}Your@tie{}Name@tie{}<your-email@@example.com>} to the cover page if it has one, or to the last patch of the series otherwise, adding another @samp{(for the whole series)} comment on the line below to explicit this fact. @@ -2873,8 +3073,8 @@ line below to explicit this fact. @item If you instead want to mark a @emph{single commit} as reviewed (but not the whole series), simply reply with -@samp{Reviewed-by:@tie{}Your@tie{}Name<your-email@@example.com>} to that -commit message. +@samp{Reviewed-by:@tie{}Your@tie{}Name@tie{}<your-email@@example.com>} +to that commit message. @end itemize If you are not a committer, you can help others find a @emph{series} you @@ -2918,6 +3118,196 @@ This check can be disabled, @emph{at your own peril}, by setting the 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. +@node Deprecation Policy +@section Deprecation Policy + +@cindex deprecation policy +As any lively project with a broad scope, Guix changes all the time and +at all levels. Because it's user-extensible and programmable, +incompatible changes can directly impact users and make their life +harder. It is thus important to reduce user-visible incompatible +changes to a minimum and, when such changes are deemed necessary, to +clearly communicate them through a @dfn{deprecation period} so everyone +can adapt with minimum hassle. This section defines the project's +commitments for smooth deprecation and describes procedures and +mechanisms to honor them. + +There are several ways to use Guix; how to handle deprecation will +depend on each use case. Those can be roughly categorized like this: + +@itemize +@item +package management exclusively through the command line; + +@item +advanced package management using the manifest and package interfaces; + +@item +Home and System management, using the @code{operating-system} and/or +@code{home-environment} interfaces together with the service interfaces; + +@item +development or use of external tools that use programming interfaces +such as the @code{(guix ...)} modules. +@end itemize + +These use cases form a spectrum with varying degrees of coupling---from +``distant'' to tightly coupled. Based on this insight, we define the +following @dfn{deprecation policies} that we consider suitable for each +of these levels. + +@table @asis +@item Command-line tools +Guix sub-commands should be thought of as remaining available +``forever''. Once a Guix sub-command is to be removed, it should be +deprecated first, and then remain available for @b{at least one year} +after the first release that deprecated it. + +Deprecation should first be announced in the manual and as an entry in +@file{etc/news.scm}; additional communication such as a blog post +explaining the rationale is welcome. Months before the scheduled +removal date, the command should print a warning explaining how to +migrate. An example of this is the replacement of @command{guix +environment} by @command{guix shell}, started in October +2021@footnote{For more details on the @command{guix shell} transition, +see +@uref{https://guix.gnu.org/en/blog/2021/from-guix-environment-to-guix-shell/}.}. + +Because of the broad impact of such a change, we recommend conducting a +user survey before enacting a plan. + +@cindex package deprecation +@item Package name changes +When a package name changes, it must remain available under its old name +for @b{at least one year}. For example, @code{go-ipfs} was renamed to +@code{kubo} following a decision made upstream; to communicate the name +change to users, the package module provided this definition: + +@findex deprecated-package +@lisp +(define-public go-ipfs + (deprecated-package "go-ipfs" kubo)) +@end lisp + +That way, someone running @command{guix install go-ipfs} or similar sees +a deprecation warning mentioning the new name. + +@cindex package removal policy +@anchor{package-removal-policy} +@item Package removal +Packages whose upstream developers have declared as having reached ``end +of life'' or being unmaintained may be removed; likewise, packages that +have been @b{failing to build for two months or more} may be removed. + +There is no formal deprecation mechanism for this case, unless a +replacement exists, in which case the @code{deprecated-package} +procedure mentioned above can be used. + +If the package being removed is a ``leaf'' (no other packages depend on +it), it may be removed after a @b{one-month review period} of the patch +removing it (this applies even when the removal has additional +motivations such as security problems affecting the package). + +If it has many dependent packages---as is the case for example with +Python version@tie{}2---the relevant team must propose a deprecation +removal agenda and seek consensus with other packagers for @b{at least +one month}. It may also invite feedback from the broader user +community, for example through a survey. Removal of all impacted +packages may be gradual, spanning multiple months, to accommodate all +use cases. + +When the package being removed is considered popular, whether or not it +is a leaf, its deprecation must be announced as an entry in +@code{etc/news.scm}. + +@item Package upgrade +In the case of packages with many dependents and/or many users, an +upgrade may be treated like the @emph{removal} of the previous version. + +Examples include major version upgrades of programming language +implementations, as we've seen above with Python, and major upgrades of +``big'' libraries such as Qt or GTK. + +@cindex service deprecation +@item Services +Changes to services for Guix Home and Guix System have a direct impact +on user configuration. For a user, adjusting to interface changes is +rarely rewarding, which is why any such change must be clearly +communicated in advance through deprecation warnings and documentation. + +Renaming of variables related to service, home, or system configuration +must be communicated for at least six months before removal using the +@code{(guix deprecation)} mechanisms. For example, renaming of +@code{murmur-configuration} to @code{mumble-server-configuration} was +communicated through a series of definitions like this one: + +@findex define-deprecated/public-alias +@lisp +(define-deprecated/public-alias + murmur-configuration + mumble-server-configuration) +@end lisp + +Procedures slated for removal may be defined like this: + +@findex define-deprecated +@lisp +(define-deprecated (elogind-service #:key (config (elogind-configuration))) + elogind-service-type + (service elogind-service-type config)) +@end lisp + +Record fields, notably fields of service configuration records, must +follow a similar deprecation period. This is usually achieved through +@i{ad hoc} means though. For example, the @code{hosts-file} field of +@code{operating-system} was deprecated by adding a @code{sanitized} +property that would emit a warning: + +@lisp +(define-record-type* <operating-system> + ;; @dots{} + (hosts-file %operating-system-hosts-file ;deprecated + (default #f) + (sanitize warn-hosts-file-field-deprecation))) + +(define-deprecated (operating-system-hosts-file os) + hosts-service-type + (%operating-system-hosts-file os)) +@end lisp + +When deprecating interfaces in @code{operating-system}, +@code{home-environment}, @code{(gnu services)}, or any popular service, +the deprecation must come with an entry in @code{etc/news.scm}. + +@cindex deprecation of programming interfaces +@item Core interfaces +Core programming interfaces, in particular the @code{(guix ...)} +modules, may be relied on by a variety of external tools and channels. +Any incompatible change must be formally deprecated with +@code{define-deprecated}, as shown above, for @b{at least one year} +before removal. The manual must clearly document the new interface and, +except in obvious cases, explain how to migrate from the old one. + +As an example, the @code{build-expression->derivation} procedure was +superseded by @code{gexp->derivation} and remained available as a +deprecated symbol: + +@lisp +(define-deprecated (build-expression->derivation store name exp + #:key @dots{}) + gexp->derivation + @dots{}) +@end lisp + +Sometimes bindings are moved from one module to another. In those +cases, bindings must be reexported from the original module for at least +one year. +@end table + +This section does not cover all possible situations but hopefully allows +users to know what to expect and developers to stick to its spirit. +Please email @email{guix-devel@@gnu.org} for any questions. + @cindex documentation @node Writing Documentation @section Writing Documentation @@ -2983,7 +3373,7 @@ 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'' +@code{hello} package by typing @command{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 @@ -3243,3 +3633,204 @@ differs for the various components. be updated accordingly (see @file{website/i18n-howto.txt} for more information on the process). @end itemize + + +@cindex infrastructure +@node Contributing to Guix's Infrastructure +@section Contributing to Guix's Infrastructure + +Since its inception, the Guix project has always valued its autonomy, and that +reflects in its infrastructure: our servers run Guix System and exclusively +free software, and are administered by volunteers. + +Of course this comes at a cost and this is why we need contributions. Our hope +is to make infrastructure-related activity more legible so that maybe you can +picture yourself helping in one of these areas. + + +@menu +* Coding:: +* System Administration:: +* Day-to-Day System Administration:: +* On-Site Intervention:: +* Hosting:: +* Administrative Tasks:: +@end menu + +@node Coding +@subsection Coding + +The project runs many Guix-specific services; this is all lovely Scheme code +but it tends to receive less attention than Guix itself: + +@itemize +@item +Build Farm Front-End: @url{https://git.cbaines.net/guix/bffe, bffe} +@item +Cuirass: @url{https://guix.gnu.org/cuirass/, Cuirass} +@item +Goggles (IRC logger): +@url{https://git.savannah.gnu.org/cgit/guix/maintenance.git/tree/hydra/goggles.scm, +Goggles} +@item +Guix Build Coordinator: +@url{https://git.savannah.gnu.org/cgit/guix/build-coordinator.git/, +Build-Coordinator} +@item +Guix Data Service: +@url{https://git.savannah.gnu.org/git/guix/data-service.git/, Data-Service} +@item +Guix Packages Website: +@url{https://codeberg.org/luis-felipe/guix-packages-website.git, +Guix-Packages-Website} +@item +mumi: @url{https://git.savannah.gnu.org/cgit/guix/mumi.git/, Mumi} +@item +nar-herder: @url{https://git.savannah.gnu.org/cgit/guix/nar-herder.git/, +Nar-Herder} +@item +QA Frontpage: +@url{https://git.savannah.gnu.org/git/guix/qa-frontpage.git, QA-Frontpage} +@end itemize + +There is no time constraint on this coding activity: any improvement is +welcome, whenever it comes. Most of these code bases are relatively small, +which should make it easier to get started. + +Prerequisites: Familiarity with Guile, HTTP, and databases. + +If you wish to get started, check out the README of the project of your choice +and get in touch with guix-devel and the primary developer(s) of the tool as +per @code{git shortlog -s | sort -k1 -n}. + +@node System Administration +@subsection System Administration + +Guix System configuration for all our systems is held in this repository: + +@url{https://git.savannah.gnu.org/cgit/guix/maintenance.git/tree/hydra/} + +The two front-ends are @file{berlin.scm} (the machine behind ci.guix.gnu.org) +and @file{bayfront.scm} (the machine behind bordeaux.guix.gnu.org, +guix.gnu.org, hpc.guix.info, qa.guix.gnu.org, and more). Both connect to a +number of build machines and helpers. + +Without even having SSH access to the machine, you can help by posting patches +to improve the configuration (you can test it with @code{guix system vm}). +Here are ways you can help: + +@itemize +@item +Improve infra monitoring: set up a dashboard to monitor all the infrastructure, +and an out-of-band channel to communicate about downtime. + +@item +Implement web site redundancy: guix.gnu.org should be backed by several +machines on different sites. Get in touch with us and/or send a patch! + +@item +Implement substitute redundancy: likewise, bordeaux.guix.gnu.org and +ci.guix.gnu.org should be backed by several head nodes. + +@item +Improve backup: there's currently ad-hoc backup of selected pieces over rsync +between the two head nodes; we can improve on that, for example with a +dedicated backup site and proper testing of recoverability. + +@item +Support mirroring: We'd like to make it easy for others to mirror substitutes +from ci.guix and bordeaux.guix, perhaps by offering public rsync access. + +@item +Optimize our web services: Monitor the performance of our services and tweak +nginx config or whatever it takes to improve it. + +There is no time constraint on this activity: any improvement is welcome, +whenever you can work on it. + +Prerequisite: Familiarity with Guix System administration and ideally with the +infrastructure handbook: + +@url{https://git.savannah.gnu.org/cgit/guix/maintenance.git/tree/doc/infra-handbook.org, +Infra-Handbook} + +@end itemize + +@node Day-to-Day System Administration +@subsection Day-to-Day System Administration + +We're also looking for people who'd be willing to have SSH access to some of +the infrastructure to help with day-to-day maintenance: restarting a build, +restarting the occasional service that has gone wild (that can happen), +reconfiguring/upgrading a machine, rebooting, etc. + +This day-to-day activity requires you to be available some of the time (during +office hours or not, during the week-end or not), whenever is convenient for +you, so you can react to issues reported on IRC, on the mailing list, or +elsewhere, and synchronize with other sysadmins. + +Prerequisite: Being a ``known'' member of the community, familiarity with Guix +System administration, with some of the services/web sites being run, and with +the infrastructure handbook: + +@url{https://git.savannah.gnu.org/cgit/guix/maintenance.git/tree/doc/infra-handbook.org, +Infra-Handbook} + +@node On-Site Intervention +@subsection On-Site Intervention + +The first front-end is currently generously hosted by the Max Delbrück Center +(MDC), a research institute in Berlin, Germany. Only authorized personnel can +physically access it. + +The second one, bordeaux.guix.gnu.org, is hosted in Bordeaux, France, in a +professional data center shared with non-profit ISP Aquilenet. If you live in +the region of Bordeaux and would like to help out when we need to go on-site, +please make yourself known by emailing @email{guix-sysadmin@@gnu.org}. + +On-site interventions are rare, but they're usually in response to an +emergency. + +@node Hosting +@subsection Hosting + +We're looking for people who can host machines and help out whenever +physical access is needed. More specifically: + +@itemize +@item +We need hosting of ``small'' machines such as single-board computers (AArch64, +RISC-V) for use as build machines. + +@item +We need hosting for front-ends and x86_64 build machines in a data center where +they can be racked and where, ideally, several local Guix sysadmins can +physically access them. +@end itemize + +The machines should be accessible over Wireguard VPN most of the +time, so longer power or network interruptions should be the +exception. + +Prerequisites: Familiarity with installing and remotely administering Guix +System. + +@node Administrative Tasks +@subsection Administrative Tasks + +The infra remains up and running thanks to crucial administrative tasks, which +includes: + +@itemize +@item +Selecting and purchasing hardware, for example build machines. +@item +Renewing domain names. + +@item +Securing funding, in particular via the Guix Foundation: +@url{https://foundation.guix.info, Guix Foundation} +@end itemize + +Prerequisites: Familiarity with hardware, and/or DNS registrars, +and/or sponsorship, and/or crowdfunding. |