diff options
Diffstat (limited to 'doc/contributing.texi')
| -rw-r--r-- | doc/contributing.texi | 192 |
1 files changed, 173 insertions, 19 deletions
diff --git a/doc/contributing.texi b/doc/contributing.texi index 69f0327afb..ce4b9db366 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -77,6 +77,12 @@ hack on Guix: guix shell -D guix --pure @end example +or even, from within a Git worktree for Guix: + +@example +guix shell --pure +@end example + @xref{Invoking guix shell}, for more information on that command. If you are unable to use Guix when building Guix from a checkout, the @@ -204,12 +210,11 @@ 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 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): +(the @file{pre-inst-env} script lives in the top build tree of Guix; +@pxref{Building from Git} to generate it). 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 @@ -300,15 +305,10 @@ Geiser allows for interactive and incremental development from within Emacs: code compilation and evaluation from within buffers, access to on-line documentation (docstrings), context-sensitive completion, @kbd{M-.} to jump to an object definition, a REPL to try out your code, -and more (@pxref{Introduction,,, geiser, Geiser User Manual}). For -convenient Guix development, make sure to augment Guile’s load path so -that it finds source files from your checkout: - -@lisp -;; @r{Assuming the Guix checkout is in ~/src/guix.} -(with-eval-after-load 'geiser-guile - (add-to-list 'geiser-guile-load-path "~/src/guix")) -@end lisp +and more (@pxref{Introduction,,, geiser, Geiser User Manual}). If you +allow Emacs to load the @file{.dir-locals.el} file at the root of the +project checkout, it will cause Geiser to automatically add the local +Guix sources to the Guile load path. To actually edit the code, Emacs already has a neat Scheme mode. But in addition to that, you must not miss @@ -384,6 +384,70 @@ copyright-update}. If you want to do it automatically after each buffer save then add @code{(add-hook 'after-save-hook 'copyright-update)} in Emacs. +@subsection Viewing Bugs within Emacs + +Emacs has a nice minor mode called @code{bug-reference}, which, when +combined with @samp{emacs-debbugs} (the Emacs package), can be used to +open links such as @samp{<https://bugs.gnu.org/58697>} or +@samp{<https://issues.guix.gnu.org/58697>} as bug report buffers. From +there you can easily consult the email thread via the Gnus interface, +reply or modify the bug status, all without leaving the comfort of +Emacs! Below is a sample configuration to add to your @file{~/.emacs} +configuration file: + +@lisp +;;; Bug references. +(add-hook 'prog-mode-hook #'bug-reference-prog-mode) +(add-hook 'gnus-mode-hook #'bug-reference-mode) +(add-hook 'erc-mode-hook #'bug-reference-mode) +(add-hook 'bug-reference-mode-hook 'debbugs-browse-mode) +(add-hook 'bug-reference-prog-mode-hook 'debbugs-browse-mode) +(add-hook 'gnus-summary-mode-hook 'bug-reference-mode) +(add-hook 'gnus-article-mode-hook 'bug-reference-mode) + +;;; This extends the default expression (the top-most, first expression +;;; provided to 'or') to also match URLs such as +;;; <https://issues.guix.gnu.org/58697> or <https://bugs.gnu.org/58697>. +;;; It is also extended to detect "Fixes: #NNNNN" git trailers. +(setq bug-reference-bug-regexp + (rx (group (or (seq word-boundary + (or (seq (char "Bb") "ug" + (zero-or-one " ") + (zero-or-one "#")) + (seq (char "Pp") "atch" + (zero-or-one " ") + "#") + (seq (char "Ff") "ixes" + (zero-or-one ":") + (zero-or-one " ") "#") + (seq "RFE" + (zero-or-one " ") "#") + (seq "PR " + (one-or-more (char "a-z+-")) "/")) + (group (one-or-more (char "0-9")) + (zero-or-one + (seq "#" (one-or-more + (char "0-9")))))) + (seq "<https://bugs.gnu.org/" + (group-n 2 (one-or-more (char "0-9"))) + ">"))))) + +;; The following allows Emacs Debbugs user to open the issue directly within +;; Emacs. +(setq debbugs-browse-url-regexp + (rx line-start + "http" (zero-or-one "s") "://" + (or "debbugs" "issues.guix" "bugs") + ".gnu.org" (one-or-more "/") + (group (zero-or-one "cgi/bugreport.cgi?bug=")) + (group-n 3 (one-or-more digit)) + line-end)) +@end lisp + +For more information, refer to @ref{Bug Reference,,, emacs, The GNU +Emacs Manual} and @ref{Minor Mode,,, debbugs-ug, The Debbugs User +Guide}. + @node Packaging Guidelines @section Packaging Guidelines @@ -1345,6 +1409,12 @@ should not be delayed. When a bug is resolved, please close the thread by sending an email to @email{@var{ISSUE_NUMBER}-done@@debbugs.gnu.org}. +@menu +* Configuring Git:: +* Sending a Patch Series:: +* Teams:: +@end menu + @node Configuring Git @subsection Configuring Git @cindex git configuration @@ -1542,10 +1612,10 @@ This section describes how the Guix project tracks its bug reports, patch submissions and topic branches. @menu -* The Issue Tracker:: The official bug and patch tracker. -* Managing Patches and Branches:: How changes to Guix are managed. -* Debbugs User Interfaces:: Ways to interact with Debbugs. -* Debbugs Usertags:: Tag reports with custom labels. +* The Issue Tracker:: The official bug and patch tracker. +* Managing Patches and Branches:: How changes to Guix are managed. +* Debbugs User Interfaces:: Ways to interact with Debbugs. +* Debbugs Usertags:: Tag reports with custom labels. @end menu @node The Issue Tracker @@ -1625,6 +1695,8 @@ information on some builds and substitute availability. @node Debbugs User Interfaces @subsection Debbugs User Interfaces +@subsubsection Web interface + A web interface (actually @emph{two} web interfaces!) are available to browse issues: @@ -1646,6 +1718,88 @@ 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 + +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. + +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 +git:send-email installed. + +@example +$ cd guix +~/guix$ guix shell mumi git git:send-email +@end example + +To search for issues, say all open issues about "zig", run + +@example +~/guix [env]$ mumi search zig is:open + +#60889 Add zig-build-system +opened on 17 Jan 17:37 Z by Ekaitz Zarraga +#61036 [PATCH 0/3] Update zig to 0.10.1 +opened on 24 Jan 09:42 Z by Efraim Flashner +#39136 [PATCH] gnu: services: Add endlessh. +opened on 14 Jan 2020 21:21 by Nicol? Balzarotti +#60424 [PATCH] gnu: Add python-online-judge-tools +opened on 30 Dec 2022 07:03 by gemmaro +#45601 [PATCH 0/6] vlang 0.2 update +opened on 1 Jan 2021 19:23 by Ryan Prior +@end example + +Pick an issue and make it the "current" issue. + +@example +~/guix [env]$ mumi current 61036 + +#61036 [PATCH 0/3] Update zig to 0.10.1 +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 + +@example +~/guix [env]$ git format-patch origin/master +~/guix [env]$ mumi send-email foo.patch bar.patch +@end example + +Note that you do not have to pass in @samp{--to} or @samp{--cc} +arguments to @command{git format-patch}. @command{mumi send-email} will +put them in correctly when sending the patches. + +To open a new issue, run + +@example +~/guix [env]$ mumi new +@end example + +and send patches + +@example +~/guix [env]$ mumi send-email foo.patch bar.patch +@end example + +@command{mumi send-email} is really a wrapper around @command{git +send-email} that automates away all the nitty-gritty of sending patches. +It uses the current issue state to automatically figure out the correct +@samp{To} address to send to, other participants to @samp{Cc}, headers +to add, etc. + +Also note that, unlike @command{git send-email}, @command{mumi +send-email} works perfectly well with single and multiple patches alike. +It automates away the debbugs dance of sending the first patch, waiting +for a response from debbugs and sending the remaining patches. It does +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 + If you use Emacs, you may find it more convenient to interact with issues using @file{debbugs.el}, which you can install with: |