summaryrefslogtreecommitdiffstats
path: root/CONTRIBUTING.d
diff options
context:
space:
mode:
Diffstat (limited to 'CONTRIBUTING.d')
-rw-r--r--CONTRIBUTING.d/git41
-rw-r--r--CONTRIBUTING.d/mail10
-rw-r--r--CONTRIBUTING.d/patches48
3 files changed, 92 insertions, 7 deletions
diff --git a/CONTRIBUTING.d/git b/CONTRIBUTING.d/git
new file mode 100644
index 0000000..4f1003a
--- /dev/null
+++ b/CONTRIBUTING.d/git
@@ -0,0 +1,41 @@
+Name
+ Git - instructions for configuring git(1)
+
+Description
+ git-diff(1), gitattributes(5)
+ To produce useful hunk contexts in manual pages, we need to hack
+ git(1)'s idea of a function name, and also to tell git what is a
+ manual page.
+
+ $ git config --global diff.man.xfuncname '^\.S[SHsh] .*$';
+ $ echo '*.[0-9]* diff=man' >>~/.config/git/attributes;
+
+ git-format-patch(1)
+ Send patches to the right addresses.
+
+ $ git config --local format.to 'Alejandro Colomar <alx@kernel.org>';
+ $ git config --local format.cc '<linux-man@vger.kernel.org>';
+
+ git-send-email(1)
+ If mutt(1) or neomutt(1) are configured in the system,
+ git-send-email(1) can be configured to use any of them as a
+ driver. Recent versions of neomutt(1) can enable crypto with -C.
+
+ $ git config --global \
+ sendemail.sendmailcmd 'neomutt -C -H - && true';
+ or
+ $ git config --global sendemail.sendmailcmd 'mutt -H - && true';
+
+See also
+ git-config(1)
+ git-diff(1)
+ git-format-patch(1)
+ git-send-email(1)
+ gitattributes(5)
+ mutt(1)
+ neomutt(1)
+
+ CONTRIBUTING.d/*
+
+ <https://git-send-email.io/>
+ <https://neomutt.org/feature/cli-crypto>
diff --git a/CONTRIBUTING.d/mail b/CONTRIBUTING.d/mail
index 48e5b9a..a749e34 100644
--- a/CONTRIBUTING.d/mail
+++ b/CONTRIBUTING.d/mail
@@ -51,13 +51,11 @@ Description
using a PGP key. See also:
<https://www.gnupg.org/faq/gnupg-faq.html#use_pgpmime>
- There are many ways you can sign your patches, and it depends on
- your preferred tools. You can use neomutt(1) (>= 20240201) as a
- driver for git-send-email(1). In <~/.gitconfig>, add the
- following section:
+ If you use mutt(1), we recommend the following configuration for
+ PGP:
- [sendemail]
- sendmailcmd = neomutt -C -H - && true
+ set crypt_autosign = yes
+ set crypt_protected_headers_write = yes
See also
CONTRIBUTING
diff --git a/CONTRIBUTING.d/patches b/CONTRIBUTING.d/patches
index 96550ce..35f4923 100644
--- a/CONTRIBUTING.d/patches
+++ b/CONTRIBUTING.d/patches
@@ -5,8 +5,11 @@ Description
If you know how to fix a problem in a manual page (if not, see
<CONTRIBUTING.d/bugs>), then send a patch in an email.
+ - Configure git(1) for this project. See <CONTRIBUTING.d/git>.
+
- Follow the instructions for sending mail to the mailing list
- from <CONTRIBUTING.d/mail>.
+ from <CONTRIBUTING.d/mail>. See also "Send the patches"
+ below.
- The subject of the email should contain "[patch]" in the
subject line.
@@ -87,8 +90,51 @@ Description
- Make patches against the latest version of the manual page.
Use git(1) for getting the latest version.
+ Prepare the patches for email submission
+ We recommend using git-format-patch(1) to prepare the patches.
+ Please use --range-diff to document the differences between
+ revisions of the patch set, even in the first revision.
+
+ To prepare a branch to be sent as a patch set (v1):
+
+ $ git format-patch -o ./patches master..HEAD \
+ --range-diff=master -v1 --cover-letter;
+
+ The range diff will be included in the cover letter (or in a
+ single patch, if there is only one):
+
+ $ tail -n7 ./patches/v1-0000-cover-letter.patch;
+ Range-diff against v0:
+ -: --------- > 1: 7ec952012 foo.3: tfix
+ -: --------- > 2: d80376b08 bar.3: ffix
+ -: --------- > 3: 892a12470 foo.3: wfix
+ --
+ 2.43.0
+
+ To send a v2 after some feedback:
+
+ $ git format-patch -o ./patches master..HEAD \
+ --range-diff=old_master..old_HEAD -v2 --cover-letter;
+
+ The values for 'old_master' and 'old_HEAD' can be consulted in
+ the previous cover letter. In this example, it would be
+ '--range-diff=7ec952012^..892a12470'.
+
+ Send the patches
+ We recommend using git-send-email(1) to send the patches to the
+ mailing list. For instructions on how to configure and use it,
+ see <https://git-send-email.io/>. See also <CONTRIBUTING.d/git>.
+
+ Sign the patches with PGP
+ See <CONTRIBUTING.d/mail> for more details on signing your mail
+ to the list. See also <CONTRIBUTING.d/git> for instructions for
+ configuring git-send-email(1) to use neomutt(1) as a driver.
+
See also
CONTRIBUTING
CONTRIBUTING.d/*
<https://www.kernel.org/doc/Documentation/process/submitting-patches.rst>
+ <https://inbox.sourceware.org/gcc/ZiV5unTogyI7rPJA@debian/>
+ <https://git-send-email.io/>
+ <https://neomutt.org/feature/cli-crypto>