* [PATCH b4 01/21] docs: maintainer: ty: fix incorrect config name for templates
2026-02-03 13:30 [PATCH b4 00/21] docs: various fixes + migration from definition lists to glossaries for config settings Quentin Schulz
@ 2026-02-03 13:31 ` Quentin Schulz
2026-02-03 13:31 ` [PATCH b4 02/21] docs: prep: add info on when range-diff-opts was added Quentin Schulz
` (21 subsequent siblings)
22 siblings, 0 replies; 25+ messages in thread
From: Quentin Schulz @ 2026-02-03 13:31 UTC (permalink / raw)
To: Kernel.org Tools; +Cc: Konstantin Ryabitsev, Quentin Schulz
From: Quentin Schulz <quentin.schulz@cherry.de>
The config options are named with dashes and not underscores, so let's
fix that oversight.
Fixes: 2ce1e619ddb4 ("docs: complete most of the maintainer docs")
Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
docs/maintainer/ty.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/maintainer/ty.rst b/docs/maintainer/ty.rst
index fd69c7e..b445bb6 100644
--- a/docs/maintainer/ty.rst
+++ b/docs/maintainer/ty.rst
@@ -74,7 +74,7 @@ Editing the templates
You can edit the default templates that are provided with b4 to
customize the thank-you message. Once you have your own versions, you
can specify the path to the template to use via the
-``b4.thanks_am_template`` and ``b4.thanks_pr_template`` configuration
+``b4.thanks-am-template`` and ``b4.thanks-pr-template`` configuration
parameters. See :ref:`ty_settings` for details.
Optional flags
--
2.52.0
^ permalink raw reply related [flat|nested] 25+ messages in thread* [PATCH b4 02/21] docs: prep: add info on when range-diff-opts was added
2026-02-03 13:30 [PATCH b4 00/21] docs: various fixes + migration from definition lists to glossaries for config settings Quentin Schulz
2026-02-03 13:31 ` [PATCH b4 01/21] docs: maintainer: ty: fix incorrect config name for templates Quentin Schulz
@ 2026-02-03 13:31 ` Quentin Schulz
2026-02-03 13:31 ` [PATCH b4 03/21] docs: diff: " Quentin Schulz
` (20 subsequent siblings)
22 siblings, 0 replies; 25+ messages in thread
From: Quentin Schulz @ 2026-02-03 13:31 UTC (permalink / raw)
To: Kernel.org Tools; +Cc: Konstantin Ryabitsev, Quentin Schulz
From: Quentin Schulz <quentin.schulz@cherry.de>
This specifies since which release the range-diff-opts option is
available (which is not yet, hence v0.15).
Fixes: eb4a66b12bc4 ("prep: support passing arguments to git range-diff")
Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
docs/contributor/prep.rst | 2 ++
1 file changed, 2 insertions(+)
diff --git a/docs/contributor/prep.rst b/docs/contributor/prep.rst
index 18c710d..4c26602 100644
--- a/docs/contributor/prep.rst
+++ b/docs/contributor/prep.rst
@@ -500,3 +500,5 @@ modifying defaults for some of these flags.
``--compare-to``. For example::
b4 prep --compare-to v1 --range-diff-opts "--creation-factor=80 --no-dual-color"
+
+ .. versionadded:: v0.15
--
2.52.0
^ permalink raw reply related [flat|nested] 25+ messages in thread* [PATCH b4 03/21] docs: diff: add info on when range-diff-opts was added
2026-02-03 13:30 [PATCH b4 00/21] docs: various fixes + migration from definition lists to glossaries for config settings Quentin Schulz
2026-02-03 13:31 ` [PATCH b4 01/21] docs: maintainer: ty: fix incorrect config name for templates Quentin Schulz
2026-02-03 13:31 ` [PATCH b4 02/21] docs: prep: add info on when range-diff-opts was added Quentin Schulz
@ 2026-02-03 13:31 ` Quentin Schulz
2026-02-03 13:31 ` [PATCH b4 04/21] docs: contributor: send: fix sendmail typo Quentin Schulz
` (19 subsequent siblings)
22 siblings, 0 replies; 25+ messages in thread
From: Quentin Schulz @ 2026-02-03 13:31 UTC (permalink / raw)
To: Kernel.org Tools; +Cc: Konstantin Ryabitsev, Quentin Schulz
From: Quentin Schulz <quentin.schulz@cherry.de>
This specifies since which release the range-diff-opts option is
available (which is not yet, hence v0.15).
Fixes: 3c7fbc395fc6 ("diff: support passing arguments to git range-diff")
Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
docs/maintainer/diff.rst | 2 ++
1 file changed, 2 insertions(+)
diff --git a/docs/maintainer/diff.rst b/docs/maintainer/diff.rst
index 7911cdc..4e3fac0 100644
--- a/docs/maintainer/diff.rst
+++ b/docs/maintainer/diff.rst
@@ -47,6 +47,8 @@ Optional flags
b4 diff --range-diff-opts "--creation-factor=80 --no-dual-color" <url>
+ .. versionadded:: v0.15
+
``-o OUTDIFF, --output-diff OUTDIFF``
**(DEPRECATED)** Sends ``range-diff`` output into a file. You should use
``-n`` instead and redirect output from the actual ``git range-diff``
--
2.52.0
^ permalink raw reply related [flat|nested] 25+ messages in thread* [PATCH b4 04/21] docs: contributor: send: fix sendmail typo
2026-02-03 13:30 [PATCH b4 00/21] docs: various fixes + migration from definition lists to glossaries for config settings Quentin Schulz
` (2 preceding siblings ...)
2026-02-03 13:31 ` [PATCH b4 03/21] docs: diff: " Quentin Schulz
@ 2026-02-03 13:31 ` Quentin Schulz
2026-02-03 13:31 ` [PATCH b4 05/21] docs: config: separate b4.thanks-pr-template and b4.thanks-am-template Quentin Schulz
` (18 subsequent siblings)
22 siblings, 0 replies; 25+ messages in thread
From: Quentin Schulz @ 2026-02-03 13:31 UTC (permalink / raw)
To: Kernel.org Tools; +Cc: Konstantin Ryabitsev, Quentin Schulz
From: Quentin Schulz <quentin.schulz@cherry.de>
There's a sendmail binary, but the git configuration settings are
sendemail and not sendmail (and you can use sendmail in sendemail to
make things more confusing), so let's fix that oversight.
Fixes: e8045d135316 ("ez: Add --use-web-endpoint arg to force web endpoint")
Fixes: 890fdc05400e ("docs: document pre-flight checks")
Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
docs/contributor/send.rst | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/docs/contributor/send.rst b/docs/contributor/send.rst
index 54ed474..0de2aa5 100644
--- a/docs/contributor/send.rst
+++ b/docs/contributor/send.rst
@@ -141,9 +141,9 @@ with the following setting::
Using your own SMTP server
--------------------------
-If there is a ``sendmail`` section in your git configuration, B4 tries
+If there is a ``sendemail`` section in your git configuration, B4 tries
to use that by default instead of going via the web endpoint. At this
-time, b4 only recognizes a subset of ``sendmail`` options supported by
+time, b4 only recognizes a subset of ``sendemail`` options supported by
git itself. The vast majority of servers should only need the following
settings::
@@ -156,7 +156,7 @@ settings::
You can also set up ``msmtp`` or a similar tool and specify the path to
the ``sendmail``-compliant binary as the value for ``smtpServer``. To
-force B4 to use the web endpoint even when a ``sendmail`` option is
+force B4 to use the web endpoint even when a ``sendemail`` option is
present, use the ``--use-web-endpoint`` switch.
Sending your patches
--
2.52.0
^ permalink raw reply related [flat|nested] 25+ messages in thread* [PATCH b4 05/21] docs: config: separate b4.thanks-pr-template and b4.thanks-am-template
2026-02-03 13:30 [PATCH b4 00/21] docs: various fixes + migration from definition lists to glossaries for config settings Quentin Schulz
` (3 preceding siblings ...)
2026-02-03 13:31 ` [PATCH b4 04/21] docs: contributor: send: fix sendmail typo Quentin Schulz
@ 2026-02-03 13:31 ` Quentin Schulz
2026-02-03 13:31 ` [PATCH b4 06/21] docs: use rST version admonitions for command options Quentin Schulz
` (17 subsequent siblings)
22 siblings, 0 replies; 25+ messages in thread
From: Quentin Schulz @ 2026-02-03 13:31 UTC (permalink / raw)
To: Kernel.org Tools; +Cc: Konstantin Ryabitsev, Quentin Schulz
From: Quentin Schulz <quentin.schulz@cherry.de>
While their definition are identical (so far), they are for different
things and this way of presenting the configs may confuse the user into
thinking those are aliases for the same thing. They aren't, so split
them.
Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
docs/config.rst | 8 +++++++-
1 file changed, 7 insertions(+), 1 deletion(-)
diff --git a/docs/config.rst b/docs/config.rst
index a1145af..a9006a5 100644
--- a/docs/config.rst
+++ b/docs/config.rst
@@ -236,7 +236,13 @@ Attestation settings
``ty`` settings
~~~~~~~~~~~~~~~
-``b4.thanks-pr-template``, ``b4.thanks-am-template``
+``b4.thanks-pr-template``
+ Full paths to the templates to use when generating thank-you messages
+ for contributors. See example templates provided with the project.
+
+ Default: ``None``
+
+``b4.thanks-am-template``
Full paths to the templates to use when generating thank-you messages
for contributors. See example templates provided with the project.
--
2.52.0
^ permalink raw reply related [flat|nested] 25+ messages in thread* [PATCH b4 06/21] docs: use rST version admonitions for command options
2026-02-03 13:30 [PATCH b4 00/21] docs: various fixes + migration from definition lists to glossaries for config settings Quentin Schulz
` (4 preceding siblings ...)
2026-02-03 13:31 ` [PATCH b4 05/21] docs: config: separate b4.thanks-pr-template and b4.thanks-am-template Quentin Schulz
@ 2026-02-03 13:31 ` Quentin Schulz
2026-02-03 13:31 ` [PATCH b4 07/21] docs: use versionadded admonition for sections Quentin Schulz
` (16 subsequent siblings)
22 siblings, 0 replies; 25+ messages in thread
From: Quentin Schulz @ 2026-02-03 13:31 UTC (permalink / raw)
To: Kernel.org Tools; +Cc: Konstantin Ryabitsev, Quentin Schulz
From: Quentin Schulz <quentin.schulz@cherry.de>
rST provides directives[1] to specify for which version something was
added or modified, so let's use that.
This notably frees the definition list's term of the version string
which will be important in the next commit where the definition lists
are replaced by glossary terms such that they automatically provide an
anchor which makes it easier to share a link to the option or parameter
and also allows to link at the term definition with :term: across the
docs.
[1] https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#describing-changes-between-versions
Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
docs/contributor/prep.rst | 32 ++++++++++++++++++++++++--------
docs/contributor/send.rst | 8 ++++++--
docs/maintainer/am-shazam.rst | 8 ++++++--
docs/maintainer/mbox.rst | 12 +++++++++---
docs/maintainer/ty.rst | 4 +++-
5 files changed, 48 insertions(+), 16 deletions(-)
diff --git a/docs/contributor/prep.rst b/docs/contributor/prep.rst
index 4c26602..122e3cd 100644
--- a/docs/contributor/prep.rst
+++ b/docs/contributor/prep.rst
@@ -372,16 +372,20 @@ modifying defaults for some of these flags.
don't like vim, you would have already set your ``$EDITOR`` to use
some other command.
-``--edit-deps`` **(v0.14+)**
+``--edit-deps``
Lets you edit the series dependencies using the editor command defined
in git-config as ``core.editor``, the ``$EDITOR`` environment var if
that isn't found, or ``vim``.
-``--check-deps`` **(v0.14+)**
+ .. versionadded:: v0.14
+
+``--check-deps``
Verifies that b4 can resolve all specified dependencies and that
everything cleanly applies to the base-commit specified.
-``--check`` **(v0.14+)**
+ .. versionadded:: v0.14
+
+``--check``
Runs a set of checks on your series to identify some of the more
common problems.
@@ -402,6 +406,8 @@ modifying defaults for some of these flags.
./scripts/checkpatch.pl --strict --git $(b4 prep --show-info series-range)
+ .. versionadded:: v0.14
+
``--show-revision``
Shows the current series revision.
@@ -409,13 +415,15 @@ modifying defaults for some of these flags.
Forces the revision to a different integer number. This modifies your
cover letter and tracking information and makes this change permanent.
-``--compare-to vN`` **(v0.11+)**
+``--compare-to vN``
This executes a ``git range-diff`` command that lets you compare the
previously sent version of the series to what is currently in your
working branch. This is very useful right before sending off a new
revision to make sure that you didn't forget to include anything into
changelogs.
+ .. versionadded:: v0.11
+
``--manual-reroll MSGID``
Normally, your patch series should be automatically rerolled to the
next version after a successful ``b4 send`` operation (see
@@ -425,7 +433,7 @@ modifying defaults for some of these flags.
from the public-inbox server, so we can properly add the reference to
the previously sent series to the cover letter changelog.
-``--set-prefixes PREFIX [PREFIX ...]`` **(v0.11+)**
+``--set-prefixes PREFIX [PREFIX ...]``
If you want to mark your patch as ``RFC``, ``WIP``, or add any other
subsystem identifiers, you can define them via this command. Do
**not** add ``PATCH`` or ``v1`` here, as these are already
@@ -440,11 +448,15 @@ modifying defaults for some of these flags.
When b4 sends the message, it should add ``PATCH``, ``vN``, to the
subject as necessary.
-``--add-prefixes PREFIX [PREFIX ...]`` **(v0.14+)**
+ .. versionadded:: v0.11
+
+``--add-prefixes PREFIX [PREFIX ...]``
Similar to ``--set-prefixes``, but will add prefixes to any ones
currently defined, as opposed to completely replacing them.
-``--show-info [PARAM]`` **(v0.13+)**
+ .. versionadded:: v0.14
+
+``--show-info [PARAM]``
Dumps information about the current series in a format suitable for
parsing by other tools. Starting with v0.13, the parameter can be one
of the following:
@@ -471,7 +483,9 @@ modifying defaults for some of these flags.
b4 prep --show-info
-``--cleanup [BRANCHNAME]`` **(v0.13+)**
+ .. versionadded:: v0.13
+
+``--cleanup [BRANCHNAME]``
Archive and delete obsolete prep-managed branches and all git objects
related to them, such as sent tags. Run without parameters to list
all known prep-managed branches in the repository. Rerun with the
@@ -479,6 +493,8 @@ modifying defaults for some of these flags.
and tracking information, and then delete all git objects related to
that series from the local repository.
+ .. versionadded:: v0.13
+
``-n NEW_SERIES_NAME, --new NEW_SERIES_NAME``
Creates a new branch to start work on a new patch series.
diff --git a/docs/contributor/send.rst b/docs/contributor/send.rst
index 0de2aa5..f9fd9e4 100644
--- a/docs/contributor/send.rst
+++ b/docs/contributor/send.rst
@@ -279,19 +279,23 @@ Command line flags
actually sending things out and lets you verify that all patches are
looking good and all recipients are correctly set.
-``--preview-to`` **(v0.13+)**
+``--preview-to``
Sometimes it's useful to send your series for a pre-review to a
colleague, mentor, boss, etc. Using this option sends out the prepared
patches to the addresses specified on the command line, but doesn't
reroll your series, allowing you to send the actual submission at some
later point.
-``--reflect`` **(v0.11+)**
+ .. versionadded:: v0.13
+
+``--reflect``
Prepares everything for sending, but only emails yourself (the address
in the ``From:`` header). Useful as a last step to make sure that
everything is looking good, and especially useful when using the web
endpoint, because it may rewrite your From: header for DMARC reasons.
+ .. versionadded:: v0.11
+
``--no-trailer-to-cc``
Tells b4 not to add any addresses found in the cover or patch trailers
to To: or Cc:. This is usually handy for testing purposes, in case you
diff --git a/docs/maintainer/am-shazam.rst b/docs/maintainer/am-shazam.rst
index b691706..1ca9b50 100644
--- a/docs/maintainer/am-shazam.rst
+++ b/docs/maintainer/am-shazam.rst
@@ -75,12 +75,14 @@ The following flags are common to both commands:
This lets you force b4 to ignore cache and retrieve the latest
results.
-``--single-message`` **(0.13+)**
+``--single-message``
By default, b4 retrieves the entire thread, but sometimes you really
just want a single message. This helps when someone posts a patch in
the middle of a long thread and you just want that patch and ignore
the rest of the messages.
+ .. versionadded:: v0.13
+
``-v WANTVER, --use-version WANTVER``
If a thread (or threads, when used with ``-c``) contains multiple
patch series revisions, b4 automatically picks the highest numbered
@@ -162,7 +164,7 @@ The following flags are common to both commands:
translated into left-to-right languages), you can override the default
behavior with this switch.
-``--check`` **(0.14+)**
+``--check``
Tells b4 to run a series of local checks on each patch of the series
and display any problems. When b4 finds a valid patchwork project
definition in the configuration settings, it also looks up the CI
@@ -178,6 +180,8 @@ The following flags are common to both commands:
[b4]
am-perpatch-check-cmd = ./scripts/checkpatch.pl -q --terse --no-summary --mailback --strict
+ .. versionadded:: v0.14
+
Flags only valid for ``b4 am``
------------------------------
The following flags only make sense for ``b4 am``:
diff --git a/docs/maintainer/mbox.rst b/docs/maintainer/mbox.rst
index b4bba22..f3597a9 100644
--- a/docs/maintainer/mbox.rst
+++ b/docs/maintainer/mbox.rst
@@ -33,7 +33,7 @@ Option flags
and you need to do some work while offline. You can pass ``-`` to read
messages from stdin.
-``--stdin-pipe-sep STDIN_PIPE_SEP`` **(0.11+)**
+``--stdin-pipe-sep STDIN_PIPE_SEP``
When reading input from stdin, split messages using the string passed
as parameter. Otherwise, b4 expects stdin to be a single message or a
valid mbox.
@@ -45,17 +45,21 @@ Option flags
Then invoke b4 with ``-m - --stdin-pipe-sep='\n---randomstr---\n'``
+ .. versionadded:: v0.11
+
``-C, --no-cache``
By default, b4 will cache the retrieved threads for about 10 minutes.
This lets you force b4 to ignore cache and retrieve the latest
results.
-``--single-message`` **(0.13+)**
+``--single-message``
By default, b4 will retrieve the entire thread, but sometimes you
really just want a single message. This helps when someone posts a
patch in the middle of a long thread and you just want that patch and
ignore the rest of what is going on.
+ .. versionadded:: v0.13
+
``-o OUTDIR, --outdir OUTDIR``
Instead of writing the .mbox file to the current directory, write it
to this location instead. You can also pass a path to an existing
@@ -85,7 +89,7 @@ Option flags
that aren't already present. Note, that this uses simple message-id
matching and no other checks for correctness are performed.
-``-r MBOX, --refetch MBOX`` **(v0.12+)**
+``-r MBOX, --refetch MBOX``
This allows you to refetch all messages in the provided mailbox from
the upstream public-inbox server. For example, this is useful when you
have a .mbx file prepared by ``b4 am`` and you want to send a
@@ -93,6 +97,8 @@ Option flags
original message headers that may have been dropped or modified by
``b4 am``.
+ .. versionadded:: v0.12
+
Using with mutt
---------------
If you are a mutt or neomutt user and your mail is stored locally, you
diff --git a/docs/maintainer/ty.rst b/docs/maintainer/ty.rst
index b445bb6..21c56de 100644
--- a/docs/maintainer/ty.rst
+++ b/docs/maintainer/ty.rst
@@ -130,6 +130,8 @@ Optional flags
state instead of the default specified in config settings (use with
-a, -t or -d). See :ref:`patchwork_settings` for more details.
-``--me-too`` **(v0.15+)**
+``--me-too``
Include yourself in the thank-you message cc's. This is useful if you
want to keep track of which patches you applied to your tree.
+
+ .. versionadded:: v0.15
--
2.52.0
^ permalink raw reply related [flat|nested] 25+ messages in thread* [PATCH b4 07/21] docs: use versionadded admonition for sections
2026-02-03 13:30 [PATCH b4 00/21] docs: various fixes + migration from definition lists to glossaries for config settings Quentin Schulz
` (5 preceding siblings ...)
2026-02-03 13:31 ` [PATCH b4 06/21] docs: use rST version admonitions for command options Quentin Schulz
@ 2026-02-03 13:31 ` Quentin Schulz
2026-02-03 13:31 ` [PATCH b4 08/21] docs: maintainer: use deprecated admonition Quentin Schulz
` (15 subsequent siblings)
22 siblings, 0 replies; 25+ messages in thread
From: Quentin Schulz @ 2026-02-03 13:31 UTC (permalink / raw)
To: Kernel.org Tools; +Cc: Konstantin Ryabitsev, Quentin Schulz
From: Quentin Schulz <quentin.schulz@cherry.de>
So that we use version admonitions consistently across the docs for
things that were added or modified in given releases.
Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
docs/contributor/prep.rst | 9 +++++++--
docs/contributor/send.rst | 14 ++++++++++----
2 files changed, 17 insertions(+), 6 deletions(-)
diff --git a/docs/contributor/prep.rst b/docs/contributor/prep.rst
index 122e3cd..6e90b10 100644
--- a/docs/contributor/prep.rst
+++ b/docs/contributor/prep.rst
@@ -187,7 +187,9 @@ additional information about the intent of your entire series.
Working with series dependencies
--------------------------------
-.. warning:: new in **(v0.14+)**
+.. versionadded:: v0.14
+
+.. warning::
This is an experimental set of features introduced in v0.14. It may
have rough edges or unexpected bugs.
@@ -314,7 +316,10 @@ This may also be already set by the project, if they have a
Checking your work
------------------
-.. warning:: new in **(v0.14+)**
+
+.. versionadded:: v0.14
+
+.. warning::
This is a new feature in version 0.14 and you should consider it
experimental.
diff --git a/docs/contributor/send.rst b/docs/contributor/send.rst
index f9fd9e4..f5a1ff1 100644
--- a/docs/contributor/send.rst
+++ b/docs/contributor/send.rst
@@ -170,8 +170,11 @@ sending your work.
prep``, but future versions may support sending arbitrary patches
generated with ``git format-patch``.
-Passing pre-flight checks **(v0.14+)**
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Passing pre-flight checks
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: v0.14
+
B4 defines some pre-flight checks that should be passing, or the command
generates a warning:
@@ -230,8 +233,11 @@ When ``--reflect`` is on:
public-inbox feed
* your branch is **not** automatically rerolled to the next revision
-Checking things over with ``--preview-to`` **(v0.13+)**
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Checking things over with ``--preview-to``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: v0.13
+
Sometimes you want to ask your friend, colleague, boss, or mentor to
give your submission a quick review. You can send them your series using
``--preview-to boss@example.com`` before you send things out to the
--
2.52.0
^ permalink raw reply related [flat|nested] 25+ messages in thread* [PATCH b4 08/21] docs: maintainer: use deprecated admonition
2026-02-03 13:30 [PATCH b4 00/21] docs: various fixes + migration from definition lists to glossaries for config settings Quentin Schulz
` (6 preceding siblings ...)
2026-02-03 13:31 ` [PATCH b4 07/21] docs: use versionadded admonition for sections Quentin Schulz
@ 2026-02-03 13:31 ` Quentin Schulz
2026-02-03 13:31 ` [PATCH b4 09/21] docs: config: provide link to git-config conf file documentation Quentin Schulz
` (14 subsequent siblings)
22 siblings, 0 replies; 25+ messages in thread
From: Quentin Schulz @ 2026-02-03 13:31 UTC (permalink / raw)
To: Kernel.org Tools; +Cc: Konstantin Ryabitsev, Quentin Schulz
From: Quentin Schulz <quentin.schulz@cherry.de>
Use the rST deprecated admonition[1] to specify since which release this
has been deprecated.
One can add information as to what to replace the option with, so that's
what's done wherever we have that information.
The version is the first one to have the commits which inserts the
deprecated string for the options, which is commit 2ce1e619ddb4 ("docs:
complete most of the maintainer docs") available in v0.10.
[1] https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-deprecated
Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
docs/maintainer/diff.rst | 14 +++++++++-----
docs/maintainer/pr.rst | 13 +++++++++----
2 files changed, 18 insertions(+), 9 deletions(-)
diff --git a/docs/maintainer/diff.rst b/docs/maintainer/diff.rst
index 4e3fac0..f546fd6 100644
--- a/docs/maintainer/diff.rst
+++ b/docs/maintainer/diff.rst
@@ -50,10 +50,14 @@ Optional flags
.. versionadded:: v0.15
``-o OUTDIFF, --output-diff OUTDIFF``
- **(DEPRECATED)** Sends ``range-diff`` output into a file. You should use
- ``-n`` instead and redirect output from the actual ``git range-diff``
- command.
+ Sends ``range-diff`` output into a file.
+
+ .. deprecated:: v0.10
+ You should use ``-n`` instead and redirect output from the actual
+ ``git range-diff`` command.
``-c, --color``
- **(DEPRECATED)** Show colour output even when outputting into a file.
- You should use ``-n`` instead and modify flags to ``range-diff``.
+ Show colour output even when outputting into a file.
+
+ .. deprecated:: v0.10
+ You should use ``-n`` instead and modify flags to ``range-diff``.
diff --git a/docs/maintainer/pr.rst b/docs/maintainer/pr.rst
index 46db7ee..ca0310d 100644
--- a/docs/maintainer/pr.rst
+++ b/docs/maintainer/pr.rst
@@ -64,14 +64,19 @@ archival public-inbox so they can be analyzed by archivists at a later
date if necessary.
``-f MAILFROM, --from-addr MAILFROM``
- **(DEPRECATED)** When exploding pull requests, use this email address
+ When exploding pull requests, use this email address
in the From header, instead of reusing the same From as in the pull
request.
+ .. deprecated:: v0.10
+
``-s SENDIDENTITY, --send-as-identity SENDIDENTITY``
- **(DEPRECATED)** When resending pull requests as patch series, use
+ When resending pull requests as patch series, use
this sendemail identity.
-``--dry-run``
- **(DEPRECATED)** Force a --dry-run on ``git-send-email`` invocation.
+ .. deprecated:: v0.10
+``--dry-run``
+ Force a --dry-run on ``git-send-email`` invocation.
+
+ .. deprecated:: v0.10
--
2.52.0
^ permalink raw reply related [flat|nested] 25+ messages in thread* [PATCH b4 09/21] docs: config: provide link to git-config conf file documentation
2026-02-03 13:30 [PATCH b4 00/21] docs: various fixes + migration from definition lists to glossaries for config settings Quentin Schulz
` (7 preceding siblings ...)
2026-02-03 13:31 ` [PATCH b4 08/21] docs: maintainer: use deprecated admonition Quentin Schulz
@ 2026-02-03 13:31 ` Quentin Schulz
2026-02-03 13:31 ` [PATCH b4 10/21] docs: config: fix discrepancy between example strings Quentin Schulz
` (13 subsequent siblings)
22 siblings, 0 replies; 25+ messages in thread
From: Quentin Schulz @ 2026-02-03 13:31 UTC (permalink / raw)
To: Kernel.org Tools; +Cc: Konstantin Ryabitsev, Quentin Schulz
From: Quentin Schulz <quentin.schulz@cherry.de>
So that it's easier to get access to the appropriate git-config
documentation.
Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
docs/config.rst | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/docs/config.rst b/docs/config.rst
index a9006a5..594a857 100644
--- a/docs/config.rst
+++ b/docs/config.rst
@@ -1,6 +1,7 @@
Configuration options
=====================
-B4 doesn't have a separate configuration file but uses ``git-config`` to
+B4 doesn't have a separate configuration file but uses
+`git-config <https://git-scm.com/docs/git-config#_configuration_file>`__ to
retrieve a set of b4-specific settings. This means that you can have three
levels of b4 configuration:
--
2.52.0
^ permalink raw reply related [flat|nested] 25+ messages in thread* [PATCH b4 10/21] docs: config: fix discrepancy between example strings
2026-02-03 13:30 [PATCH b4 00/21] docs: various fixes + migration from definition lists to glossaries for config settings Quentin Schulz
` (8 preceding siblings ...)
2026-02-03 13:31 ` [PATCH b4 09/21] docs: config: provide link to git-config conf file documentation Quentin Schulz
@ 2026-02-03 13:31 ` Quentin Schulz
2026-02-03 13:31 ` [PATCH b4 11/21] docs: move sentence-ending dots from within the last quoted string to outside Quentin Schulz
` (12 subsequent siblings)
22 siblings, 0 replies; 25+ messages in thread
From: Quentin Schulz @ 2026-02-03 13:31 UTC (permalink / raw)
To: Kernel.org Tools; +Cc: Konstantin Ryabitsev, Quentin Schulz
From: Quentin Schulz <quentin.schulz@cherry.de>
Commit 707da4b965ea ("am: add the -i/--add-message-id switch") updated
the example code-block but not the string in the sentence that precedes
the code-block, resulting in a mismatch. Let's fix this oversight.
Fixes: 707da4b965ea ("am: add the -i/--add-message-id switch")
Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
docs/config.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/config.rst b/docs/config.rst
index 594a857..6b33c33 100644
--- a/docs/config.rst
+++ b/docs/config.rst
@@ -61,7 +61,7 @@ These options control many of the core features of b4.
``b4.linktrailermask`` (v0.13+)
Overrides the format of the ``Link:`` trailer, in case you want to
call it something other than "Link." For example, some projects
- use "Message-Id" trailers instead::
+ use "Message-ID" trailers instead::
linktrailermask = Message-ID: <%s>
--
2.52.0
^ permalink raw reply related [flat|nested] 25+ messages in thread* [PATCH b4 11/21] docs: move sentence-ending dots from within the last quoted string to outside
2026-02-03 13:30 [PATCH b4 00/21] docs: various fixes + migration from definition lists to glossaries for config settings Quentin Schulz
` (9 preceding siblings ...)
2026-02-03 13:31 ` [PATCH b4 10/21] docs: config: fix discrepancy between example strings Quentin Schulz
@ 2026-02-03 13:31 ` Quentin Schulz
2026-02-03 13:31 ` [PATCH b4 12/21] docs: config: add missing dot at end of sentence Quentin Schulz
` (11 subsequent siblings)
22 siblings, 0 replies; 25+ messages in thread
From: Quentin Schulz @ 2026-02-03 13:31 UTC (permalink / raw)
To: Kernel.org Tools; +Cc: Konstantin Ryabitsev, Quentin Schulz, Your Name
From: Quentin Schulz <quentin.schulz@cherry.de>
These dots aren't meant to be part of the quoted string but as
sentence-ending dots so let's fix that.
Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
docs/config.rst | 6 +++---
docs/contributor/prep.rst | 2 +-
2 files changed, 4 insertions(+), 4 deletions(-)
diff --git a/docs/config.rst b/docs/config.rst
index 6b33c33..aff0ec3 100644
--- a/docs/config.rst
+++ b/docs/config.rst
@@ -60,7 +60,7 @@ These options control many of the core features of b4.
``b4.linktrailermask`` (v0.13+)
Overrides the format of the ``Link:`` trailer, in case you want to
- call it something other than "Link." For example, some projects
+ call it something other than "Link". For example, some projects
use "Message-ID" trailers instead::
linktrailermask = Message-ID: <%s>
@@ -85,7 +85,7 @@ These options control many of the core features of b4.
``b4.save-maildirs``
The "mbox" file format is actually several incompatible standards,
- such as "mboxo" vs. "mboxrd." Setting this option can avoid potential
+ such as "mboxo" vs. "mboxrd". Setting this option can avoid potential
problems by saving retrieved threads as Maildirs.
Default: ``no``
@@ -116,7 +116,7 @@ These options control many of the core features of b4.
Signed-off-by: Your Name <your.name@example.com>
Your custody section is beneath "Ezri Submaintainer," so the only
- trailers considered for reordering are "Link" and "Tested-by." Your
+ trailers considered for reordering are "Link" and "Tested-by". Your
own Signed-off-by trailer is always at the bottom of your own custody
section.
diff --git a/docs/contributor/prep.rst b/docs/contributor/prep.rst
index 6e90b10..9c27b64 100644
--- a/docs/contributor/prep.rst
+++ b/docs/contributor/prep.rst
@@ -126,7 +126,7 @@ Enrolling an existing branch
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you've already started working on a set of commits without first
running ``b4 prep -n``, you can enroll your existing branch to make it
-"prep-tracked."
+"prep-tracked".
For example, if you have a branch called ``my-topical-branch`` that was
forked from ``master``, you can enroll it with b4::
--
2.52.0
^ permalink raw reply related [flat|nested] 25+ messages in thread* [PATCH b4 12/21] docs: config: add missing dot at end of sentence
2026-02-03 13:30 [PATCH b4 00/21] docs: various fixes + migration from definition lists to glossaries for config settings Quentin Schulz
` (10 preceding siblings ...)
2026-02-03 13:31 ` [PATCH b4 11/21] docs: move sentence-ending dots from within the last quoted string to outside Quentin Schulz
@ 2026-02-03 13:31 ` Quentin Schulz
2026-02-03 13:31 ` [PATCH b4 13/21] docs: config: provide link to patatt Quentin Schulz
` (10 subsequent siblings)
22 siblings, 0 replies; 25+ messages in thread
From: Quentin Schulz @ 2026-02-03 13:31 UTC (permalink / raw)
To: Kernel.org Tools; +Cc: Konstantin Ryabitsev, Quentin Schulz
From: Quentin Schulz <quentin.schulz@cherry.de>
The other definition lists always have an end-of-sentence dot, so let's
be consistent here.
Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
docs/config.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/config.rst b/docs/config.rst
index aff0ec3..5b1954d 100644
--- a/docs/config.rst
+++ b/docs/config.rst
@@ -151,7 +151,7 @@ These settings control ``b4 am`` and ``b4 shazam`` behavior.
``b4.shazam-merge-flags``
Additional flags to pass to ``git merge`` when performing a merge with
- ``b4 shazam -M``
+ ``b4 shazam -M``.
Default: ``--signoff``
--
2.52.0
^ permalink raw reply related [flat|nested] 25+ messages in thread* [PATCH b4 13/21] docs: config: provide link to patatt
2026-02-03 13:30 [PATCH b4 00/21] docs: various fixes + migration from definition lists to glossaries for config settings Quentin Schulz
` (11 preceding siblings ...)
2026-02-03 13:31 ` [PATCH b4 12/21] docs: config: add missing dot at end of sentence Quentin Schulz
@ 2026-02-03 13:31 ` Quentin Schulz
2026-02-03 13:31 ` [PATCH b4 14/21] docs: config: provide link to git-send-email manpage Quentin Schulz
` (9 subsequent siblings)
22 siblings, 0 replies; 25+ messages in thread
From: Quentin Schulz @ 2026-02-03 13:31 UTC (permalink / raw)
To: Kernel.org Tools; +Cc: Konstantin Ryabitsev, Quentin Schulz
From: Quentin Schulz <quentin.schulz@cherry.de>
We already provide a link to patatt in b4.attestation-policy so let's do
that for b4.keyringsrc as well.
Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
docs/config.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/config.rst b/docs/config.rst
index 5b1954d..2465ad0 100644
--- a/docs/config.rst
+++ b/docs/config.rst
@@ -220,7 +220,7 @@ Attestation settings
Default: ``None``
``b4.keyringsrc``
- See ``patatt`` for details on how to configure keyrings. For example,
+ See `patatt`_ for details on how to configure keyrings. For example,
you can clone the kernel.org pgp keys repository and use it for
attestation::
--
2.52.0
^ permalink raw reply related [flat|nested] 25+ messages in thread* [PATCH b4 14/21] docs: config: provide link to git-send-email manpage
2026-02-03 13:30 [PATCH b4 00/21] docs: various fixes + migration from definition lists to glossaries for config settings Quentin Schulz
` (12 preceding siblings ...)
2026-02-03 13:31 ` [PATCH b4 13/21] docs: config: provide link to patatt Quentin Schulz
@ 2026-02-03 13:31 ` Quentin Schulz
2026-02-03 13:31 ` [PATCH b4 15/21] docs: config: fix double colon typo Quentin Schulz
` (8 subsequent siblings)
22 siblings, 0 replies; 25+ messages in thread
From: Quentin Schulz @ 2026-02-03 13:31 UTC (permalink / raw)
To: Kernel.org Tools; +Cc: Konstantin Ryabitsev, Quentin Schulz
From: Quentin Schulz <quentin.schulz@cherry.de>
Makes it easier for users to have access to the manpage from the
browser.
Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
docs/config.rst | 5 +++--
1 file changed, 3 insertions(+), 2 deletions(-)
diff --git a/docs/config.rst b/docs/config.rst
index 2465ad0..3abe80a 100644
--- a/docs/config.rst
+++ b/docs/config.rst
@@ -294,8 +294,9 @@ Attestation settings
``b4.sendemail-identity``
The ``sendemail`` identity to use when sending mail directly with b4.
- This setting applies to ``b4 send`` and ``b4 ty``. See ``man
- git-send-email`` for info about sendemail identities.
+ This setting applies to ``b4 send`` and ``b4 ty``. See `man
+ git-send-email <https://git-scm.com/docs/git-send-email>`__ for info about
+ sendemail identities.
Default: ``None``
--
2.52.0
^ permalink raw reply related [flat|nested] 25+ messages in thread* [PATCH b4 15/21] docs: config: fix double colon typo
2026-02-03 13:30 [PATCH b4 00/21] docs: various fixes + migration from definition lists to glossaries for config settings Quentin Schulz
` (13 preceding siblings ...)
2026-02-03 13:31 ` [PATCH b4 14/21] docs: config: provide link to git-send-email manpage Quentin Schulz
@ 2026-02-03 13:31 ` Quentin Schulz
2026-02-03 13:31 ` [PATCH b4 16/21] docs: config: provide example content for template files Quentin Schulz
` (7 subsequent siblings)
22 siblings, 0 replies; 25+ messages in thread
From: Quentin Schulz @ 2026-02-03 13:31 UTC (permalink / raw)
To: Kernel.org Tools; +Cc: Konstantin Ryabitsev, Quentin Schulz
From: Quentin Schulz <quentin.schulz@cherry.de>
This currently renders as "Default::" in the build output, which is
wrong. Let's fix that by using the same style as everywhere else, that
is, one colon.
Fixes: cd43f60e6a49 ("docs: proofread and fixes")
Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
docs/config.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/config.rst b/docs/config.rst
index 3abe80a..9da8e32 100644
--- a/docs/config.rst
+++ b/docs/config.rst
@@ -402,7 +402,7 @@ Contributor-oriented settings
stdin. If b4 finds ``scripts/get_maintainer.pl`` at the top of your git tree,
it uses the command shown below by default.
- Default:: ``scripts/get_maintainer.pl --nogit --nogit-fallback --nogit-chief-penguins --norolestats --nom``
+ Default: ``scripts/get_maintainer.pl --nogit --nogit-fallback --nogit-chief-penguins --norolestats --nom``
``b4.send-same-thread`` (v0.13+)
When sending a new version of a series, send it in the same thread as
--
2.52.0
^ permalink raw reply related [flat|nested] 25+ messages in thread* [PATCH b4 16/21] docs: config: provide example content for template files
2026-02-03 13:30 [PATCH b4 00/21] docs: various fixes + migration from definition lists to glossaries for config settings Quentin Schulz
` (14 preceding siblings ...)
2026-02-03 13:31 ` [PATCH b4 15/21] docs: config: fix double colon typo Quentin Schulz
@ 2026-02-03 13:31 ` Quentin Schulz
2026-02-03 13:31 ` [PATCH b4 17/21] docs: config: use rST version admonitions Quentin Schulz
` (6 subsequent siblings)
22 siblings, 0 replies; 25+ messages in thread
From: Quentin Schulz @ 2026-02-03 13:31 UTC (permalink / raw)
To: Kernel.org Tools; +Cc: Konstantin Ryabitsev, Quentin Schulz
From: Quentin Schulz <quentin.schulz@cherry.de>
Instead of telling user to have a look at example templates stored in
the repo, directly include them in the docs such that they don't have to
look for them.
Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
docs/config.rst | 14 ++++++++++----
1 file changed, 10 insertions(+), 4 deletions(-)
diff --git a/docs/config.rst b/docs/config.rst
index 9da8e32..edd4678 100644
--- a/docs/config.rst
+++ b/docs/config.rst
@@ -156,8 +156,10 @@ These settings control ``b4 am`` and ``b4 shazam`` behavior.
Default: ``--signoff``
``b4.shazam-merge-template``
- Path to a template to use when creating a merge commit. See
- ``shazam-merge-template.example`` for an example.
+ Path to a template to use when creating a merge commit. Take the following
+ as example content for this file:
+
+ .. literalinclude:: ../src/b4/templates/shazam-merge-template.example
Default: ``None``
@@ -239,13 +241,17 @@ Attestation settings
~~~~~~~~~~~~~~~
``b4.thanks-pr-template``
Full paths to the templates to use when generating thank-you messages
- for contributors. See example templates provided with the project.
+ for contributors. Take the following as example content for this file:
+
+ .. literalinclude:: ../src/b4/templates/thanks-pr-template.example
Default: ``None``
``b4.thanks-am-template``
Full paths to the templates to use when generating thank-you messages
- for contributors. See example templates provided with the project.
+ for contributors. Take the following as example content for this file:
+
+ .. literalinclude:: ../src/b4/templates/thanks-am-template.example
Default: ``None``
--
2.52.0
^ permalink raw reply related [flat|nested] 25+ messages in thread* [PATCH b4 17/21] docs: config: use rST version admonitions
2026-02-03 13:30 [PATCH b4 00/21] docs: various fixes + migration from definition lists to glossaries for config settings Quentin Schulz
` (15 preceding siblings ...)
2026-02-03 13:31 ` [PATCH b4 16/21] docs: config: provide example content for template files Quentin Schulz
@ 2026-02-03 13:31 ` Quentin Schulz
2026-02-03 13:31 ` [PATCH b4 18/21] docs: config: migrate definition lists to glossaries Quentin Schulz
` (5 subsequent siblings)
22 siblings, 0 replies; 25+ messages in thread
From: Quentin Schulz @ 2026-02-03 13:31 UTC (permalink / raw)
To: Kernel.org Tools; +Cc: Konstantin Ryabitsev, Quentin Schulz
From: Quentin Schulz <quentin.schulz@cherry.de>
rST provides directives[1] to specify for which version something was
added or modified, so let's use that.
This notably frees the definition list's term of the version string
which will be important in the next commit where the definition lists
are replaced by glossary terms such that they automatically provide an
anchor which makes it easier to share a link to the config setting and
also allows to link at the term definition with :term: across the docs.
[1] https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#describing-changes-between-versions
Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
docs/config.rst | 52 +++++++++++++++++++++++++++++++++++++---------------
1 file changed, 37 insertions(+), 15 deletions(-)
diff --git a/docs/config.rst b/docs/config.rst
index edd4678..735684e 100644
--- a/docs/config.rst
+++ b/docs/config.rst
@@ -58,7 +58,7 @@ These options control many of the core features of b4.
Default: ``https://lore.kernel.org/all/?x=m&t=1&q=%s``
-``b4.linktrailermask`` (v0.13+)
+``b4.linktrailermask``
Overrides the format of the ``Link:`` trailer, in case you want to
call it something other than "Link". For example, some projects
use "Message-ID" trailers instead::
@@ -67,12 +67,14 @@ These options control many of the core features of b4.
The ``%s`` is the placeholder for the message-id.
- Note: starting with version 0.14, you can pass the ``-i`` command-line
- switch instead of ``-l`` to automatically insert the ``Message-ID``
- trailer.
-
Default: ``Link: https://lore.kernel.org/%s``
+ .. versionadded:: v0.13
+
+ .. versionchanged:: v0.14
+ You can now pass the ``-i`` command-line switch instead of ``-l`` to
+ automatically insert the ``Message-ID`` trailer.
+
``b4.listid-preference``
Sometimes messages with the same message-id can have different
contents, because some servers modify message bodies to inject list
@@ -163,7 +165,7 @@ These settings control ``b4 am`` and ``b4 shazam`` behavior.
Default: ``None``
-``b4.am-perpatch-check-cmd`` (v0.14+)
+``b4.am-perpatch-check-cmd``
The command to use when running ``--check``. The command is run once for each
patch to check. The patch file to check is piped through stdin. If this
config is defined multiple times, all commands will be run. If this config is
@@ -172,6 +174,8 @@ These settings control ``b4 am`` and ``b4 shazam`` behavior.
Default: ``./scripts/checkpatch.pl -q --terse --no-summary --mailback``
+ .. versionadded:: v0.14
+
.. _attestation_settings:
Attestation settings
@@ -193,7 +197,7 @@ Attestation settings
Default: ``yes``
-``b4.attestation-dns-resolvers`` (v0.14+)
+``b4.attestation-dns-resolvers``
You can specify your own DNS servers if you are on a company network
and your OS-provided resolvers aren't able to perform domain key
lookups. For example, to use Google DNS servers::
@@ -202,6 +206,8 @@ Attestation settings
Default: ``None``
+ .. versionadded:: v0.14
+
``b4.attestation-staleness-days``
Ignore attestation signatures that are more than this many days
old. This helps avoid a class of attacks when someone re-sends old
@@ -269,7 +275,7 @@ Attestation settings
Default: ``None``
-``b4.thanks-from-name`` (v0.13+)
+``b4.thanks-from-name``
The name to use in the ``From:`` header when sending thank-you notes.
By default, b4 uses ``user.name``. For example::
@@ -277,7 +283,9 @@ Attestation settings
Default: ``None``
-``b4.thanks-from-email`` (v0.13+)
+ .. versionadded:: v0.13
+
+``b4.thanks-from-email``
The email to use in the ``From:`` header when sending thank-you notes.
By default, b4 uses ``user.email``. For example::
@@ -285,6 +293,8 @@ Attestation settings
Default: ``None``
+ .. versionadded:: v0.13
+
``b4.thanks-treename``
Name of the tree to use in the thank-you templates.
@@ -306,12 +316,14 @@ Attestation settings
Default: ``None``
-``b4.ty-send-email`` (v0.11+)
+``b4.ty-send-email``
When set, tells ``b4 ty`` to send email directly instead of writing
out ``.thanks`` files.
Default: ``no``
+ .. versionadded:: v0.11
+
.. _patchwork_settings:
Patchwork integration settings
@@ -410,19 +422,24 @@ Contributor-oriented settings
Default: ``scripts/get_maintainer.pl --nogit --nogit-fallback --nogit-chief-penguins --norolestats --nom``
-``b4.send-same-thread`` (v0.13+)
+``b4.send-same-thread``
When sending a new version of a series, send it in the same thread as
the previous version. The config supports the following values:
* ``yes``, ``true``, ``y``: B4 sends the first message of the new series as a
reply to the previous version's cover letter.
* ``shallow``: B4 sends the first message of the new series as a reply to the
- first version's cover letter. (v0.15+)
+ first version's cover letter.
* ``no``: B4 does not send the new version of the series in the same thread
as any previous version.
Default: ``no``
+ .. versionadded:: v0.13
+
+ .. versionchanged:: v0.15
+ Added ``shallow`` config value.
+
``b4.prep-cover-strategy``
Alternative cover letter storage strategy to use, in case you don't
want to use the default ``commit`` strategy. See
@@ -444,14 +461,16 @@ Contributor-oriented settings
Default: ``None``
-``b4.send-prefixes`` (v0.11+)
+``b4.send-prefixes``
Extra prefixes to add to ``[PATCH]`` (e.g. ``RFC mydrv``).
This setting can be replaced for a series with ``b4 prep --set-prefixes``.
Default: ``None``
-``b4.prep-perpatch-check-cmd`` (v0.14+)
+ .. versionadded:: v0.11
+
+``b4.prep-perpatch-check-cmd``
The command to use when running ``--check``. The command is run once for each
patch to check. The patch file to check is piped through stdin. If this
config is defined multiple times, all commands will be run. If this config is
@@ -460,7 +479,9 @@ Contributor-oriented settings
Default: ``./scripts/checkpatch.pl -q --terse --no-summary --mailback --showfile``
-``b4.prep-pre-flight-checks`` (v0.14+)
+ .. versionadded:: v0.14
+
+``b4.prep-pre-flight-checks``
You can use this to turn off some or all pre-flight checks that b4 runs
prior to sending out patches. To cancel all checks::
@@ -473,6 +494,7 @@ Contributor-oriented settings
[b4]
prep-pre-flight-checks = disable-needs-auto-to-cc, needs-checking
+ .. versionadded:: v0.14
To document
-----------
--
2.52.0
^ permalink raw reply related [flat|nested] 25+ messages in thread* [PATCH b4 18/21] docs: config: migrate definition lists to glossaries
2026-02-03 13:30 [PATCH b4 00/21] docs: various fixes + migration from definition lists to glossaries for config settings Quentin Schulz
` (16 preceding siblings ...)
2026-02-03 13:31 ` [PATCH b4 17/21] docs: config: use rST version admonitions Quentin Schulz
@ 2026-02-03 13:31 ` Quentin Schulz
2026-02-03 13:31 ` [PATCH b4 19/21] docs: config: sort glossaries Quentin Schulz
` (4 subsequent siblings)
22 siblings, 0 replies; 25+ messages in thread
From: Quentin Schulz @ 2026-02-03 13:31 UTC (permalink / raw)
To: Kernel.org Tools; +Cc: Konstantin Ryabitsev, Quentin Schulz
From: Quentin Schulz <quentin.schulz@cherry.de>
This allows us to have an anchor per config option which is convenient
when trying to send links to documentation of a specific config option.
The :term: cross-referencing is not necessary but it makes the option
string clickable instead of only having the ¶ character next to it to
click. This is what we use in the Yocto docs.
Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
docs/config.rst | 607 +++++++++++++++++++++++++++++---------------------------
1 file changed, 311 insertions(+), 296 deletions(-)
diff --git a/docs/config.rst b/docs/config.rst
index 735684e..cd205fd 100644
--- a/docs/config.rst
+++ b/docs/config.rst
@@ -38,107 +38,109 @@ Core options
~~~~~~~~~~~~
These options control many of the core features of b4.
-``b4.midmask``
- Specifies the server from where to retrieve the messages specified by
- their message-id.
+.. glossary::
- Default: ``https://lore.kernel.org/%s``
+ :term:`b4.midmask`
+ Specifies the server from where to retrieve the messages specified by
+ their message-id.
-``b4.linkmask``
- B4 uses this setting to construct the URL in the ``Link:`` trailers.
- If you want a shorter option, you can also use
- ``https://msgid.link/%s``, which is an alias for lore.kernel.org.
+ Default: ``https://lore.kernel.org/%s``
- Default: ``https://lore.kernel.org/%s``
+ :term:`b4.linkmask`
+ B4 uses this setting to construct the URL in the ``Link:`` trailers.
+ If you want a shorter option, you can also use
+ ``https://msgid.link/%s``, which is an alias for lore.kernel.org.
-``b4.searchmask``
- B4 uses this setting to query and retrieve threads matching specific
- search terms. For example, it can retrieve trailer updates using the
- series ``change-id`` identifier.
+ Default: ``https://lore.kernel.org/%s``
- Default: ``https://lore.kernel.org/all/?x=m&t=1&q=%s``
+ :term:`b4.searchmask`
+ B4 uses this setting to query and retrieve threads matching specific
+ search terms. For example, it can retrieve trailer updates using the
+ series ``change-id`` identifier.
-``b4.linktrailermask``
- Overrides the format of the ``Link:`` trailer, in case you want to
- call it something other than "Link". For example, some projects
- use "Message-ID" trailers instead::
+ Default: ``https://lore.kernel.org/all/?x=m&t=1&q=%s``
- linktrailermask = Message-ID: <%s>
+ :term:`b4.linktrailermask`
+ Overrides the format of the ``Link:`` trailer, in case you want to
+ call it something other than "Link". For example, some projects
+ use "Message-ID" trailers instead::
- The ``%s`` is the placeholder for the message-id.
+ linktrailermask = Message-ID: <%s>
- Default: ``Link: https://lore.kernel.org/%s``
+ The ``%s`` is the placeholder for the message-id.
- .. versionadded:: v0.13
+ Default: ``Link: https://lore.kernel.org/%s``
- .. versionchanged:: v0.14
- You can now pass the ``-i`` command-line switch instead of ``-l`` to
- automatically insert the ``Message-ID`` trailer.
+ .. versionadded:: v0.13
-``b4.listid-preference``
- Sometimes messages with the same message-id can have different
- contents, because some servers modify message bodies to inject list
- subscription information. B4 attempts to de-duplicate the results
- using the ``List-Id`` header. You may use this parameter to specify
- the order of preference, using comma-separated strings with shell-style
- wildcard globbing.
+ .. versionchanged:: v0.14
+ You can now pass the ``-i`` command-line switch instead of ``-l`` to
+ automatically insert the ``Message-ID`` trailer.
- Default: ``*.feeds.kernel.org, *.linux.dev,*.kernel.org,*``
+ :term:`b4.listid-preference`
+ Sometimes messages with the same message-id can have different
+ contents, because some servers modify message bodies to inject list
+ subscription information. B4 attempts to de-duplicate the results
+ using the ``List-Id`` header. You may use this parameter to specify
+ the order of preference, using comma-separated strings with shell-style
+ wildcard globbing.
-``b4.save-maildirs``
- The "mbox" file format is actually several incompatible standards,
- such as "mboxo" vs. "mboxrd". Setting this option can avoid potential
- problems by saving retrieved threads as Maildirs.
+ Default: ``*.feeds.kernel.org, *.linux.dev,*.kernel.org,*``
- Default: ``no``
+ :term:`b4.save-maildirs`
+ The "mbox" file format is actually several incompatible standards,
+ such as "mboxo" vs. "mboxrd". Setting this option can avoid potential
+ problems by saving retrieved threads as Maildirs.
-``b4.trailer-order``
- This lets you control the order of trailers that get added to your own
- custody section of the commit message. By default, b4 applies these
- trailers in the order received. However, if you want to list trailers
- in a specific order, you can try something like::
+ Default: ``no``
- trailer-order = link*,fixes*,acked*,reviewed*,tested*,*
+ :term:`b4.trailer-order`
+ This lets you control the order of trailers that get added to your own
+ custody section of the commit message. By default, b4 applies these
+ trailers in the order received. However, if you want to list trailers
+ in a specific order, you can try something like::
- The "chain of custody" is an important concept in patch-based code
- review process. Each "Signed-off-by" trailer indicates where the
- custody section of previous reviewer ends and the new one starts. Your
- own custody section is always between the previous-to-last
- "Signed-off-by" trailer, if any, and the bottom of the trailer
- section. For example::
+ trailer-order = link*,fixes*,acked*,reviewed*,tested*,*
- Fixes: abcde (Commit info)
- Suggested-by: Alex Reporter <alex.reporter@example.com>
- Signed-off-by: Betty Developer <betty.developer@example.com>
- Acked-by: Chandra Acker <chandra.acker@example.com>
- Reviewed-by: Debby Reviewer <debby.reviewer@example.com>
- Signed-off-by: Ezri Submaintainer <ezri.submaintainer@example.com>
- Link: https://msgid.link/some@thing.foo
- Tested-by: Finn Tester <finn.tester@example.com>
- Signed-off-by: Your Name <your.name@example.com>
+ The "chain of custody" is an important concept in patch-based code
+ review process. Each "Signed-off-by" trailer indicates where the
+ custody section of previous reviewer ends and the new one starts. Your
+ own custody section is always between the previous-to-last
+ "Signed-off-by" trailer, if any, and the bottom of the trailer
+ section. For example::
- Your custody section is beneath "Ezri Submaintainer," so the only
- trailers considered for reordering are "Link" and "Tested-by". Your
- own Signed-off-by trailer is always at the bottom of your own custody
- section.
+ Fixes: abcde (Commit info)
+ Suggested-by: Alex Reporter <alex.reporter@example.com>
+ Signed-off-by: Betty Developer <betty.developer@example.com>
+ Acked-by: Chandra Acker <chandra.acker@example.com>
+ Reviewed-by: Debby Reviewer <debby.reviewer@example.com>
+ Signed-off-by: Ezri Submaintainer <ezri.submaintainer@example.com>
+ Link: https://msgid.link/some@thing.foo
+ Tested-by: Finn Tester <finn.tester@example.com>
+ Signed-off-by: Your Name <your.name@example.com>
- Default: ``*``
+ Your custody section is beneath "Ezri Submaintainer," so the only
+ trailers considered for reordering are "Link" and "Tested-by". Your
+ own Signed-off-by trailer is always at the bottom of your own custody
+ section.
-``b4.trailers-ignore-from``
- A comma-separated list of addresses that b4 should always ignore
- when applying follow-up trailers. This is useful when dealing with
- reports generated by some automated bots. For example::
+ Default: ``*``
- trailers-ignore-from = lkp@intel.com, someotherbot@example.org
+ :term:`b4.trailers-ignore-from`
+ A comma-separated list of addresses that b4 should always ignore
+ when applying follow-up trailers. This is useful when dealing with
+ reports generated by some automated bots. For example::
- Default: ``None``
+ trailers-ignore-from = lkp@intel.com, someotherbot@example.org
-``b4.cache-expire``
- B4 caches retrieved threads for 10 minutes. This option allows
- tweaking the time that the cache remains valid. Many commands also
- allow a ``--no-cache`` flag to force b4 to perform remote lookups.
+ Default: ``None``
- Default: ``10``
+ :term:`b4.cache-expire`
+ B4 caches retrieved threads for 10 minutes. This option allows
+ tweaking the time that the cache remains valid. Many commands also
+ allow a ``--no-cache`` flag to force b4 to perform remote lookups.
+
+ Default: ``10``
.. _shazam_settings:
@@ -146,183 +148,189 @@ These options control many of the core features of b4.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These settings control ``b4 am`` and ``b4 shazam`` behavior.
-``b4.shazam-am-flags``
- Additional flags to pass to ``git am`` when applying patches.
+.. glossary::
- Default: ``None``
+ :term:`b4.shazam-am-flags`
+ Additional flags to pass to ``git am`` when applying patches.
-``b4.shazam-merge-flags``
- Additional flags to pass to ``git merge`` when performing a merge with
- ``b4 shazam -M``.
+ Default: ``None``
- Default: ``--signoff``
+ :term:`b4.shazam-merge-flags`
+ Additional flags to pass to ``git merge`` when performing a merge with
+ ``b4 shazam -M``.
-``b4.shazam-merge-template``
- Path to a template to use when creating a merge commit. Take the following
- as example content for this file:
+ Default: ``--signoff``
- .. literalinclude:: ../src/b4/templates/shazam-merge-template.example
+ :term:`b4.shazam-merge-template`
+ Path to a template to use when creating a merge commit. Take the following
+ as example content for this file:
- Default: ``None``
+ .. literalinclude:: ../src/b4/templates/shazam-merge-template.example
-``b4.am-perpatch-check-cmd``
- The command to use when running ``--check``. The command is run once for each
- patch to check. The patch file to check is piped through stdin. If this
- config is defined multiple times, all commands will be run. If this config is
- not defined and b4 finds ``scripts/checkpatch.pl`` at the top of your git
- tree, it uses the command shown below by default.
+ Default: ``None``
- Default: ``./scripts/checkpatch.pl -q --terse --no-summary --mailback``
+ :term:`b4.am-perpatch-check-cmd`
+ The command to use when running ``--check``. The command is run once for each
+ patch to check. The patch file to check is piped through stdin. If this
+ config is defined multiple times, all commands will be run. If this config is
+ not defined and b4 finds ``scripts/checkpatch.pl`` at the top of your git
+ tree, it uses the command shown below by default.
- .. versionadded:: v0.14
+ Default: ``./scripts/checkpatch.pl -q --terse --no-summary --mailback``
+
+ .. versionadded:: v0.14
.. _attestation_settings:
Attestation settings
~~~~~~~~~~~~~~~~~~~~
-``b4.attestation-policy``
- B4 supports domain-level and end-to-end attestation of patches using
- the `patatt`_ library. There are four different operation modes:
+.. glossary::
- * ``off``: don't bother checking attestation at all
- * ``softfail``: print green marks when attestation is passing and
- red marks when it's failing
- * ``hardfail``: exit with an error when any attestation checks fail
+ :term:`b4.attestation-policy`
+ B4 supports domain-level and end-to-end attestation of patches using
+ the `patatt`_ library. There are four different operation modes:
- Default: ``softfail``
+ * ``off``: don't bother checking attestation at all
+ * ``softfail``: print green marks when attestation is passing and
+ red marks when it's failing
+ * ``hardfail``: exit with an error when any attestation checks fail
-``b4.attestation-check-dkim``
- Controls whether to perform DKIM attestation checks.
+ Default: ``softfail``
- Default: ``yes``
+ :term:`b4.attestation-check-dkim`
+ Controls whether to perform DKIM attestation checks.
-``b4.attestation-dns-resolvers``
- You can specify your own DNS servers if you are on a company network
- and your OS-provided resolvers aren't able to perform domain key
- lookups. For example, to use Google DNS servers::
+ Default: ``yes``
- attestation-dns-resolvers = 8.8.8.8, 8.8.4.4
+ :term:`b4.attestation-dns-resolvers`
+ You can specify your own DNS servers if you are on a company network
+ and your OS-provided resolvers aren't able to perform domain key
+ lookups. For example, to use Google DNS servers::
- Default: ``None``
+ attestation-dns-resolvers = 8.8.8.8, 8.8.4.4
- .. versionadded:: v0.14
+ Default: ``None``
-``b4.attestation-staleness-days``
- Ignore attestation signatures that are more than this many days
- old. This helps avoid a class of attacks when someone re-sends old
- patches that contain known security bugs.
+ .. versionadded:: v0.14
- Default: ``30``
+ :term:`b4.attestation-staleness-days`
+ Ignore attestation signatures that are more than this many days
+ old. This helps avoid a class of attacks when someone re-sends old
+ patches that contain known security bugs.
-``b4.attestation-gnupghome``
- Sets ``GNUPGHOME`` before running PGP attestation checks that rely on
- GnuPG.
+ Default: ``30``
- Default: ``None``
+ :term:`b4.attestation-gnupghome`
+ Sets ``GNUPGHOME`` before running PGP attestation checks that rely on
+ GnuPG.
-``b4.gpgbin``
- Full path to a different binary to use for ``gpg``. B4 also checks the
- ``gpg.program`` setting, and uses that value, if found.
+ Default: ``None``
- Default: ``None``
+ :term:`b4.gpgbin`
+ Full path to a different binary to use for ``gpg``. B4 also checks the
+ ``gpg.program`` setting, and uses that value, if found.
-``b4.keyringsrc``
- See `patatt`_ for details on how to configure keyrings. For example,
- you can clone the kernel.org pgp keys repository and use it for
- attestation::
+ Default: ``None``
- git clone https://git.kernel.org/pub/scm/docs/kernel/pgpkeys.git
+ :term:`b4.keyringsrc`
+ See `patatt`_ for details on how to configure keyrings. For example,
+ you can clone the kernel.org pgp keys repository and use it for
+ attestation::
- Then set the following in your ``~/.gitconfig``::
+ git clone https://git.kernel.org/pub/scm/docs/kernel/pgpkeys.git
- [b4]
- keyringsrc = ~/path/to/pgpkeys/.keyring
+ Then set the following in your ``~/.gitconfig``::
- Default: ``None``
+ [b4]
+ keyringsrc = ~/path/to/pgpkeys/.keyring
+
+ Default: ``None``
.. _ty_settings:
``ty`` settings
~~~~~~~~~~~~~~~
-``b4.thanks-pr-template``
- Full paths to the templates to use when generating thank-you messages
- for contributors. Take the following as example content for this file:
- .. literalinclude:: ../src/b4/templates/thanks-pr-template.example
+.. glossary::
- Default: ``None``
+ :term:`b4.thanks-pr-template`
+ Full paths to the templates to use when generating thank-you messages
+ for contributors. Take the following as example content for this file:
-``b4.thanks-am-template``
- Full paths to the templates to use when generating thank-you messages
- for contributors. Take the following as example content for this file:
+ .. literalinclude:: ../src/b4/templates/thanks-pr-template.example
- .. literalinclude:: ../src/b4/templates/thanks-am-template.example
+ Default: ``None``
- Default: ``None``
+ :term:`b4.thanks-am-template`
+ Full paths to the templates to use when generating thank-you messages
+ for contributors. Take the following as example content for this file:
-``b4.thanks-commit-url-mask``
- Used when creating summaries for ``b4 ty``, and can be a value like::
+ .. literalinclude:: ../src/b4/templates/thanks-am-template.example
- thanks-commit-url-mask = https://git.kernel.org/username/c/%.12s
+ Default: ``None``
- If not set, b4 falls back to using commit hashes.
+ :term:`b4.thanks-commit-url-mask`
+ Used when creating summaries for ``b4 ty``, and can be a value like::
- .. note::
+ thanks-commit-url-mask = https://git.kernel.org/username/c/%.12s
- See this page for more info on convenient git.kernel.org short URLs:
- https://korg.docs.kernel.org/git-url-shorteners.html
+ If not set, b4 falls back to using commit hashes.
- Default: ``None``
+ .. note::
-``b4.thanks-from-name``
- The name to use in the ``From:`` header when sending thank-you notes.
- By default, b4 uses ``user.name``. For example::
+ See this page for more info on convenient git.kernel.org short URLs:
+ https://korg.docs.kernel.org/git-url-shorteners.html
- thanks-from-name = Project Foo Thanks Bot
+ Default: ``None``
- Default: ``None``
+ :term:`b4.thanks-from-name`
+ The name to use in the ``From:`` header when sending thank-you notes.
+ By default, b4 uses ``user.name``. For example::
- .. versionadded:: v0.13
+ thanks-from-name = Project Foo Thanks Bot
-``b4.thanks-from-email``
- The email to use in the ``From:`` header when sending thank-you notes.
- By default, b4 uses ``user.email``. For example::
+ Default: ``None``
- thanks-from-email = thanks-bot@example.com
+ .. versionadded:: v0.13
- Default: ``None``
+ :term:`b4.thanks-from-email`
+ The email to use in the ``From:`` header when sending thank-you notes.
+ By default, b4 uses ``user.email``. For example::
- .. versionadded:: v0.13
+ thanks-from-email = thanks-bot@example.com
-``b4.thanks-treename``
- Name of the tree to use in the thank-you templates.
+ Default: ``None``
- Default: ``None``
+ .. versionadded:: v0.13
-``b4.email-exclude``
- A list of addresses to always exclude from the message recipients.
- Expects a comma-separated list with shell-style globbing. E.g.::
+ :term:`b4.thanks-treename`
+ Name of the tree to use in the thank-you templates.
- email-exclude = *@codeaurora.org, *@obsolete.example.com
+ Default: ``None``
- Default: ``None``
+ :term:`b4.email-exclude`
+ A list of addresses to always exclude from the message recipients.
+ Expects a comma-separated list with shell-style globbing. E.g.::
-``b4.sendemail-identity``
- The ``sendemail`` identity to use when sending mail directly with b4.
- This setting applies to ``b4 send`` and ``b4 ty``. See `man
- git-send-email <https://git-scm.com/docs/git-send-email>`__ for info about
- sendemail identities.
+ email-exclude = *@codeaurora.org, *@obsolete.example.com
- Default: ``None``
+ Default: ``None``
-``b4.ty-send-email``
- When set, tells ``b4 ty`` to send email directly instead of writing
- out ``.thanks`` files.
+ :term:`b4.sendemail-identity`
+ The ``sendemail`` identity to use when sending mail directly with b4.
+ This setting applies to ``b4 send`` and ``b4 ty``. See `man
+ git-send-email <https://git-scm.com/docs/git-send-email>`__ for info about
- Default: ``no``
+ Default: ``None``
- .. versionadded:: v0.11
+ :term:`b4.ty-send-email`
+ When set, tells ``b4 ty`` to send email directly instead of writing
+ out ``.thanks`` files.
+
+ Default: ``no``
+
+ .. versionadded:: v0.11
.. _patchwork_settings:
@@ -331,175 +339,182 @@ Patchwork integration settings
If your project uses a patchwork server, setting these allows you to
integrate your b4 workflow with patchwork.
-``b4.pw-url``
- The URL of your patchwork server. Note, that this should point at the
- top-level of your patchwork installation and **not** at the project patch
- listing. For example::
+.. glossary::
- pw-url = https://patchwork.kernel.org/
+ :term:`b4.pw-url`
+ The URL of your patchwork server. Note, that this should point at the
+ top-level of your patchwork installation and **not** at the project patch
+ listing. For example::
- Default: ``None``
+ pw-url = https://patchwork.kernel.org/
-``b4.pw-key``
- The API key from your user profile to use when authenticating with the
- patchwork server.
+ Default: ``None``
- Default: ``None``
+ :term:`b4.pw-key`
+ The API key from your user profile to use when authenticating with the
+ patchwork server.
-``b4.pw-project``
- The name of the patchwork project, exactly as seen in the URL
- sub-path. For example::
+ Default: ``None``
- pw-project = linux-usb
+ :term:`b4.pw-project`
+ The name of the patchwork project, exactly as seen in the URL
+ sub-path. For example::
- Default: ``None``
+ pw-project = linux-usb
-``b4.pw-review-state``
- Enabling this option makes ``b4 am`` or ``b4 shazam`` automatically set
- the review status of the retrieved patches. For example::
+ Default: ``None``
- pw-review-state = under-review
+ :term:`b4.pw-review-state`
+ Enabling this option makes ``b4 am`` or ``b4 shazam`` automatically set
+ the review status of the retrieved patches. For example::
- Default: ``None``
+ pw-review-state = under-review
-``b4.pw-accept-state``
- Enabling this option makes ``b4 ty`` set the status of any applied patches
- to the specified state. For example::
+ Default: ``None``
- pw-accept-state = accepted
+ :term:`b4.pw-accept-state`
+ Enabling this option makes ``b4 ty`` set the status of any applied patches
+ to the specified state. For example::
- Default: ``None``
+ pw-accept-state = accepted
-``b4.pw-discard-state``
- Enabling this option makes ``b4 ty -d`` set the status of any matching
- patches to the specified state. For example::
+ Default: ``None``
- pw-discard-state = rejected
+ :term:`b4.pw-discard-state`
+ Enabling this option makes ``b4 ty -d`` set the status of any matching
+ patches to the specified state. For example::
- Default: ``None``
+ pw-discard-state = rejected
+
+ Default: ``None``
.. _contributor_settings:
Contributor-oriented settings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-``b4.send-endpoint-web``
- The web submission endpoint to use. See :ref:`web_endpoint`.
+.. glossary::
- Default: ``None``
+ :term:`b4.send-endpoint-web`
+ The web submission endpoint to use. See :ref:`web_endpoint`.
-``b4.send-series-to``
- A comma-separated list of addresses to always add to the "To:" header.
- See :ref:`prep_recipients`.
+ Default: ``None``
- Default: ``None``
+ :term:`b4.send-series-to`
+ A comma-separated list of addresses to always add to the "To:" header.
+ See :ref:`prep_recipients`.
-``b4.send-series-cc``
- A comma-separated list of addresses to always add to the "Cc:" header.
- See :ref:`prep_recipients`.
+ Default: ``None``
- Default: ``None``
+ :term:`b4.send-series-cc`
+ A comma-separated list of addresses to always add to the "Cc:" header.
+ See :ref:`prep_recipients`.
-``b4.send-no-patatt-sign``
- Instructs b4 not to sign patches with patatt before sending them. Note, that
- using the web submission endpoint requires using signed patches.
+ Default: ``None``
- Default: ``no``
+ :term:`b4.send-no-patatt-sign`
+ Instructs b4 not to sign patches with patatt before sending them. Note, that
+ using the web submission endpoint requires using signed patches.
-``b4.send-auto-to-cmd``
- The command to use for obtaining the list of "To:" recipients. The command is
- run once for each patch in the series. Each patch file is piped through
- stdin. If b4 finds ``scripts/get_maintainer.pl`` at the top of your git tree,
- it uses the command shown below by default.
+ Default: ``no``
- Default: ``scripts/get_maintainer.pl --nogit --nogit-fallback --nogit-chief-penguins --norolestats --nol``
+ :term:`b4.send-auto-to-cmd`
+ The command to use for obtaining the list of "To:" recipients. The command is
+ run once for each patch in the series. Each patch file is piped through
+ stdin. If b4 finds ``scripts/get_maintainer.pl`` at the top of your git tree,
+ it uses the command shown below by default.
-``b4.send-auto-cc-cmd``
- The command to use for obtaining the list of "Cc:" recipients. The command is
- run once for each patch in the series. Each patch file is piped through
- stdin. If b4 finds ``scripts/get_maintainer.pl`` at the top of your git tree,
- it uses the command shown below by default.
+ Default: ``scripts/get_maintainer.pl --nogit --nogit-fallback --nogit-chief-penguins --norolestats --nol``
- Default: ``scripts/get_maintainer.pl --nogit --nogit-fallback --nogit-chief-penguins --norolestats --nom``
+ :term:`b4.send-auto-cc-cmd`
+ The command to use for obtaining the list of "Cc:" recipients. The command is
+ run once for each patch in the series. Each patch file is piped through
+ stdin. If b4 finds ``scripts/get_maintainer.pl`` at the top of your git tree,
+ it uses the command shown below by default.
-``b4.send-same-thread``
- When sending a new version of a series, send it in the same thread as
- the previous version. The config supports the following values:
+ Default: ``scripts/get_maintainer.pl --nogit --nogit-fallback --nogit-chief-penguins --norolestats --nom``
- * ``yes``, ``true``, ``y``: B4 sends the first message of the new series as a
- reply to the previous version's cover letter.
- * ``shallow``: B4 sends the first message of the new series as a reply to the
- first version's cover letter.
- * ``no``: B4 does not send the new version of the series in the same thread
- as any previous version.
+ :term:`b4.send-same-thread`
+ When sending a new version of a series, send it in the same thread as
+ the previous version. The config supports the following values:
- Default: ``no``
+ * ``yes``, ``true``, ``y``: B4 sends the first message of the new series as a
+ reply to the previous version's cover letter.
+ * ``shallow``: B4 sends the first message of the new series as a reply to the
+ first version's cover letter.
+ * ``no``: B4 does not send the new version of the series in the same thread
+ as any previous version.
- .. versionadded:: v0.13
+ Default: ``no``
- .. versionchanged:: v0.15
- Added ``shallow`` config value.
+ .. versionadded:: v0.13
-``b4.prep-cover-strategy``
- Alternative cover letter storage strategy to use, in case you don't
- want to use the default ``commit`` strategy. See
- :ref:`prep_cover_strategies`.
+ .. versionchanged:: v0.15
+ Added ``shallow`` config value.
- Default: ``commit``
+ :term:`b4.prep-cover-strategy`
+ Alternative cover letter storage strategy to use, in case you don't
+ want to use the default ``commit`` strategy. See
+ :ref:`prep_cover_strategies`.
-``b4.prep-cover-template``
- Path to the template to use for the cover letter. The template supports the
- following tokens:
+ Default: ``commit``
- * ``${cover}``: the content of the cover letter itself
- * ``${shortlog}``: the ``git shortlog`` output for the series
- * ``${diffstat}``: the ``git diff --stat`` output for the series
- * ``${range_diff}``: the ``git range-diff`` output against the previous revision of the series
- * ``${base_commit}``: the base commit of the series
- * ``${change_id}``: the change-id of the series
- * ``${signature}``: your signature, either from ``~/.signature`` if found, or from your Git config
+ :term:`b4.prep-cover-template`
+ Path to the template to use for the cover letter. The template supports the
+ following tokens:
- Default: ``None``
+ * ``${cover}``: the content of the cover letter itself
+ * ``${shortlog}``: the ``git shortlog`` output for the series
+ * ``${diffstat}``: the ``git diff --stat`` output for the series
+ * ``${range_diff}``: the ``git range-diff`` output against the previous revision of the series
+ * ``${base_commit}``: the base commit of the series
+ * ``${change_id}``: the change-id of the series
+ * ``${signature}``: your signature, either from ``~/.signature`` if found, or from your Git config
-``b4.send-prefixes``
- Extra prefixes to add to ``[PATCH]`` (e.g. ``RFC mydrv``).
+ Default: ``None``
- This setting can be replaced for a series with ``b4 prep --set-prefixes``.
+ :term:`b4.send-prefixes`
+ Extra prefixes to add to ``[PATCH]`` (e.g. ``RFC mydrv``).
- Default: ``None``
+ This setting can be replaced for a series with ``b4 prep --set-prefixes``.
- .. versionadded:: v0.11
+ Default: ``None``
-``b4.prep-perpatch-check-cmd``
- The command to use when running ``--check``. The command is run once for each
- patch to check. The patch file to check is piped through stdin. If this
- config is defined multiple times, all commands will be run. If this config is
- not defined and b4 finds ``scripts/checkpatch.pl`` at the top of your git
- tree, it uses the command shown below by default.
+ .. versionadded:: v0.11
- Default: ``./scripts/checkpatch.pl -q --terse --no-summary --mailback --showfile``
+ :term:`b4.prep-perpatch-check-cmd`
+ The command to use when running ``--check``. The command is run once for each
+ patch to check. The patch file to check is piped through stdin. If this
+ config is defined multiple times, all commands will be run. If this config is
+ not defined and b4 finds ``scripts/checkpatch.pl`` at the top of your git
+ tree, it uses the command shown below by default.
- .. versionadded:: v0.14
+ Default: ``./scripts/checkpatch.pl -q --terse --no-summary --mailback --showfile``
-``b4.prep-pre-flight-checks``
- You can use this to turn off some or all pre-flight checks that b4 runs
- prior to sending out patches. To cancel all checks::
+ .. versionadded:: v0.14
- [b4]
- prep-pre-flight-checks = disable-all
+ :term:`b4.prep-pre-flight-checks`
+ You can use this to turn off some or all pre-flight checks that b4 runs
+ prior to sending out patches. To cancel all checks::
- To turn off specific checks, list each one of them, separated by
- comma::
+ [b4]
+ prep-pre-flight-checks = disable-all
- [b4]
- prep-pre-flight-checks = disable-needs-auto-to-cc, needs-checking
+ To turn off specific checks, list each one of them, separated by
+ comma::
- .. versionadded:: v0.14
+ [b4]
+ prep-pre-flight-checks = disable-needs-auto-to-cc, needs-checking
+
+ .. versionadded:: v0.14
To document
-----------
-``b4.gh-api-key``
- Deliberately undocumented because the feature is incomplete and poorly
- tested.
+
+.. glossary::
+
+ :term:`b4.gh-api-key`
+ Deliberately undocumented because the feature is incomplete and poorly
+ tested.
.. _`patatt`: https://pypi.org/project/patatt/
--
2.52.0
^ permalink raw reply related [flat|nested] 25+ messages in thread* [PATCH b4 19/21] docs: config: sort glossaries
2026-02-03 13:30 [PATCH b4 00/21] docs: various fixes + migration from definition lists to glossaries for config settings Quentin Schulz
` (17 preceding siblings ...)
2026-02-03 13:31 ` [PATCH b4 18/21] docs: config: migrate definition lists to glossaries Quentin Schulz
@ 2026-02-03 13:31 ` Quentin Schulz
2026-02-03 13:31 ` [PATCH b4 20/21] docs: cross-reference config options with :term: Quentin Schulz
` (3 subsequent siblings)
22 siblings, 0 replies; 25+ messages in thread
From: Quentin Schulz @ 2026-02-03 13:31 UTC (permalink / raw)
To: Kernel.org Tools; +Cc: Konstantin Ryabitsev, Quentin Schulz
From: Quentin Schulz <quentin.schulz@cherry.de>
This sorts the term defined in glossaries such that they appear
alphabetically in the docs.
Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
docs/config.rst | 324 +++++++++++++++++++++++++++++---------------------------
1 file changed, 166 insertions(+), 158 deletions(-)
diff --git a/docs/config.rst b/docs/config.rst
index cd205fd..f2ed519 100644
--- a/docs/config.rst
+++ b/docs/config.rst
@@ -39,12 +39,14 @@ Core options
These options control many of the core features of b4.
.. glossary::
+ :sorted:
- :term:`b4.midmask`
- Specifies the server from where to retrieve the messages specified by
- their message-id.
+ :term:`b4.cache-expire`
+ B4 caches retrieved threads for 10 minutes. This option allows
+ tweaking the time that the cache remains valid. Many commands also
+ allow a ``--no-cache`` flag to force b4 to perform remote lookups.
- Default: ``https://lore.kernel.org/%s``
+ Default: ``10``
:term:`b4.linkmask`
B4 uses this setting to construct the URL in the ``Link:`` trailers.
@@ -53,13 +55,6 @@ These options control many of the core features of b4.
Default: ``https://lore.kernel.org/%s``
- :term:`b4.searchmask`
- B4 uses this setting to query and retrieve threads matching specific
- search terms. For example, it can retrieve trailer updates using the
- series ``change-id`` identifier.
-
- Default: ``https://lore.kernel.org/all/?x=m&t=1&q=%s``
-
:term:`b4.linktrailermask`
Overrides the format of the ``Link:`` trailer, in case you want to
call it something other than "Link". For example, some projects
@@ -87,6 +82,12 @@ These options control many of the core features of b4.
Default: ``*.feeds.kernel.org, *.linux.dev,*.kernel.org,*``
+ :term:`b4.midmask`
+ Specifies the server from where to retrieve the messages specified by
+ their message-id.
+
+ Default: ``https://lore.kernel.org/%s``
+
:term:`b4.save-maildirs`
The "mbox" file format is actually several incompatible standards,
such as "mboxo" vs. "mboxrd". Setting this option can avoid potential
@@ -94,6 +95,13 @@ These options control many of the core features of b4.
Default: ``no``
+ :term:`b4.searchmask`
+ B4 uses this setting to query and retrieve threads matching specific
+ search terms. For example, it can retrieve trailer updates using the
+ series ``change-id`` identifier.
+
+ Default: ``https://lore.kernel.org/all/?x=m&t=1&q=%s``
+
:term:`b4.trailer-order`
This lets you control the order of trailers that get added to your own
custody section of the commit message. By default, b4 applies these
@@ -135,13 +143,6 @@ These options control many of the core features of b4.
Default: ``None``
- :term:`b4.cache-expire`
- B4 caches retrieved threads for 10 minutes. This option allows
- tweaking the time that the cache remains valid. Many commands also
- allow a ``--no-cache`` flag to force b4 to perform remote lookups.
-
- Default: ``10``
-
.. _shazam_settings:
``am`` and ``shazam`` settings
@@ -149,6 +150,18 @@ These options control many of the core features of b4.
These settings control ``b4 am`` and ``b4 shazam`` behavior.
.. glossary::
+ :sorted:
+
+ :term:`b4.am-perpatch-check-cmd`
+ The command to use when running ``--check``. The command is run once for each
+ patch to check. The patch file to check is piped through stdin. If this
+ config is defined multiple times, all commands will be run. If this config is
+ not defined and b4 finds ``scripts/checkpatch.pl`` at the top of your git
+ tree, it uses the command shown below by default.
+
+ Default: ``./scripts/checkpatch.pl -q --terse --no-summary --mailback``
+
+ .. versionadded:: v0.14
:term:`b4.shazam-am-flags`
Additional flags to pass to ``git am`` when applying patches.
@@ -169,34 +182,13 @@ These settings control ``b4 am`` and ``b4 shazam`` behavior.
Default: ``None``
- :term:`b4.am-perpatch-check-cmd`
- The command to use when running ``--check``. The command is run once for each
- patch to check. The patch file to check is piped through stdin. If this
- config is defined multiple times, all commands will be run. If this config is
- not defined and b4 finds ``scripts/checkpatch.pl`` at the top of your git
- tree, it uses the command shown below by default.
-
- Default: ``./scripts/checkpatch.pl -q --terse --no-summary --mailback``
-
- .. versionadded:: v0.14
-
.. _attestation_settings:
Attestation settings
~~~~~~~~~~~~~~~~~~~~
.. glossary::
-
- :term:`b4.attestation-policy`
- B4 supports domain-level and end-to-end attestation of patches using
- the `patatt`_ library. There are four different operation modes:
-
- * ``off``: don't bother checking attestation at all
- * ``softfail``: print green marks when attestation is passing and
- red marks when it's failing
- * ``hardfail``: exit with an error when any attestation checks fail
-
- Default: ``softfail``
+ :sorted:
:term:`b4.attestation-check-dkim`
Controls whether to perform DKIM attestation checks.
@@ -214,6 +206,23 @@ Attestation settings
.. versionadded:: v0.14
+ :term:`b4.attestation-gnupghome`
+ Sets ``GNUPGHOME`` before running PGP attestation checks that rely on
+ GnuPG.
+
+ Default: ``None``
+
+ :term:`b4.attestation-policy`
+ B4 supports domain-level and end-to-end attestation of patches using
+ the `patatt`_ library. There are four different operation modes:
+
+ * ``off``: don't bother checking attestation at all
+ * ``softfail``: print green marks when attestation is passing and
+ red marks when it's failing
+ * ``hardfail``: exit with an error when any attestation checks fail
+
+ Default: ``softfail``
+
:term:`b4.attestation-staleness-days`
Ignore attestation signatures that are more than this many days
old. This helps avoid a class of attacks when someone re-sends old
@@ -221,12 +230,6 @@ Attestation settings
Default: ``30``
- :term:`b4.attestation-gnupghome`
- Sets ``GNUPGHOME`` before running PGP attestation checks that rely on
- GnuPG.
-
- Default: ``None``
-
:term:`b4.gpgbin`
Full path to a different binary to use for ``gpg``. B4 also checks the
``gpg.program`` setting, and uses that value, if found.
@@ -253,12 +256,21 @@ Attestation settings
~~~~~~~~~~~~~~~
.. glossary::
+ :sorted:
- :term:`b4.thanks-pr-template`
- Full paths to the templates to use when generating thank-you messages
- for contributors. Take the following as example content for this file:
+ :term:`b4.email-exclude`
+ A list of addresses to always exclude from the message recipients.
+ Expects a comma-separated list with shell-style globbing. E.g.::
- .. literalinclude:: ../src/b4/templates/thanks-pr-template.example
+ email-exclude = *@codeaurora.org, *@obsolete.example.com
+
+ Default: ``None``
+
+ :term:`b4.sendemail-identity`
+ The ``sendemail`` identity to use when sending mail directly with b4.
+ This setting applies to ``b4 send`` and ``b4 ty``. See `man
+ git-send-email <https://git-scm.com/docs/git-send-email>`__ for info about
+ sendemail identities.
Default: ``None``
@@ -284,16 +296,6 @@ Attestation settings
Default: ``None``
- :term:`b4.thanks-from-name`
- The name to use in the ``From:`` header when sending thank-you notes.
- By default, b4 uses ``user.name``. For example::
-
- thanks-from-name = Project Foo Thanks Bot
-
- Default: ``None``
-
- .. versionadded:: v0.13
-
:term:`b4.thanks-from-email`
The email to use in the ``From:`` header when sending thank-you notes.
By default, b4 uses ``user.email``. For example::
@@ -304,26 +306,29 @@ Attestation settings
.. versionadded:: v0.13
+ :term:`b4.thanks-from-name`
+ The name to use in the ``From:`` header when sending thank-you notes.
+ By default, b4 uses ``user.name``. For example::
+
+ thanks-from-name = Project Foo Thanks Bot
+
+ Default: ``None``
+
+ .. versionadded:: v0.13
+
+ :term:`b4.thanks-pr-template`
+ Full paths to the templates to use when generating thank-you messages
+ for contributors. Take the following as example content for this file:
+
+ .. literalinclude:: ../src/b4/templates/thanks-pr-template.example
+
+ Default: ``None``
+
:term:`b4.thanks-treename`
Name of the tree to use in the thank-you templates.
Default: ``None``
- :term:`b4.email-exclude`
- A list of addresses to always exclude from the message recipients.
- Expects a comma-separated list with shell-style globbing. E.g.::
-
- email-exclude = *@codeaurora.org, *@obsolete.example.com
-
- Default: ``None``
-
- :term:`b4.sendemail-identity`
- The ``sendemail`` identity to use when sending mail directly with b4.
- This setting applies to ``b4 send`` and ``b4 ty``. See `man
- git-send-email <https://git-scm.com/docs/git-send-email>`__ for info about
-
- Default: ``None``
-
:term:`b4.ty-send-email`
When set, tells ``b4 ty`` to send email directly instead of writing
out ``.thanks`` files.
@@ -340,13 +345,21 @@ If your project uses a patchwork server, setting these allows you to
integrate your b4 workflow with patchwork.
.. glossary::
+ :sorted:
- :term:`b4.pw-url`
- The URL of your patchwork server. Note, that this should point at the
- top-level of your patchwork installation and **not** at the project patch
- listing. For example::
+ :term:`b4.pw-accept-state`
+ Enabling this option makes ``b4 ty`` set the status of any applied patches
+ to the specified state. For example::
- pw-url = https://patchwork.kernel.org/
+ pw-accept-state = accepted
+
+ Default: ``None``
+
+ :term:`b4.pw-discard-state`
+ Enabling this option makes ``b4 ty -d`` set the status of any matching
+ patches to the specified state. For example::
+
+ pw-discard-state = rejected
Default: ``None``
@@ -372,19 +385,12 @@ integrate your b4 workflow with patchwork.
Default: ``None``
- :term:`b4.pw-accept-state`
- Enabling this option makes ``b4 ty`` set the status of any applied patches
- to the specified state. For example::
+ :term:`b4.pw-url`
+ The URL of your patchwork server. Note, that this should point at the
+ top-level of your patchwork installation and **not** at the project patch
+ listing. For example::
- pw-accept-state = accepted
-
- Default: ``None``
-
- :term:`b4.pw-discard-state`
- Enabling this option makes ``b4 ty -d`` set the status of any matching
- patches to the specified state. For example::
-
- pw-discard-state = rejected
+ pw-url = https://patchwork.kernel.org/
Default: ``None``
@@ -394,63 +400,7 @@ Contributor-oriented settings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. glossary::
-
- :term:`b4.send-endpoint-web`
- The web submission endpoint to use. See :ref:`web_endpoint`.
-
- Default: ``None``
-
- :term:`b4.send-series-to`
- A comma-separated list of addresses to always add to the "To:" header.
- See :ref:`prep_recipients`.
-
- Default: ``None``
-
- :term:`b4.send-series-cc`
- A comma-separated list of addresses to always add to the "Cc:" header.
- See :ref:`prep_recipients`.
-
- Default: ``None``
-
- :term:`b4.send-no-patatt-sign`
- Instructs b4 not to sign patches with patatt before sending them. Note, that
- using the web submission endpoint requires using signed patches.
-
- Default: ``no``
-
- :term:`b4.send-auto-to-cmd`
- The command to use for obtaining the list of "To:" recipients. The command is
- run once for each patch in the series. Each patch file is piped through
- stdin. If b4 finds ``scripts/get_maintainer.pl`` at the top of your git tree,
- it uses the command shown below by default.
-
- Default: ``scripts/get_maintainer.pl --nogit --nogit-fallback --nogit-chief-penguins --norolestats --nol``
-
- :term:`b4.send-auto-cc-cmd`
- The command to use for obtaining the list of "Cc:" recipients. The command is
- run once for each patch in the series. Each patch file is piped through
- stdin. If b4 finds ``scripts/get_maintainer.pl`` at the top of your git tree,
- it uses the command shown below by default.
-
- Default: ``scripts/get_maintainer.pl --nogit --nogit-fallback --nogit-chief-penguins --norolestats --nom``
-
- :term:`b4.send-same-thread`
- When sending a new version of a series, send it in the same thread as
- the previous version. The config supports the following values:
-
- * ``yes``, ``true``, ``y``: B4 sends the first message of the new series as a
- reply to the previous version's cover letter.
- * ``shallow``: B4 sends the first message of the new series as a reply to the
- first version's cover letter.
- * ``no``: B4 does not send the new version of the series in the same thread
- as any previous version.
-
- Default: ``no``
-
- .. versionadded:: v0.13
-
- .. versionchanged:: v0.15
- Added ``shallow`` config value.
+ :sorted:
:term:`b4.prep-cover-strategy`
Alternative cover letter storage strategy to use, in case you don't
@@ -473,15 +423,6 @@ Contributor-oriented settings
Default: ``None``
- :term:`b4.send-prefixes`
- Extra prefixes to add to ``[PATCH]`` (e.g. ``RFC mydrv``).
-
- This setting can be replaced for a series with ``b4 prep --set-prefixes``.
-
- Default: ``None``
-
- .. versionadded:: v0.11
-
:term:`b4.prep-perpatch-check-cmd`
The command to use when running ``--check``. The command is run once for each
patch to check. The patch file to check is piped through stdin. If this
@@ -508,10 +449,77 @@ Contributor-oriented settings
.. versionadded:: v0.14
+ :term:`b4.send-auto-cc-cmd`
+ The command to use for obtaining the list of "Cc:" recipients. The command is
+ run once for each patch in the series. Each patch file is piped through
+ stdin. If b4 finds ``scripts/get_maintainer.pl`` at the top of your git tree,
+ it uses the command shown below by default.
+
+ Default: ``scripts/get_maintainer.pl --nogit --nogit-fallback --nogit-chief-penguins --norolestats --nom``
+
+ :term:`b4.send-auto-to-cmd`
+ The command to use for obtaining the list of "To:" recipients. The command is
+ run once for each patch in the series. Each patch file is piped through
+ stdin. If b4 finds ``scripts/get_maintainer.pl`` at the top of your git tree,
+ it uses the command shown below by default.
+
+ Default: ``scripts/get_maintainer.pl --nogit --nogit-fallback --nogit-chief-penguins --norolestats --nol``
+
+ :term:`b4.send-endpoint-web`
+ The web submission endpoint to use. See :ref:`web_endpoint`.
+
+ Default: ``None``
+
+ :term:`b4.send-no-patatt-sign`
+ Instructs b4 not to sign patches with patatt before sending them. Note, that
+ using the web submission endpoint requires using signed patches.
+
+ Default: ``no``
+
+ :term:`b4.send-prefixes`
+ Extra prefixes to add to ``[PATCH]`` (e.g. ``RFC mydrv``).
+
+ This setting can be replaced for a series with ``b4 prep --set-prefixes``.
+
+ Default: ``None``
+
+ .. versionadded:: v0.11
+
+ :term:`b4.send-same-thread`
+ When sending a new version of a series, send it in the same thread as
+ the previous version. The config supports the following values:
+
+ * ``yes``, ``true``, ``y``: B4 sends the first message of the new series as a
+ reply to the previous version's cover letter.
+ * ``shallow``: B4 sends the first message of the new series as a reply to the
+ first version's cover letter.
+ * ``no``: B4 does not send the new version of the series in the same thread
+ as any previous version.
+
+ Default: ``no``
+
+ .. versionadded:: v0.13
+
+ .. versionchanged:: v0.15
+ Added ``shallow`` config value.
+
+ :term:`b4.send-series-cc`
+ A comma-separated list of addresses to always add to the "Cc:" header.
+ See :ref:`prep_recipients`.
+
+ Default: ``None``
+
+ :term:`b4.send-series-to`
+ A comma-separated list of addresses to always add to the "To:" header.
+ See :ref:`prep_recipients`.
+
+ Default: ``None``
+
To document
-----------
.. glossary::
+ :sorted:
:term:`b4.gh-api-key`
Deliberately undocumented because the feature is incomplete and poorly
--
2.52.0
^ permalink raw reply related [flat|nested] 25+ messages in thread* [PATCH b4 20/21] docs: cross-reference config options with :term:
2026-02-03 13:30 [PATCH b4 00/21] docs: various fixes + migration from definition lists to glossaries for config settings Quentin Schulz
` (18 preceding siblings ...)
2026-02-03 13:31 ` [PATCH b4 19/21] docs: config: sort glossaries Quentin Schulz
@ 2026-02-03 13:31 ` Quentin Schulz
2026-02-03 13:31 ` [PATCH b4 21/21] docs: maintainer: am-shazam: cross-reference b4.linkmask for --add-link Quentin Schulz
` (2 subsequent siblings)
22 siblings, 0 replies; 25+ messages in thread
From: Quentin Schulz @ 2026-02-03 13:31 UTC (permalink / raw)
To: Kernel.org Tools; +Cc: Konstantin Ryabitsev, Quentin Schulz
From: Quentin Schulz <quentin.schulz@cherry.de>
This inserts a link to the definition of the config option such that
it's either to find it.
Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
docs/config.rst | 2 +-
docs/contributor/prep.rst | 4 ++--
docs/contributor/send.rst | 6 +++---
docs/maintainer/am-shazam.rst | 2 +-
docs/maintainer/ty.rst | 4 ++--
5 files changed, 9 insertions(+), 9 deletions(-)
diff --git a/docs/config.rst b/docs/config.rst
index f2ed519..d2a80c2 100644
--- a/docs/config.rst
+++ b/docs/config.rst
@@ -28,7 +28,7 @@ file in the repository you're currently using.
Configuration options
---------------------
All settings are under the ``b4`` section. For example, to set the
-``b4.midmask`` option, add the following section to the relevant git
+:term:`b4.midmask` option, add the following section to the relevant git
config file::
[b4]
diff --git a/docs/contributor/prep.rst b/docs/contributor/prep.rst
index 9c27b64..e6b45c7 100644
--- a/docs/contributor/prep.rst
+++ b/docs/contributor/prep.rst
@@ -65,7 +65,7 @@ disadvantages in some less-common situations:
For this reason, b4 supports alternative strategies for storing the
cover letter. You can tell ``b4`` which strategy to use using the
-``b4.prep-cover-strategy`` configuration variable.
+:term:`b4.prep-cover-strategy` configuration variable.
``commit`` strategy (default)
This is the default strategy that keeps the cover letter and all
@@ -400,7 +400,7 @@ modifying defaults for some of these flags.
``./scripts/checkpatch.pl --terse --no-summary --mailback --showfile``
You can specify your own command by setting the
- ``b4.prep-perpatch-check-cmd`` configuration parameter. For example
+ :term:`b4.prep-perpatch-check-cmd` configuration parameter. For example
you can make it more strict::
[b4]
diff --git a/docs/contributor/send.rst b/docs/contributor/send.rst
index f5a1ff1..ba18ef5 100644
--- a/docs/contributor/send.rst
+++ b/docs/contributor/send.rst
@@ -311,13 +311,13 @@ Command line flags
``--to``
Additional email addresses to include into the To: header. Separate
multiple entries with a comma. You can also set this in the
- configuration file using the ``b4.send-series-to`` option (see
+ configuration file using the :term:`b4.send-series-to` option (see
:ref:`contributor_settings`).
``--cc``
Additional email addresses to include into the Cc: header. Separate
multiple entries with a comma. You can also set this in the
- configuration file using the ``b4.send-series-cc`` option (see
+ configuration file using the :term:`b4.send-series-cc` option (see
:ref:`contributor_settings`).
``--not-me-too``
@@ -328,7 +328,7 @@ Command line flags
Note, that sending via the web submission endpoint requires
cryptographic signatures at all times, so this is only a valid option
to use with ``-o`` or when using your own SMTP server. This can be set
- in the configuration using the ``b4.send-no-patatt-sign`` (see
+ in the configuration using the :term:`b4.send-no-patatt-sign` (see
:ref:`contributor_settings`).
``--resend V``
diff --git a/docs/maintainer/am-shazam.rst b/docs/maintainer/am-shazam.rst
index 1ca9b50..5c3fb75 100644
--- a/docs/maintainer/am-shazam.rst
+++ b/docs/maintainer/am-shazam.rst
@@ -175,7 +175,7 @@ The following flags are common to both commands:
./scripts/checkpatch.pl -q --terse --no-summary --mailback
You can specify a different command to run by setting the
- ``b4.am-perpatch-check-cmd`` configuration setting, e.g.::
+ :term:`b4.am-perpatch-check-cmd` configuration setting, e.g.::
[b4]
am-perpatch-check-cmd = ./scripts/checkpatch.pl -q --terse --no-summary --mailback --strict
diff --git a/docs/maintainer/ty.rst b/docs/maintainer/ty.rst
index 21c56de..c1b79b5 100644
--- a/docs/maintainer/ty.rst
+++ b/docs/maintainer/ty.rst
@@ -66,7 +66,7 @@ happy with the results, you can omit the ``--dry-run`` switch to
actually send the mail.
If you want ``b4 ty`` to always send mail, you can make the ``-S``
-switch permanent by setting the ``b4.ty-send-email`` config variable to
+switch permanent by setting the :term:`b4.ty-send-email` config variable to
``yes``.
Editing the templates
@@ -74,7 +74,7 @@ Editing the templates
You can edit the default templates that are provided with b4 to
customize the thank-you message. Once you have your own versions, you
can specify the path to the template to use via the
-``b4.thanks-am-template`` and ``b4.thanks-pr-template`` configuration
+:term:`b4.thanks-am-template` and :term:`b4.thanks-pr-template` configuration
parameters. See :ref:`ty_settings` for details.
Optional flags
--
2.52.0
^ permalink raw reply related [flat|nested] 25+ messages in thread* [PATCH b4 21/21] docs: maintainer: am-shazam: cross-reference b4.linkmask for --add-link
2026-02-03 13:30 [PATCH b4 00/21] docs: various fixes + migration from definition lists to glossaries for config settings Quentin Schulz
` (19 preceding siblings ...)
2026-02-03 13:31 ` [PATCH b4 20/21] docs: cross-reference config options with :term: Quentin Schulz
@ 2026-02-03 13:31 ` Quentin Schulz
2026-02-03 22:00 ` [PATCH b4 00/21] docs: various fixes + migration from definition lists to glossaries for config settings Konstantin Ryabitsev
2026-02-24 17:02 ` Konstantin Ryabitsev
22 siblings, 0 replies; 25+ messages in thread
From: Quentin Schulz @ 2026-02-03 13:31 UTC (permalink / raw)
To: Kernel.org Tools; +Cc: Konstantin Ryabitsev, Quentin Schulz
From: Quentin Schulz <quentin.schulz@cherry.de>
The --add-link boolean option will be using the linkmask b4 setting so
let's make that clear how to specify a different template.
Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
docs/maintainer/am-shazam.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/maintainer/am-shazam.rst b/docs/maintainer/am-shazam.rst
index 5c3fb75..54b6fc4 100644
--- a/docs/maintainer/am-shazam.rst
+++ b/docs/maintainer/am-shazam.rst
@@ -115,7 +115,7 @@ The following flags are common to both commands:
``-l, --add-link``
Adds a ``Link:`` trailer with the URL of the retrieved message using
- the ``linkmask`` template.
+ the :term:`b4.linkmask` template.
``-i, --add-message-id``
Adds a ``Message-ID:`` trailer with the Message-ID of the retrieved
--
2.52.0
^ permalink raw reply related [flat|nested] 25+ messages in thread* Re: [PATCH b4 00/21] docs: various fixes + migration from definition lists to glossaries for config settings
2026-02-03 13:30 [PATCH b4 00/21] docs: various fixes + migration from definition lists to glossaries for config settings Quentin Schulz
` (20 preceding siblings ...)
2026-02-03 13:31 ` [PATCH b4 21/21] docs: maintainer: am-shazam: cross-reference b4.linkmask for --add-link Quentin Schulz
@ 2026-02-03 22:00 ` Konstantin Ryabitsev
2026-02-09 11:09 ` Quentin Schulz
2026-02-24 17:02 ` Konstantin Ryabitsev
22 siblings, 1 reply; 25+ messages in thread
From: Konstantin Ryabitsev @ 2026-02-03 22:00 UTC (permalink / raw)
To: Quentin Schulz; +Cc: Kernel.org Tools, Konstantin Ryabitsev, Quentin Schulz
On Tue, 03 Feb 2026 14:30:59 +0100, Quentin Schulz <foss+kernel@0leil.net> wrote:
> This makes use of rST version admonitions for config settings in
> anticipation to make each config setting a term such that we can
> cross-reference them easily and have an anchor in the output for easier
> link sharing. Then it migrates current "verbatim cross-references" to
> actual cross-references using :term:.
Great work, thank you for sending that in. I'm holding off on this only
because I want to try merging it using the new review ui, to test the
full review-merge-thanks cycle.
I noticed that there is no attestation on your patches, not even a DKIM
signature. Do you mind setting that up -- this is probably not the last
series you're sending in.
> Note: ``b4 send`` seems to be picking up
> ``Signed-off-by: Your Name <your.name@example.com>`` from the git
> context in patch 11 and adds it to Cc recipients for some reason??
Hm... definitely a bug that I'll look into. I also see it added to the
CC list, so you probably got a bounce for that as well.
Thanks!
--
KR
^ permalink raw reply [flat|nested] 25+ messages in thread* Re: [PATCH b4 00/21] docs: various fixes + migration from definition lists to glossaries for config settings
2026-02-03 22:00 ` [PATCH b4 00/21] docs: various fixes + migration from definition lists to glossaries for config settings Konstantin Ryabitsev
@ 2026-02-09 11:09 ` Quentin Schulz
0 siblings, 0 replies; 25+ messages in thread
From: Quentin Schulz @ 2026-02-09 11:09 UTC (permalink / raw)
To: Konstantin Ryabitsev, Quentin Schulz; +Cc: Kernel.org Tools
Hi Konstantin,
On 2/3/26 11:00 PM, Konstantin Ryabitsev wrote:
> On Tue, 03 Feb 2026 14:30:59 +0100, Quentin Schulz <foss+kernel@0leil.net> wrote:
>> This makes use of rST version admonitions for config settings in
>> anticipation to make each config setting a term such that we can
>> cross-reference them easily and have an anchor in the output for easier
>> link sharing. Then it migrates current "verbatim cross-references" to
>> actual cross-references using :term:.
>
> Great work, thank you for sending that in. I'm holding off on this only
> because I want to try merging it using the new review ui, to test the
> full review-merge-thanks cycle.
>
Ack.
> I noticed that there is no attestation on your patches, not even a DKIM
> signature. Do you mind setting that up -- this is probably not the last
> series you're sending in.
>
Not the first even ;)
I should have fixed this oversight now. Would you rather have a v2 or a
RESEND for the added DKIM signature?
>> Note: ``b4 send`` seems to be picking up
>> ``Signed-off-by: Your Name <your.name@example.com>`` from the git
>> context in patch 11 and adds it to Cc recipients for some reason??
>
> Hm... definitely a bug that I'll look into. I also see it added to the
> CC list, so you probably got a bounce for that as well.
>
Do you want a separate mail thread on the ML such that one can do a
Closes: in a commit log fixing it? (I vaguely remember something about a
"bugspray" tool?)
Cheers,
Quentin
^ permalink raw reply [flat|nested] 25+ messages in thread
* Re: [PATCH b4 00/21] docs: various fixes + migration from definition lists to glossaries for config settings
2026-02-03 13:30 [PATCH b4 00/21] docs: various fixes + migration from definition lists to glossaries for config settings Quentin Schulz
` (21 preceding siblings ...)
2026-02-03 22:00 ` [PATCH b4 00/21] docs: various fixes + migration from definition lists to glossaries for config settings Konstantin Ryabitsev
@ 2026-02-24 17:02 ` Konstantin Ryabitsev
22 siblings, 0 replies; 25+ messages in thread
From: Konstantin Ryabitsev @ 2026-02-24 17:02 UTC (permalink / raw)
To: Kernel.org Tools, Quentin Schulz; +Cc: Quentin Schulz
On Tue, 03 Feb 2026 14:30:59 +0100, Quentin Schulz wrote:
> docs: various fixes + migration from definition lists to glossaries for config settings
>
> This makes use of rST version admonitions for config settings in
> anticipation to make each config setting a term such that we can
> cross-reference them easily and have an anchor in the output for easier
> link sharing. Then it migrates current "verbatim cross-references" to
> actual cross-references using :term:.
>
> [...]
Applied, thanks!
[01/21] docs: maintainer: ty: fix incorrect config name for templates
commit: 075798a3853e6e36ef24579162cfa57b4f68bee5
[02/21] docs: prep: add info on when range-diff-opts was added
commit: ba986b23bf5c9cd3639d8755e2beec47e0e6ab9c
[03/21] docs: diff: add info on when range-diff-opts was added
commit: 8decfc81783cc755227d4a3ac2eedd636ce15be8
[04/21] docs: contributor: send: fix sendmail typo
commit: b1102e55390db0c37b55817726fb4063a2d77c0b
[05/21] docs: config: separate b4.thanks-pr-template and b4.thanks-am-template
commit: 6d5ea09b1afb9696bb51a843ac45c74a6ab2daed
[06/21] docs: use rST version admonitions for command options
commit: 787d38ea47cfb368a5ce3495b1b7c0cf283b27a8
[07/21] docs: use versionadded admonition for sections
commit: 516b83309278457d93844433d8f091e08cc734d5
[08/21] docs: maintainer: use deprecated admonition
commit: 1e8781aa3877549865a60f39d298e124b47ad361
[09/21] docs: config: provide link to git-config conf file documentation
commit: e1478411056d6af9b00efa520ee6f6f23bbe0523
[10/21] docs: config: fix discrepancy between example strings
commit: e0c3dd312f323f2c12e4ca6959f501bb52641c4d
[11/21] docs: move sentence-ending dots from within the last quoted string to outside
commit: 1f2991f5fd6f824b977a6be72224b31f8ee3437d
[12/21] docs: config: add missing dot at end of sentence
commit: 78f186e0059ec161456e78dc90c1bd18dde6410b
[13/21] docs: config: provide link to patatt
commit: 7e2ada10d95412b18022a5ffad6b433845d70f62
[14/21] docs: config: provide link to git-send-email manpage
commit: ce6d1d94581750993add06994765ea7b23df1e8c
[15/21] docs: config: fix double colon typo
commit: 21c51381472723a5e10c09501efe13f7ae999e53
[16/21] docs: config: provide example content for template files
commit: bd9fe265c68a6608d6f481c0a142d34e37c6b66b
[17/21] docs: config: use rST version admonitions
commit: dd516611af3944c0ea24e897f8aafbf524aff5f8
[18/21] docs: config: migrate definition lists to glossaries
commit: c7feb0050730d911dffdee65c8c89589cb0f8ec2
[19/21] docs: config: sort glossaries
commit: af1c83586198f595223873d0bb1c6ac67f4f560d
[20/21] docs: cross-reference config options with :term:
commit: f3863312bb98adf0ce179e105cb673eed82e8cd9
[21/21] docs: maintainer: am-shazam: cross-reference b4.linkmask for --add-link
commit: 00c1aa82af335d1c1aa2cb881d50f3f4ffee4dcd
Best regards,
--
KR
^ permalink raw reply [flat|nested] 25+ messages in thread