Hi,

this small patch series wires up b4 in Git and recommends the use
thereof via "MyFirstContribution", as discussed in [1].

Changes in v3:
  - I wasn't really able to judge consensus one way or the other
    regarding the deep vs shallow nesting of cover letters, so I still
    have the change to shallow nesting of cover letters part of this
    series. If we continue to be split on this one (or if we favor the
    current status quo) I'm happy to drop the first patch and adapt the
    last patch to use deep nesting of cover letters instead.
  - Hopefully fix some confusion by saying "shallow/deep threading of
    cover letters".
  - Fix some more instances where we recommend deep threading of cover
    letters.
  - Link to v2: https://patch.msgid.link/20260603-pks-b4-v2-0-a8aea0aa2c23@pks.im

Changes in v2:
  - Reorder commits so that the b4 docs are added first.
  - Add a section that highlights how to configure b4, and that points
    out that the per-project defaults can be overridden via Git
    configuration.
  - Add a patch to MyFirstContribution that recommends shallow
    threading. I mostly intend this to be a discussion starter so that
    the `.b4-config` file matches our preferred threading style.
  - Fix a typo.
  - Link to v1: https://patch.msgid.link/20260602-pks-b4-v1-0-a7ae5a49e9cf@pks.im

Thanks!

Patrick

[1]: <xmqqik81xpqx.fsf@gitster.g>

---
Patrick Steinhardt (3):
      MyFirstContribution: recommend shallow threading of cover letters
      MyFirstContribution: recommend the use of b4
      b4: introduce configuration for the Git project

 .b4-config                             |   6 ++
 .b4-cover-template                     |  11 ++++
 Documentation/MyFirstContribution.adoc | 100 ++++++++++++++++++++++++++++++---
 Documentation/SubmittingPatches        |   6 +-
 4 files changed, 114 insertions(+), 9 deletions(-)

Range-diff versus v2:

1:  f7784c8f7f ! 1:  4b0c4f9aca Documentation/MyFirstContribution: recommend shallow threading
    @@ Metadata
     Author: Patrick Steinhardt [off-list ref]
     
      ## Commit message ##
    -    Documentation/MyFirstContribution: recommend shallow threading
    +    MyFirstContribution: recommend shallow threading of cover letters
     
    -    The "MyFirstContribution" document recommends the use of deep threading:
    -    every cover letter of subsequent iterations shall be linked to the cover
    -    letter of the preceding version. The result of this is that eventually,
    -    threads with many versions are getting nested so deep that it becomes
    -    hard to follow.
    +    The "MyFirstContribution" document recommends the use of deep threading
    +    of cover letters: every cover letter of subsequent iterations shall be
    +    linked to the cover letter of the preceding version. The result of this
    +    is that eventually, threads with many versions are getting nested so
    +    deep that it becomes hard to follow.
     
    -    Adapt the recommendation to instead propose shallow threading: instead
    -    of linking the cover letter to the previous cover letter, the user is
    -    supposed to always link it to the first cover letter. This still makes
    -    it easy to follow the iterations, but has the benefit of nesting to a
    -    much shallower level.
    +    Adapt the recommendation to instead propose shallow threading of cover
    +    letters: instead of linking the cover letter to the previous cover
    +    letter, the user is supposed to always link it to the first cover
    +    letter. This still makes it easy to follow the iterations, but has the
    +    benefit of nesting to a much shallower level.
     
         Signed-off-by: Patrick Steinhardt [off-list ref]
     
      ## Documentation/MyFirstContribution.adoc ##
    +@@ Documentation/MyFirstContribution.adoc: We can note a few things:
    +   v3", etc. in place of "PATCH". For example, "[PATCH v2 1/3]" would be the first of
    +   three patches in the second iteration. Each iteration is sent with a new cover
    +   letter (like "[PATCH v2 0/3]" above), itself a reply to the cover letter of the
    +-  previous iteration (more on that below).
    ++  first iteration (more on that below).
    + 
    + NOTE: A single-patch topic is sent with "[PATCH]", "[PATCH v2]", etc. without
    + _i_/_n_ numbering (in the above thread overview, no single-patch topic appears,
    +@@ Documentation/MyFirstContribution.adoc: between your last version and now, if it's something significant. You do not
    + need the exact same body in your second cover letter; focus on explaining to
    + reviewers the changes you've made that may not be as visible.
    + 
    +-You will also need to go and find the Message-ID of your previous cover letter.
    ++You will also need to go and find the Message-ID of your first cover letter.
    + You can either note it when you send the first series, from the output of `git
    + send-email`, or you can look it up on the
    + https://lore.kernel.org/git[mailing list]. Find your cover letter in the
     @@ Documentation/MyFirstContribution.adoc: Message-ID: [off-list ref]
      
      Your Message-ID is `[off-list ref]`. This example will be used
2:  e8f3caf73a ! 2:  625de75a33 Documentation/MyFirstContribution: recommend the use of b4
    @@ Metadata
     Author: Patrick Steinhardt [off-list ref]
     
      ## Commit message ##
    -    Documentation/MyFirstContribution: recommend the use of b4
    +    MyFirstContribution: recommend the use of b4
     
         The b4 tool originates from the Linux kernel community and is intended
         to help mailing-list based workflows. It automates a lot of the annoying
3:  35591c55c8 = 3:  a95973cfb6 b4: introduce configuration for the Git project

---
base-commit: 9ac3f193c05c2237e2b14ebaa1149e9fc8a1abe0
change-id: 20260602-pks-b4-31cc20d7f84b