all messages for Guix-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
From: Maxim Cournoyer <maxim.cournoyer@gmail.com>
To: 58813@debbugs.gnu.org
Cc: ludo@gnu.org, liliana.prikler@gmail.com,
	Maxim Cournoyer <maxim.cournoyer@gmail.com>,
	zimon.toutoune@gmail.com
Subject: bug#58813: [PATCH v2 5/5] doc: Simplify contributing section by automating git configuration.
Date: Sun, 23 Apr 2023 22:29:27 -0400	[thread overview]
Message-ID: <8f46ecccc4343c24e9fc0d8b9c8cf5504ef2601d.1682303142.git.maxim.cournoyer@gmail.com> (raw)
In-Reply-To: <5b9af4fa77a89c6a4b169dc464f414b1a4166d60.camel@gmail.com>

Fixes <https://issues.guix.gnu.org/58813>. No longer suggests to
splice the output of etc/teams.scm commands into the 'git send-email'
command line; this is now transparently handled by the Git
configuration, which is also automatic.

* doc/contributing.texi (Configuring Git): Streamline section, now automated
via Automake.
(Sending a Patch Series): Do not specify options configured as default by the
above.  Prefer long option names, for readability.
(Teams): Rewrite the examples to use --header-cmd.
(Commit Access): Refer to the Configuring Git section instead of detailing
manual steps.
---
 doc/contributing.texi | 104 ++++++++++++++----------------------------
 doc/guix.texi         |   2 +-
 2 files changed, 36 insertions(+), 70 deletions(-)

diff --git a/doc/contributing.texi b/doc/contributing.texi
index 73d1cd2648..b13531c5cc 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -1395,28 +1395,8 @@ Configuring Git
 use @command{git config --local}, or edit @file{.git/config} in the
 repository instead of @file{~/.gitconfig}.
 
-We provide some default settings in @file{etc/git/gitconfig} which
-modify how patches are generated, making them easier to read and apply.
-These settings can be applied by manually copying them to
-@file{.git/config} in your checkout, or by telling Git to include the
-whole file:
-
-@example
-git config --local include.path ../etc/git/gitconfig
-@end example
-
-From then on, any changes to @file{etc/git/gitconfig} would
-automatically take effect.
-
-Since the first patch in a series must be sent separately
-(@pxref{Sending a Patch Series}), it can also be helpful to tell
-@command{git format-patch} to handle the e-mail threading instead of
-@command{git send-email}:
-
-@example
-git config --local format.thread shallow
-git config --local sendemail.thread no
-@end example
+Other important Git configuration will automatically be configured when
+building the project (@pxref{Building from Git}).
 
 @node Sending a Patch Series
 @subsection Sending a Patch Series
@@ -1439,10 +1419,12 @@ Sending a Patch Series
 
 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:
+the Guix mailing list to be reviewed and merged.  Assuming you have
+already configured Git according to @xref{Configuring Git}, you can
+simply use:
 
 @example
-$ git send-email -1 -a --base=auto --to=guix-patches@@gnu.org
+$ git send-email --annotate -1
 @end example
 
 @quotation Tip
@@ -1453,31 +1435,26 @@ Sending a Patch Series
 @url{https://git.savannah.gnu.org/cgit/guix.git}.
 
 @example
-git send-email -1 -a --base=auto \
-    --subject-prefix='PATCH core-updates' \
-    --to=guix-patches@@gnu.org
+git send-email --annotate --subject-prefix='PATCH core-updates' -1
 @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{-a} flag (which is short for @option{--annotate}).
-
-The @option{--base=auto} flag automatically adds a note at the bottom
-of the patch of the commit it was based on, making it easier for
-maintainers to rebase and merge your patch.
+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 -a} 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}.
+@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}.
 
 @example
-$ git commit -a
-$ git send-email -1 -a --base=auto -v@var{REVISION} \
-      --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org
+$ git commit --amend
+$ git send-email --annotate -v@var{REVISION} \
+      --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org -1
 @end example
 
 @quotation Note
@@ -1494,14 +1471,14 @@ Sending a Patch Series
 @unnumberedsubsubsec Notifying Teams
 @anchor{Notifying Teams}
 @cindex teams
