From patchwork Wed Feb 21 22:05:11 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Ale Abdo X-Patchwork-Id: 60880 Return-Path: X-Original-To: patchwork@mira.cbaines.net Delivered-To: patchwork@mira.cbaines.net Received: by mira.cbaines.net (Postfix, from userid 113) id E164027BBEA; Wed, 21 Feb 2024 22:10:08 +0000 (GMT) X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on mira.cbaines.net X-Spam-Level: X-Spam-Status: No, score=-3.9 required=5.0 tests=BAYES_00,MAILING_LIST_MULTI, RCVD_IN_MSPIKE_H2,SPF_HELO_PASS,URIBL_BLOCKED autolearn=ham autolearn_force=no version=3.4.6 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mira.cbaines.net (Postfix) with ESMTPS id 0CCCC27BBE2 for ; Wed, 21 Feb 2024 22:10:04 +0000 (GMT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rcumc-0002VK-0U; Wed, 21 Feb 2024 17:09:42 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1rcuma-0002Ud-5C for guix-patches@gnu.org; Wed, 21 Feb 2024 17:09:40 -0500 Received: from debbugs.gnu.org ([2001:470:142:5::43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1rcumZ-0003bP-TG for guix-patches@gnu.org; Wed, 21 Feb 2024 17:09:39 -0500 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1rcumw-00033K-Bt for guix-patches@gnu.org; Wed, 21 Feb 2024 17:10:02 -0500 X-Loop: help-debbugs@gnu.org Subject: [bug#68414] [PATCH v1] doc: Improve documentation for submitting patches References: <90c8dbae96a3554647770b367945329b15526719.1705122523.git.abdo@member.fsf.org> In-Reply-To: <90c8dbae96a3554647770b367945329b15526719.1705122523.git.abdo@member.fsf.org> Resent-From: Ale Abdo Original-Sender: "Debbugs-submit" Resent-CC: guix-patches@gnu.org Resent-Date: Wed, 21 Feb 2024 22:10:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 68414 X-GNU-PR-Package: guix-patches X-GNU-PR-Keywords: patch To: 68414@debbugs.gnu.org Cc: Ale Abdo Received: via spool by 68414-submit@debbugs.gnu.org id=B68414.170855336311602 (code B ref 68414); Wed, 21 Feb 2024 22:10:02 +0000 Received: (at 68414) by debbugs.gnu.org; 21 Feb 2024 22:09:23 +0000 Received: from localhost ([127.0.0.1]:46666 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rcumG-00030o-Vg for submit@debbugs.gnu.org; Wed, 21 Feb 2024 17:09:23 -0500 Received: from msg-4.mailo.com ([213.182.54.15]:37532 helo=mailo.com) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rcumD-00030B-Ny for 68414@debbugs.gnu.org; Wed, 21 Feb 2024 17:09:19 -0500 Received: by b221-2.in.mailobj.net [192.168.90.22] with ESMTP via ip-20.mailobj.net [213.182.54.20] Wed, 21 Feb 2024 23:08:48 +0100 (CET) X-EA-Auth: rLre+XkParPqsjmHUcH4pwcCtlihnC54PLzuHofSmoSdlMQIL6GL6wvRPvKFkKmSL0JWZTc082R0owU+eskUbzH/p3NHDno3 From: Ale Abdo Date: Wed, 21 Feb 2024 23:05:11 +0100 Message-ID: <299ae514ddb2f9f365d2b4a9600cf92887f9b7b3.1708553111.git.abdo@member.fsf.org> X-Mailer: git-send-email 2.41.0 MIME-Version: 1.0 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: guix-patches@gnu.org List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-patches-bounces+patchwork=mira.cbaines.net@gnu.org Sender: guix-patches-bounces+patchwork=mira.cbaines.net@gnu.org X-getmail-retrieved-from-mailbox: Patches Change-Id: Ice47f1f4a54bf930bdff94b6a1e47ce84e8fabc7 --- doc/contributing.texi | 273 +++++++++++++++++++++++------------------- doc/guix.texi | 4 +- 2 files changed, 155 insertions(+), 122 deletions(-) base-commit: 8073a26022111c38808c1a803d59229288db0839 diff --git a/doc/contributing.texi b/doc/contributing.texi index a7d91724fb..6e08d381d4 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -1376,23 +1376,25 @@ Formatting Code @node Submitting Patches @section Submitting Patches +@cindex patch submission -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 +Guix is developed using the Git distributed version control system. Special +access to the official repository is not necessary in order to contribute. 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 (@pxref{Submitting patches to a project,,, git, Git User Manual}). -Contributors are encouraged to take a moment to set some Git repository -options (@pxref{Configuring Git}) first, which can improve the -readability of patches. 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, which allows us to -keep track of submissions (@pxref{Tracking Bugs and Changes}). -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{ISSUE_NUMBER}@@debbugs.gnu.org}, where @var{ISSUE_NUMBER} -is the tracking number (@pxref{Sending a Patch Series}). + +Contributors are encouraged to take a moment to set some Git repository options +(@pxref{Configuring Git}) first, which can improve the readability of patches. +Seasoned Guix developers may also want to look at the section on commit access +(@pxref{Commit Access}). + +The @email{guix-patches@@gnu.org} mailing list is backed by a Debbugs instance, +which allows us to keep track of submissions (@pxref{Tracking Bugs and +Changes}). 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{ISSUE_NUMBER}@@debbugs.gnu.org}, where @var{ISSUE_NUMBER} 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 @@ -1408,6 +1410,10 @@ Submitting Patches what questions a reviewer will ask, and answer those questions in advance. + +@node Patch quality +@subsection Patch quality + Before submitting a patch that adds or modifies a package definition, please run through this check list: @@ -1553,36 +1559,11 @@ Submitting Patches @end enumerate -When posting a patch to the mailing list, use @samp{[PATCH] @dots{}} as -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. - -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{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 -@cindex @code{git format-patch} -@cindex @code{git send-email} +@cindex @code{git config} If you have not done so already, you may wish to set a name and email that will be associated with your commits (@pxref{telling git your name, @@ -1602,35 +1583,82 @@ Configuring Git @file{commit-msg} hook of your own you would like to use with Guix, you can place it under the @file{.git/hooks/commit-msg.d/} directory. + +@node Posting a patch +@subsection Posting a patch +@cindex @code{git format-patch} + +When posting a patch to the mailing list, use @samp{[PATCH] @dots{}} as a +subject. In case 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 the @command{git send-email} command or your email client to post a +patch. + +Using @command{git send-email} has several advantages, such as automatically +CC'ing the appropriate teams, avoiding formatting issues, being +@url{https://git-scm.com/docs/git-send-email#_examples, easy to configure}, and +convenient to use. Usage is often as simple as @command{git send-email -1} to +post a single commit. @xref{Sending a Patch Series} for further details. + +Should you still prefer to use your email client, make sure to send patches +produced by @command{git format-patch} as MIME attachments in plain text +messages. For a series with multiple patches, it is possible to send them as +multiple attachments in a single message. Beware that multi-attachment messages +will not display correctly on the @url{https://issues.guix.gnu.org, Guix issue +tracker}, though they will work fine with Debbugs. Finally, should you want to +notify a team to review your patch, you'll have to figure out the appropriate +members and CC them manually (@pxref{Teams}). + +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{ISSUE_NUMBER}-done@@debbugs.gnu.org}. + + @node Sending a Patch Series @subsection Sending a Patch Series @cindex patch series @cindex @code{git send-email} @cindex @code{git format-patch} -@unnumberedsubsubsec Single Patches -@anchor{Single Patches} -The @command{git send-email} command is the best way to send both single -patches and patch series (@pxref{Multiple Patches}) to the Guix mailing -list. Sending patches as email attachments may make them difficult to -review in some mail clients, and @command{git diff} does not store commit -metadata. +The @command{git send-email} command is the best way to send both single patches +and patch series to the Guix mailing list. @quotation Note -The @command{git send-email} command is provided by the @code{send-email} -output of the @code{git} package, i.e. @code{git:send-email}. +The @command{git send-email} command is provided by the @code{send-email} output +of the @code{git} package. You may install it with @code{guix install +git:send-email}, and see @url{https://git-scm.com/docs/git-send-email#_examples, +its documentation} for an example configuration. @end quotation -The following command will create a patch email from the latest commit, -open it in your @var{EDITOR} or @var{VISUAL} for editing, and send it to -the Guix mailing list to be reviewed and merged. Assuming you have -already configured Git according to @xref{Configuring Git}, you can -simply use: +@unnumberedsubsubsec Single Commit Patches +@anchor{Single Commit Patches} + +Once you have configured Git (@pxref{Configuring Git}) and @command{git +send-email}, you can use the following command to create a patch email from the +latest commit and send it to the Guix mailing list to be reviewed and merged. + +@example +$ git send-email -1 +@end example + +If you wish to review the patch before sending, adding the @option{--annotate} +option will open the patch in your @var{EDITOR} or @var{VISUAL} for editing +before it gets sent. @example $ git send-email --annotate -1 @end example +The patch email contains a three-dash separator line after the commit +message. You may ``annotate'' the patch with explanatory text by adding +it under this line. + @quotation Tip To add a prefix to the subject of your patch, you may use the @option{--subject-prefix} option. The Guix project uses this to @@ -1643,17 +1671,12 @@ Sending a Patch Series @end example @end quotation -The patch email contains a three-dash separator line after the commit -message. You may ``annotate'' the patch with explanatory text by adding -it under this line. If you do not wish to annotate the email, you may -drop the @option{--annotate} option. - -If you need to send a revised patch, don't resend it like this or send -a ``fix'' patch to be applied on top of the last one; instead, use -@command{git commit --amend} or @url{https://git-rebase.io, -@command{git rebase}} to modify the commit, and use the -@email{@var{ISSUE_NUMBER}@@debbugs.gnu.org} address and the @option{-v} -flag with @command{git send-email}. +If you need to send a revised patch, don't resend it like the above, nor send a +``fix'' patch to be applied on top of the previous one; instead, use +@command{git commit --amend} or @url{https://git-rebase.io, @command{git +rebase}} to modify the commit, then call @command{git send-email} with the +@email{@var{ISSUE_NUMBER}@@debbugs.gnu.org} address and the @option{-v} flag to +give the revision a number. @example $ git commit --amend @@ -1662,47 +1685,44 @@ Sending a Patch Series @end example @quotation Note -Due to an apparent bug in @command{git send-email}, -@option{-v @var{REVISION}} (with the space) will not work; you -@emph{must} use @option{-v@var{REVISION}}. +@command{git send-email} syntax for patch versions is @option{-v@var{REVISION}}. +Using @option{-v @var{REVISION}} (with a space) will not work. @end quotation -You can find out @var{ISSUE_NUMBER} either by searching on the mumi -interface at @url{https://issues.guix.gnu.org} for the name of your patch or -reading the acknowledgement email sent automatically by Debbugs in -reply to incoming bugs and patches, which contains the bug number. +You can find out @var{ISSUE_NUMBER} either by searching on the Guix issue +tracker at @url{https://issues.guix.gnu.org} for the name of your patch or by +reading the acknowledgement email sent automatically by Debbugs in reply to +incoming bugs and patches, which contains the bug number. @unnumberedsubsubsec Notifying Teams @anchor{Notifying Teams} @cindex teams -If your git checkout has been correctly configured (@pxref{Configuring -Git}), the @command{git send-email} command will automatically notify -the appropriate team members, based on the scope of your changes. This -relies on the @file{etc/teams.scm} script, which can also be invoked -manually if you do not use the preferred @command{git send-email} -command to submit patches. To list the available actions of the script, -you can invoke it via the @command{etc/teams.scm help} command. For -more information regarding teams, @pxref{Teams}. +If your git checkout has been correctly configured (@pxref{Configuring Git}), +the @command{git send-email} command will automatically notify the appropriate +team members, based on the scope of your changes. This relies on the +@file{etc/teams.scm} script, which can also be invoked manually if you do not +use the preferred @command{git send-email} command to submit patches. For more +information regarding teams and @file{etc/teams.scm}, @pxref{Teams}. @quotation Note -On foreign distros, you might have to use @command{./pre-inst-env git -send-email} for @file{etc/teams.scm} to work. +When using Guix as a package manager on foreign distros, you might have to use +@command{./pre-inst-env git send-email} for @file{etc/teams.scm} to work. @end quotation -@unnumberedsubsubsec Multiple Patches -@anchor{Multiple Patches} +@unnumberedsubsubsec Multiple Commit Patches +@anchor{Multiple Commit Patches} @cindex cover letter -While @command{git send-email} alone will suffice for a single -patch, an unfortunate flaw in Debbugs means you need to be more -careful when sending multiple patches: if you send them all to the -@email{guix-patches@@gnu.org} address, a new issue will be created -for each patch! - -When sending a series of patches, it's best to send a Git ``cover -letter'' first, to give reviewers an overview of the patch series. -We can create a directory called @file{outgoing} containing both -our patch series and a cover letter called @file{0000-cover-letter.patch} -with @command{git format-patch}. +While @command{git send-email} alone will suffice for a single patch, you need +to be more careful when sending multiple patches: if you send them all to the +@email{guix-patches@@gnu.org} address, a new issue will be created for each +patch! + +When sending a series of patches, it's best to send a Git ``cover letter'' +first, to give reviewers an overview of the patch series and create a single +issue to send them to. We can create a directory called @file{outgoing} +containing both a cover letter called @file{0000-cover-letter.patch} and a patch +series for the @var{NUMBER_COMMITS} last commits with @command{git +format-patch}. @example $ git format-patch -@var{NUMBER_COMMITS} -o outgoing \ @@ -1710,29 +1730,32 @@ Sending a Patch Series @end example 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. +@email{guix-patches@@gnu.org} address, thus creating an issue to which we can +send the patches. @example $ git send-email outgoing/0000-cover-letter.patch --annotate $ rm outgoing/0000-cover-letter.patch # we don't want to resend it! @end example -Ensure you edit the email to add an appropriate subject line and -blurb before sending it. Note the automatically generated shortlog -and diffstat below the blurb. +The command will open the cover letter for editing so you can add an appropriate +subject line and blurb before sending it. Note the automatically generated +shortlog and diffstat below the blurb. -Once the Debbugs mailer has replied to your cover letter email, you -can send the actual patches to the newly-created issue address. +Once the Debbugs mailer has replied to your cover letter email, with the +@var{ISSUE_NUMBER} in the reply, you can send the actual patches to the +newly-created issue address. @example $ git send-email outgoing/*.patch --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org $ rm -rf outgoing # we don't need these anymore @end example +And you're done! + Thankfully, this @command{git format-patch} dance is not necessary to send an amended patch series, since an issue already exists for -the patchset. +the patchset. Calling @command{git send-email} directly will do. @example $ git send-email -@var{NUMBER_COMMITS} -v@var{REVISION} \ @@ -1741,45 +1764,55 @@ Sending a Patch Series 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. +revision, and why 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: +There are several teams mentoring different parts of the Guix source code. The +script @file{etc/teams.scm} provides information about them. + +To list all teams with their members and the files under their scope, you can +run from a Guix checkout: @example $ ./etc/teams.scm list-teams +@end example + +To list the scope and members of a single team, for example the team `mentors' +(which has no file scope): + +@example +$ ./etc/teams.scm show mentors id: mentors name: Mentors description: A group of mentors who chaperone contributions by newcomers. members: + Christopher Baines -+ Ricardo Wurmus ++ Ludovic Courtès + Mathieu Othacehe ++ Ricardo Wurmus + jgart -+ Ludovic Courtès -@dots{} @end example -You can run the following command to have the @code{Mentors} team put in -CC of a patch series: +@file{etc/teams.scm} can also infer the appropriate team or teams to notify +about a patch series, and output option strings to be used with @command{git +send-email} as well as @command{git format-patch}. If Git was properly +configured (@pxref{Configuring Git}), this is handled automatically by +@command{git send-email} as explained in @ref{Notifying Teams}. + +As an example, you can run the following command to have the @code{Mentors} team +put in CC of a seires of patch files to be sent with @command{git send-email}: @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: +To list the available actions of the script, you can invoke it via the +@file{etc/teams.scm help} command. -@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 @@ -2221,7 +2254,7 @@ Commit Access To avoid accidentally pushing unsigned or signed with the wrong key commits to Savannah, make sure to configure Git according to -@xref{Configuring Git}. +@ref{Configuring Git}. @subsection Commit Policy diff --git a/doc/guix.texi b/doc/guix.texi index 34aa3545da..bb5a145f5c 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -7857,7 +7857,7 @@ Defining Packages @code{guix download} (@pxref{Invoking guix download}) and @code{guix hash} (@pxref{Invoking guix hash}). -@cindex patches +@cindex patches, for packages When needed, the @code{origin} form can also have a @code{patches} field listing patches to be applied, and a @code{snippet} field giving a Scheme expression to modify the source code. @@ -8586,7 +8586,7 @@ Defining Package Variants and in your own package collection (@pxref{Creating a Channel}), among others! -@cindex inherit, for package definitions +@cindex inherit, for packages As discussed earlier, packages are first-class objects in the Scheme language. The @code{(guix packages)} module provides the @code{package} construct to define new package objects (@pxref{package Reference}).