diff options
| -rw-r--r-- | Documentation/b4.adoc | 41 | ||||
| -rw-r--r-- | Documentation/replying.adoc | 21 | ||||
| -rw-r--r-- | Documentation/reviewing-patches.adoc | 20 | ||||
| -rw-r--r-- | Documentation/testing-patches.adoc | 71 |
4 files changed, 153 insertions, 0 deletions
diff --git a/Documentation/b4.adoc b/Documentation/b4.adoc new file mode 100644 index 0000000..6e6c76f --- /dev/null +++ b/Documentation/b4.adoc @@ -0,0 +1,41 @@ += Installing and Configuring b4 +:page-parent: Tutorials + +// SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is> +// 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]. + +== 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 the https://spectrum-os.org/git/spectrum[Spectrum git +repository], 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 the Spectrum git repository 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. diff --git a/Documentation/replying.adoc b/Documentation/replying.adoc new file mode 100644 index 0000000..104cd9c --- /dev/null +++ b/Documentation/replying.adoc @@ -0,0 +1,21 @@ += Replying to Messages in the Mailing List Archives +:page-parent: Tutorials + +// SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is> +// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 + +Discussion of Spectrum takes place on +https://spectrum-os.org/participating.html#mailing-lists[mailing +lists]. + +You may want to reply to a mailing list message that you don't have a +copy of in your mail client, because you aren't subscribed to the +list, or because you subscribed after the message was sent. + +To do this, find the message you want to reply to in the +https://spectrum-os.org/lists/archives[public-inbox list archives], +click on the "reply" link at the bottom of the message, then click the +"mbox" link. Save the result to a file, then open it in your mail +client. This should import the message and allow you to reply to it +as normal. Remember to Reply All so that the masseg is sent to the +mailing list and not just to the person you're replying to. diff --git a/Documentation/reviewing-patches.adoc b/Documentation/reviewing-patches.adoc new file mode 100644 index 0000000..63ff24e --- /dev/null +++ b/Documentation/reviewing-patches.adoc @@ -0,0 +1,20 @@ += Reviewing Patches +:page-parent: How-to Guides + +// SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is> +// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 + +To review a patch posted to the +https://spectrum-os.org/participating.html#spectrum-devel[mailing +list], xref:replying.adoc[reply] to it with your feedback. + +If you believe the patch is acceptable and should be included in +Spectrum, include a line in your reply like this: + +[example] +[listing] +Reviewed-by: John Smith <john@example.com> + +This format is recognized by tooling, so any lines in this format in +patch replies will be automatically included in the commit message +when a patch is applied. diff --git a/Documentation/testing-patches.adoc b/Documentation/testing-patches.adoc new file mode 100644 index 0000000..1421637 --- /dev/null +++ b/Documentation/testing-patches.adoc @@ -0,0 +1,71 @@ += Testing Patches +:page-parent: How-to Guides + +// SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is> +// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 + +Potential changes to Spectrum are posted to and discussed on the +https://spectrum-os.org/participating.html#spectrum-devel[devel@spectrum-os.org] +mailing list. + +== Apply the patch + +If you haven't already, you'll first need to xref:b4.adoc[install and +configure] https://git.kernel.org/pub/scm/utils/b4/b4.git/about/[b4]. +Then: + +. Find the patch series you want to test on + https://spectrum-os.org/lists/archives/spectrum-devel/[public-inbox]. +. Navigate to the "permalink" page for any patch in the series. +. Copy the Message-Id for the patch, as shown on the permalink page, e.g. + \20220511092352.70E54C980@atuin.qyliss.net. +. In a copy of the https://spectrum-os.org/git/spectrum[Spectrum git + repository], Run `b4 am` with the patch's Message-Id to download all + the patches in the series into a file. ++ +[example] +[source,shell] +---- +b4 am 20220511092352.70E54C980@atuin.qyliss.net +---- + +. b4 will indicate the file name it has downloaded the patches into + with a line like: ++ +[example] +[listing] +Writing ./20220424_hi_host_rootfs_fix_weston_hotplugging.mbx ++ +Run `git am` on that file to apply the patches, for example: ++ +[example] +[source,shell] +---- +git am 20220424_hi_host_rootfs_fix_weston_hotplugging.mbx +---- + +== Post your test results + +When you've tested a patch, it's really helpful to +xref:replying.adoc[reply] with your test results. + +If the patch worked for you, please reply to it and include a line +like the following, separated from any reply text: + +---- +Tested-by: John Smith <john@example.com> +---- + +This format is recognized by tooling, so any lines in this format in +patch replies will be automatically included in the commit message +when a patch is applied. + +It's also helpful to explain in your reply how you tested the patch, +but you don't have to if it's obvious. (For example, if a patch is +supposed to fix a bug, and you verified that after applying the patch +the bug is fixed, just the Tested-by line on its own is enough to +indicate that.) + +If you found an issue with the patch, do not include a Tested-by line, +and instead reply to the patch explaining what you tested, what you +expected to happen, and what actually happened. |