1 files changed, 51 insertions, 0 deletions
diff --git a/Documentation/contributing/b4.adoc b/Documentation/contributing/b4.adoc
new file mode 100644
index 0000000..b41dc58
--- /dev/null
+++ b/Documentation/contributing/b4.adoc
@@ -0,0 +1,51 @@
+= Installing and Configuring b4
+:page-parent: Working with Patches
+:page-grand_parent: Contributing
+:page-nav_order: 1
+
+// SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
+// SPDX-FileCopyrightText: 2022 Unikie
+// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
+
+https://git.kernel.org/pub/scm/utils/b4/b4.git/about/[b4] is a utility
+for working with patches sent to a mailing list, such as
+https://spectrum-os.org/participating.html#spectrum-devel[devel@spectrum-os.org].
+
+NOTE: If you run `nix-shell` in the root of the Spectrum source tree,
+you'll be dropped into a development shell that has b4 set up
+correctly, and you don't need to do anything else.  You only need to
+configure it manually as described here if you want it to work outside
+of the Spectrum root's nix-shell.
+
+== Installing b4
+
+You should be able to install b4 from your package manager.
+
+Using Nix, you can start a shell with b4 available by running:
+
+[listing]
+[source,shell]
+nix-shell -p b4
+
+== Configuring b4
+
+As b4 was originally written for Linux development, it will default to
+searching for patches on the Linux mailing lists.  So to use it for
+Spectrum, it needs to be configured to search the Spectrum mailing
+lists instead.
+
+To do this, in a checkout of the appropriate git repository
+(https://spectrum-os.org/git/spectrum[Spectrum] or
+https://spectrum-os.org/git/nixpkgs[Spectrum Nixpkgs]), run:
+
+[listing]
+[source,shell]
+git config b4.midmask https://spectrum-os.org/lists/archives/spectrum-devel/%s
+
+From now on, any b4 command run in Spectrum repositories will search
+the Spectrum devel mailing list.
+
+== Using b4
+
+Using b4 to fetch and apply a patch from the Spectrum mailing list is
+described in the xref:testing-patches.adoc[Testing Patches] how-to guide.