From b0e74a9f5d37d5f16372617fe8f404b24a56ddd2 Mon Sep 17 00:00:00 2001 From: Alyssa Ross Date: Sat, 11 Feb 2023 14:56:51 +0000 Subject: Documentation: move "Working with Patches" under "Contributing" This is all information about how to contribute to Spectrum, so I think it makes more sense here than under "Development". Signed-off-by: Alyssa Ross Message-Id: <20230211145650.740649-1-hi@alyssa.is> --- Documentation/contributing/b4.adoc | 51 +++++++++++ .../contributing/building-documentation.adoc | 4 +- Documentation/contributing/communication.adoc | 2 +- Documentation/contributing/first-patch.adoc | 100 +++++++++++++++++++++ Documentation/contributing/index.adoc | 6 +- Documentation/contributing/replying.adoc | 27 ++++++ Documentation/contributing/reviewing-patches.adoc | 22 +++++ Documentation/contributing/testing-patches.adoc | 76 ++++++++++++++++ .../contributing/working-with-patches.adoc | 12 +++ .../contributing/writing_documentation.adoc | 2 +- Documentation/development/b4.adoc | 51 ----------- Documentation/development/first-patch.adoc | 100 --------------------- Documentation/development/replying.adoc | 27 ------ Documentation/development/reviewing-patches.adoc | 22 ----- Documentation/development/testing-patches.adoc | 76 ---------------- .../development/working-with-patches.adoc | 12 --- 16 files changed, 295 insertions(+), 295 deletions(-) create mode 100644 Documentation/contributing/b4.adoc create mode 100644 Documentation/contributing/first-patch.adoc create mode 100644 Documentation/contributing/replying.adoc create mode 100644 Documentation/contributing/reviewing-patches.adoc create mode 100644 Documentation/contributing/testing-patches.adoc create mode 100644 Documentation/contributing/working-with-patches.adoc delete mode 100644 Documentation/development/b4.adoc delete mode 100644 Documentation/development/first-patch.adoc delete mode 100644 Documentation/development/replying.adoc delete mode 100644 Documentation/development/reviewing-patches.adoc delete mode 100644 Documentation/development/testing-patches.adoc delete mode 100644 Documentation/development/working-with-patches.adoc 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 +// 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. diff --git a/Documentation/contributing/building-documentation.adoc b/Documentation/contributing/building-documentation.adoc index 63a3038..1beffa8 100644 --- a/Documentation/contributing/building-documentation.adoc +++ b/Documentation/contributing/building-documentation.adoc @@ -1,6 +1,6 @@ = Building Documentation :page-parent: Contributing -:page-nav_order: 3 +:page-nav_order: 4 // SPDX-FileCopyrightText: 2022 Unikie // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 @@ -49,4 +49,4 @@ modify any of those, or add new ones, run `scripts/build.sh` again to do a full rebuild of the site. After making changes to the documentation, see how to -xref:../development/first-patch.adoc[send your patch] and submit the changes for review. +xref:first-patch.adoc[send your patch] and submit the changes for review. diff --git a/Documentation/contributing/communication.adoc b/Documentation/contributing/communication.adoc index bb8aeb9..9344cdf 100644 --- a/Documentation/contributing/communication.adoc +++ b/Documentation/contributing/communication.adoc @@ -81,7 +81,7 @@ and where patches are sent. There is a separate guide for the Spectrum development process, including how patches are sent to this list and discussed. For more information, see -xref:../development/working-with-patches.adoc[Working with Patches]. +xref:working-with-patches.adoc[Working with Patches]. You can subscribe xref:https://spectrum-os.org/lists/mailman3/lists/devel.spectrum-os.org/[on the web], or by sending mail to *devel-subscribe@spectrum-os.org*. diff --git a/Documentation/contributing/first-patch.adoc b/Documentation/contributing/first-patch.adoc new file mode 100644 index 0000000..13efa33 --- /dev/null +++ b/Documentation/contributing/first-patch.adoc @@ -0,0 +1,100 @@ += Sending Your Patch +:page-parent: Working with Patches +:page-grand_parent: Contributing +:page-nav_order: 1 + +// SPDX-FileCopyrightText: 2022 Unikie +// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 + +This tutorial assumes that you already have basic +https://git-scm.com/[git] experience. + +Before beginning, you'll need to have a local git checkout of the +https://spectrum-os.org/git/[Spectrum source tree]. You'll also need +to have configured `git send-email` — a guide for this can be found at +https://git-send-email.io/. + +== Making Changes + +The process of making changes is similar to working on any git repository. + +. Create a branch for your changes: ++ +[source,shell] +---- +git checkout -b fix-docs # for example +---- +. Make changes in your editor. +. Stage and commit your changes: ++ +[source,shell] +---- +git add Documentation/first-patch.adoc # for example +git commit -s +---- ++ +TIP: The `-s` option adds a `Signed-off-by` line to the commit. This +indicates your acceptance of the +https://spectrum-os.org/git/spectrum/tree/DCO-1.1.txt[Developer's +Certificate of Origin], which is mandatory for Spectrum patches. + +== Submitting Changes + +Once you're happy with how the commits on your branch look, run: + +[source,shell] +---- +git send-email --to devel@spectrum-os.org --confirm=always origin/main +---- + +For each message, you will be prompted for confirmation, and then the +change will be submitted to the Spectrum development mailing list. +They will appear shortly on the +https://spectrum-os.org/lists/hyperkitty/list/devel@spectrum-os.org/[web +interface]. + +[#cover-letter] +TIP: If you're submitting multiple changes, and you'd like to provide +an overall description for the whole series, you can add the +`--compose` option, which will prompt you to compose a "cover letter" +message that will be sent before all of your patches. + +== Feedback + +Once your patch has been submitted, wait for it to be reviewed. +Feedback, if any, will be sent as email replies to your submitted +patch. You can respond to feedback in your mail client. + +Use the *Reply All* button to sent your messages to the +mailing list as well as to the person who sent the feedback. + +If you need to make changes to your patch and submit a new version, +use https://git-rebase.io/[`git rebase`] to create a new version of +your patch(es) and then submit it like this: + +[source,shell] +---- +git send-email -v2 --to devel@spectrum-os.org --confirm=always origin/main +---- + +The added `-v2` flag indicates that this is version two of your +patch set. If your patches require more rounds of changes, submit +subsequent rounds with `-v3`, `-v4`, etc. as appropriate. + +If you would like to describe what has changed from the previous version +of your patches, you can do so in a xref:cover-letter[cover letter] +as described above. + +== Acceptance + +Once your patch has been accepted, it will be applied to the upstream +Spectrum git repository. You will receive an automated email +confirmation when this happens. + +== Questions + +If you have any questions about the patch submission process, you can +ask them either on the +https://spectrum-os.org/participating.html#spectrum-devel[development +mailing list], or in the +https://spectrum-os.org/participating.html#irc[IRC/Matrix channel]. diff --git a/Documentation/contributing/index.adoc b/Documentation/contributing/index.adoc index 4be8d69..48255d8 100644 --- a/Documentation/contributing/index.adoc +++ b/Documentation/contributing/index.adoc @@ -24,7 +24,7 @@ If you have made changes you would like to be included in the official Spectrum distribution, please send patches to the spectrum-devel mailing list (devel@spectrum-os.org). For more information, see -xref:../development/working-with-patches.adoc[Working with Patches]. +xref:working-with-patches.adoc[Working with Patches]. Sending patches to the list is easy — you can do it with Git, straight from the command line. You do not have to set anything up @@ -60,7 +60,7 @@ this style of collaboration can be compared to the alternatives. If you notice something that can be fixed or improved: -. xref:https://spectrum-os.org/doc/development/first-patch.html#making-changes[Edit or add any relevant documentation]. +. xref:first-patch.html#making-changes[Edit or add any relevant documentation]. + TIP: Make sure your changes are formatted correctly and consistently with the rest of the documentation. For information on writing guidelines, @@ -68,7 +68,7 @@ see xref:../contributing/writing_documentation.adoc[Documentation Style Guide]. + . xref:../contributing/building-documentation.adoc[Test your documentation]. Reread what you wrote and run a spellchecker on it to make sure you did not miss anything. -. xref:https://spectrum-os.org/doc/development/first-patch.html#submitting-changes[Submit changes]. +. xref:first-patch.html#submitting-changes[Submit changes]. === Documentation To-Do List diff --git a/Documentation/contributing/replying.adoc b/Documentation/contributing/replying.adoc new file mode 100644 index 0000000..63fbba8 --- /dev/null +++ b/Documentation/contributing/replying.adoc @@ -0,0 +1,27 @@ += Replying to Messages in the Mailing List Archives +:page-parent: Working with Patches +:page-grand_parent: Contributing +:page-nav_order: 3 + +// SPDX-FileCopyrightText: 2022 Alyssa Ross +// 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]. + +Make sure to Reply All when replying to messages, so that the message +is sent to the mailing list and not just to the person you reply to. + +== Getting a copy of a message + +You may want to reply to a mailing list message that you do not have a +copy of in your mail client, because you are not 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 All to +it as normal. diff --git a/Documentation/contributing/reviewing-patches.adoc b/Documentation/contributing/reviewing-patches.adoc new file mode 100644 index 0000000..2f7b0fc --- /dev/null +++ b/Documentation/contributing/reviewing-patches.adoc @@ -0,0 +1,22 @@ += Reviewing Patches +:page-parent: Working with Patches +:page-grand_parent: Contributing +:page-nav_order: 2 + +// SPDX-FileCopyrightText: 2022 Alyssa Ross +// 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 + +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/contributing/testing-patches.adoc b/Documentation/contributing/testing-patches.adoc new file mode 100644 index 0000000..f76f873 --- /dev/null +++ b/Documentation/contributing/testing-patches.adoc @@ -0,0 +1,76 @@ += Testing Patches +:page-parent: Working with Patches +:page-grand_parent: Contributing +:page-nav_order: 2 + +// SPDX-FileCopyrightText: 2022 Alyssa Ross +// SPDX-FileCopyrightText: 2022 Unikie +// 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 Patch + +. 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 checkout of the https://spectrum-os.org/git/spectrum[Spectrum] + git repository, run `nix-shell` to enter a shell environment with b4 + set up correctly for Spectrum. ++ +TIP: You can manually xref:b4.adoc[set up b4] so that it works outside +of the Spectrum root's nix-shell, which allows you to skip this step. +. 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 `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 Results + +When you tested a patch, it is 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 +---- + +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. diff --git a/Documentation/contributing/working-with-patches.adoc b/Documentation/contributing/working-with-patches.adoc new file mode 100644 index 0000000..dfd4ed5 --- /dev/null +++ b/Documentation/contributing/working-with-patches.adoc @@ -0,0 +1,12 @@ += Working with Patches +:page-parent: Contributing +:page-nav_order: 2 +:page-has_children: true + +// SPDX-FileCopyrightText: 2022 Unikie +// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 + +Patches are the way for contributors to submit code to the Spectrum project. + +Make sure to xref:b4.adoc[install and configure the b4 utility] for +applying and testing other people's patches. diff --git a/Documentation/contributing/writing_documentation.adoc b/Documentation/contributing/writing_documentation.adoc index a58da64..f8a69ef 100644 --- a/Documentation/contributing/writing_documentation.adoc +++ b/Documentation/contributing/writing_documentation.adoc @@ -1,6 +1,6 @@ = Documentation Style Guide :description: Channels, announcements and so on. -:page-nav_order: 2 +:page-nav_order: 3 :page-parent: Contributing // SPDX-FileCopyrightText: 2023 Unikie diff --git a/Documentation/development/b4.adoc b/Documentation/development/b4.adoc deleted file mode 100644 index 5f141e9..0000000 --- a/Documentation/development/b4.adoc +++ /dev/null @@ -1,51 +0,0 @@ -= Installing and Configuring b4 -:page-parent: Working with Patches -:page-grand_parent: Development -:page-nav_order: 1 - -// SPDX-FileCopyrightText: 2022 Alyssa Ross -// 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. diff --git a/Documentation/development/first-patch.adoc b/Documentation/development/first-patch.adoc deleted file mode 100644 index aa6ebee..0000000 --- a/Documentation/development/first-patch.adoc +++ /dev/null @@ -1,100 +0,0 @@ -= Sending Your Patch -:page-parent: Working with Patches -:page-grand_parent: Development -:page-nav_order: 1 - -// SPDX-FileCopyrightText: 2022 Unikie -// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 - -This tutorial assumes that you already have basic -https://git-scm.com/[git] experience. - -Before beginning, you'll need to have a local git checkout of the -https://spectrum-os.org/git/[Spectrum source tree]. You'll also need -to have configured `git send-email` — a guide for this can be found at -https://git-send-email.io/. - -== Making Changes - -The process of making changes is similar to working on any git repository. - -. Create a branch for your changes: -+ -[source,shell] ----- -git checkout -b fix-docs # for example ----- -. Make changes in your editor. -. Stage and commit your changes: -+ -[source,shell] ----- -git add Documentation/first-patch.adoc # for example -git commit -s ----- -+ -TIP: The `-s` option adds a `Signed-off-by` line to the commit. This -indicates your acceptance of the -https://spectrum-os.org/git/spectrum/tree/DCO-1.1.txt[Developer's -Certificate of Origin], which is mandatory for Spectrum patches. - -== Submitting Changes - -Once you're happy with how the commits on your branch look, run: - -[source,shell] ----- -git send-email --to devel@spectrum-os.org --confirm=always origin/main ----- - -For each message, you will be prompted for confirmation, and then the -change will be submitted to the Spectrum development mailing list. -They will appear shortly on the -https://spectrum-os.org/lists/hyperkitty/list/devel@spectrum-os.org/[web -interface]. - -[#cover-letter] -TIP: If you're submitting multiple changes, and you'd like to provide -an overall description for the whole series, you can add the -`--compose` option, which will prompt you to compose a "cover letter" -message that will be sent before all of your patches. - -== Feedback - -Once your patch has been submitted, wait for it to be reviewed. -Feedback, if any, will be sent as email replies to your submitted -patch. You can respond to feedback in your mail client. - -Use the *Reply All* button to sent your messages to the -mailing list as well as to the person who sent the feedback. - -If you need to make changes to your patch and submit a new version, -use https://git-rebase.io/[`git rebase`] to create a new version of -your patch(es) and then submit it like this: - -[source,shell] ----- -git send-email -v2 --to devel@spectrum-os.org --confirm=always origin/main ----- - -The added `-v2` flag indicates that this is version two of your -patch set. If your patches require more rounds of changes, submit -subsequent rounds with `-v3`, `-v4`, etc. as appropriate. - -If you would like to describe what has changed from the previous version -of your patches, you can do so in a xref:cover-letter[cover letter] -as described above. - -== Acceptance - -Once your patch has been accepted, it will be applied to the upstream -Spectrum git repository. You will receive an automated email -confirmation when this happens. - -== Questions - -If you have any questions about the patch submission process, you can -ask them either on the -https://spectrum-os.org/participating.html#spectrum-devel[development -mailing list], or in the -https://spectrum-os.org/participating.html#irc[IRC/Matrix channel]. diff --git a/Documentation/development/replying.adoc b/Documentation/development/replying.adoc deleted file mode 100644 index a1ad394..0000000 --- a/Documentation/development/replying.adoc +++ /dev/null @@ -1,27 +0,0 @@ -= Replying to Messages in the Mailing List Archives -:page-parent: Working with Patches -:page-grand_parent: Development -:page-nav_order: 3 - -// SPDX-FileCopyrightText: 2022 Alyssa Ross -// 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]. - -Make sure to Reply All when replying to messages, so that the message -is sent to the mailing list and not just to the person you reply to. - -== Getting a copy of a message - -You may want to reply to a mailing list message that you do not have a -copy of in your mail client, because you are not 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 All to -it as normal. diff --git a/Documentation/development/reviewing-patches.adoc b/Documentation/development/reviewing-patches.adoc deleted file mode 100644 index ba47f25..0000000 --- a/Documentation/development/reviewing-patches.adoc +++ /dev/null @@ -1,22 +0,0 @@ -= Reviewing Patches -:page-parent: Working with Patches -:page-grand_parent: Development -:page-nav_order: 2 - -// SPDX-FileCopyrightText: 2022 Alyssa Ross -// 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 - -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/development/testing-patches.adoc b/Documentation/development/testing-patches.adoc deleted file mode 100644 index 0c72c93..0000000 --- a/Documentation/development/testing-patches.adoc +++ /dev/null @@ -1,76 +0,0 @@ -= Testing Patches -:page-parent: Working with Patches -:page-grand_parent: Development -:page-nav_order: 2 - -// SPDX-FileCopyrightText: 2022 Alyssa Ross -// SPDX-FileCopyrightText: 2022 Unikie -// 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 Patch - -. 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 checkout of the https://spectrum-os.org/git/spectrum[Spectrum] - git repository, run `nix-shell` to enter a shell environment with b4 - set up correctly for Spectrum. -+ -TIP: You can manually xref:b4.adoc[set up b4] so that it works outside -of the Spectrum root's nix-shell, which allows you to skip this step. -. 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 `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 Results - -When you tested a patch, it is 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 ----- - -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. diff --git a/Documentation/development/working-with-patches.adoc b/Documentation/development/working-with-patches.adoc deleted file mode 100644 index a2694ed..0000000 --- a/Documentation/development/working-with-patches.adoc +++ /dev/null @@ -1,12 +0,0 @@ -= Working with Patches -:page-parent: Development -:page-nav_order: 3 -:page-has_children: true - -// SPDX-FileCopyrightText: 2022 Unikie -// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 - -Patches are the way for contributors to submit code to the Spectrum project. - -Make sure to xref:../development/b4.adoc[install and configure the b4 utility] -for applying and testing other people's patches. -- cgit 1.4.1