diff options
Diffstat (limited to 'doc/contributing.texi')
| -rw-r--r-- | doc/contributing.texi | 113 |
1 files changed, 75 insertions, 38 deletions
diff --git a/doc/contributing.texi b/doc/contributing.texi index 66f4e86d0a..b8adc169d8 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -235,7 +235,7 @@ more information. Then, run: @example -./configure --localstatedir=/var --sysconfdir=/etc +./configure @end example @noindent @@ -246,19 +246,6 @@ normal @code{sysconfdir} value. Note that you will probably not run 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. - Finally, you can build Guix and, if you feel so inclined, run the tests (@pxref{Running the Test Suite}): @@ -276,25 +263,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.}: + +@example +guix git authenticate +@end example -Or, when your configuration for your local Git repository doesn't match +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 @@ -2298,9 +2301,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 +2311,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,6 +2363,9 @@ 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. + @node Debbugs User Interfaces @subsection Debbugs User Interfaces |