-The @file{etc/teams.scm} script may be used to notify all those who
-may be interested in your patch of its existence (@pxref{Teams}).
-Use @command{etc/teams.scm list-teams} to display all the teams,
-decide which team(s) your patch relates to, and use
-@command{etc/teams.scm cc} to output various @command{git send-email}
-flags which will notify the appropriate team members, or use
-@command{etc/teams.scm cc-members} to detect the appropriate teams
-automatically.
+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, see @xref{Teams}.
 
 @unnumberedsubsubsec Multiple Patches
 @anchor{Multiple Patches}
@@ -1528,9 +1505,7 @@ Sending a Patch Series
 that we can send the rest of the patches to.
 
 @example
-$ git send-email outgoing/0000-cover-letter.patch -a \
-      --to=guix-patches@@gnu.org \
-      $(etc/teams.scm cc-members ...)
+$ git send-email outgoing/0000-cover-letter.patch --annotate
 $ rm outgoing/0000-cover-letter.patch # we don't want to resend it!
 @end example
 
@@ -1542,9 +1517,7 @@ Sending a Patch Series
 can send the actual patches to the newly-created issue address.
 
 @example
-$ git send-email outgoing/*.patch \
-      --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org \
-      $(etc/teams.scm cc-members ...)
+$ git send-email outgoing/*.patch --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org
 $ rm -rf outgoing # we don't need these anymore
 @end example
 
@@ -1553,14 +1526,13 @@ Sending a Patch Series
 the patchset.
 
 @example
-$ git send-email -@var{NUMBER_COMMITS} \
-      -v@var{REVISION} --base=auto \
+$ git send-email -@var{NUMBER_COMMITS} -v@var{REVISION} \
       --to @var{ISSUE_NUMBER}@@debbugs.gnu.org
 @end example
 
-If need be, you may use @option{--cover-letter -a} to send another cover
-letter, e.g. for explaining what's changed since the last revision, and
-these changes are necessary.
+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
@@ -1587,7 +1559,8 @@ Teams
 CC of a patch series:
 
 @example
-$ git send-email --to @var{ISSUE_NUMBER}@@debbugs.gnu.org $(./etc/teams.scm cc mentors) *.patch
+$ 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
@@ -1596,7 +1569,7 @@ Teams
 
 @example
 $ guix shell -D guix
-[env]$ git send-email --to @var{ISSUE_NUMBER}@@debbugs.gnu.org $(./etc/teams.scm cc-members HEAD~2 HEAD) *.patch
+[env]$ git send-email --to @var{ISSUE_NUMBER}@@debbugs.gnu.org -2
 @end example
 
 @node Tracking Bugs and Patches
@@ -1831,16 +1804,9 @@ Commit Access
 make authenticate
 @end example
 
-You can prevent yourself from accidentally pushing unsigned or signed
-with the wrong key commits to Savannah by using the pre-push Git hook
-located at @file{etc/git/pre-push}:
-
-@example
-cp etc/git/pre-push .git/hooks/pre-push
-@end example
-
-It additionally calls @code{make check-channel-news} to be sure
-@file{news.scm} file is correct.
+To avoid accidentally pushing unsigned or signed with the wrong key
+commits to Savannah, make sure to configure Git according to
+@xref{Configuring Git}.
 
 @subsection Commit Policy
 
diff --git a/doc/guix.texi b/doc/guix.texi
index 9997aeb86e..e5f6c7e831 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -49,7 +49,7 @@
 Copyright @copyright{} 2017, 2021 Christine Lemmer-Webber@*
 Copyright @copyright{} 2017, 2018, 2019, 2020, 2021, 2022 Marius Bakke@*
 Copyright @copyright{} 2017, 2019, 2020, 2022 Hartmut Goebel@*
-Copyright @copyright{} 2017, 2019, 2020, 2021, 2022 Maxim Cournoyer@*
+Copyright @copyright{} 2017, 2019, 2020, 2021, 2022, 2023 Maxim Cournoyer@*
 Copyright @copyright{} 2017–2022 Tobias Geerinckx-Rice@*
 Copyright @copyright{} 2017 George Clemmer@*
 Copyright @copyright{} 2017 Andy Wingo@*
-- 
2.39.2





  parent reply	other threads:[~2023-04-24  2:30 UTC|newest]

Thread overview: 43+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2022-10-27  3:50 bug#58813: can't substitute etc/teams.scm command as doc suggests Maxim Cournoyer
2022-10-27  6:08 ` Liliana Marie Prikler
2022-10-27 12:40   ` Maxim Cournoyer
2022-10-27 16:27     ` Liliana Marie Prikler
2023-02-26  3:55 ` bug#58813: [PATCH] doc: Document how to use Patman for patches submission Maxim Cournoyer
2023-02-26  8:25   ` Liliana Marie Prikler
2023-02-26 17:11     ` Maxim Cournoyer
2023-02-27  0:45       ` Tobias Geerinckx-Rice via Bug reports for GNU Guix
2023-02-27 16:43         ` Maxim Cournoyer
2023-03-03  9:54   ` Ludovic Courtès
2023-03-03 17:26     ` Liliana Marie Prikler
2023-03-06 14:53       ` bug#58813: ‘guix style’ flaws Ludovic Courtès
2023-03-06 17:42         ` Maxim Cournoyer
2023-03-07  1:07     ` bug#58813: [PATCH] doc: Document how to use Patman for patches submission Maxim Cournoyer
2023-03-10  9:01       ` Ludovic Courtès
2023-03-10 14:07         ` Maxim Cournoyer
2023-04-23 16:04           ` bug#58813: [PATCH 0/5] Fix teams.scm by use of a new --header-cmd git send-email option Maxim Cournoyer
2023-04-23 16:04           ` bug#58813: [PATCH 1/5] gnu: git: Apply patch adding the --header-cmd feature Maxim Cournoyer
2023-04-23 17:00             ` Liliana Marie Prikler
2023-04-24  0:46               ` Maxim Cournoyer
2023-04-23 16:04           ` bug#58813: [PATCH 2/5] teams: Add 'cc-members-header-cmd' action Maxim Cournoyer
2023-04-23 16:04           ` bug#58813: [PATCH 3/5] teams: Add a configure-git action Maxim Cournoyer
2023-04-23 17:03             ` Liliana Marie Prikler
2023-04-24  0:59               ` Maxim Cournoyer
2023-04-24  2:29               ` bug#58813: [PATCH v2 0/5] Fix teams.scm by use of a new --header-cmd git send-email option Maxim Cournoyer
2023-04-24  2:29               ` bug#58813: [PATCH v2 1/5] gnu: git: Apply patch adding the --header-cmd feature Maxim Cournoyer
2023-04-24  2:29               ` bug#58813: [PATCH v2 2/5] teams: Add 'cc-members-header-cmd' action Maxim Cournoyer
2023-04-24  2:29               ` bug#58813: [PATCH v2 3/5] Makefile.am: Auto-configure Git on 'make' Maxim Cournoyer
2023-04-24  4:22                 ` Liliana Marie Prikler
2023-04-24 12:37                   ` Maxim Cournoyer
2023-04-28 14:28                 ` Josselin Poiret via Bug reports for GNU Guix
2023-05-01 16:38                   ` bug#58813: can't substitute etc/teams.scm command as doc suggests Maxim Cournoyer
2023-04-24  2:29               ` bug#58813: [PATCH v2 4/5] teams: Add a 'cc-mentors-header-cmd' action Maxim Cournoyer
2023-04-24  2:29               ` Maxim Cournoyer [this message]
2023-04-23 16:04           ` bug#58813: [PATCH " Maxim Cournoyer
2023-04-23 16:04           ` bug#58813: [PATCH 5/5] doc: Simplify contributing section by automating git configuration Maxim Cournoyer
2023-03-07 11:35 ` bug#58813: [PATCH v2] doc: Document how to use Patman for patches submission Simon Tournier
2023-03-07 16:46   ` Maxim Cournoyer
2023-03-07 17:39     ` Simon Tournier
2023-03-08  5:29       ` Liliana Marie Prikler
2023-03-08  8:47         ` Simon Tournier
2023-03-08 16:26           ` Maxim Cournoyer
2023-03-08 17:05             ` Simon Tournier

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=8f46ecccc4343c24e9fc0d8b9c8cf5504ef2601d.1682303142.git.maxim.cournoyer@gmail.com \
    --to=maxim.cournoyer@gmail.com \
    --cc=58813@debbugs.gnu.org \
    --cc=liliana.prikler@gmail.com \
    --cc=ludo@gnu.org \
    --cc=zimon.toutoune@gmail.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/guix.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.