(address . guix-patches@gnu.org)(name . Ale Abdo)(address . abdo@member.fsf.org)
90c8dbae96a3554647770b367945329b15526719.1705122523.git.abdo@member.fsf.org
Change-Id: Ice47f1f4a54bf930bdff94b6a1e47ce84e8fabc7
---
doc/contributing.texi | 278 ++++++++++++++++++++++++------------------
doc/guix.texi | 4 +-
2 files changed, 160 insertions(+), 122 deletions(-)
Toggle diff (442 lines)
diff --git a/doc/contributing.texi b/doc/contributing.texi
index 5707ff5cde..685d936a16 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,87 @@ 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, the surest way is to send
+patches produced by @command{git format-patch} as MIME attachments in plain text
+messages. Using @command{git diff} instead of @command{git format-patch} is not
+advised as it will not include commit metadata. 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. You may also send patches inline, as each patch file
+generated by @command{git format-patch} is a single valid email message, but
+you'd be advised to pay attention if your email client changes anything like
+line breaks or indentation, which could potentially break the patches. 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 +1676,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 +1690,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 +1735,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 +1769,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 <mail@@cbaines.net>
-+ Ricardo Wurmus <rekado@@elephly.net>
++ Ludovic Courtès <ludo@@gnu.org>
+ Mathieu Othacehe <othacehe@@gnu.org>
++ Ricardo Wurmus <rekado@@elephly.net>
+ 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:
+@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
@@ -2215,7 +2253,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 395545bed7..b2b7557742 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -7847,7 +7847,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.
@@ -8576,7 +8576,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}).
base-commit: c4fa3e945eee84f0459760f3ba8232dec49bd1ba
--
2.41.0