patches and low-level development discussion
 help / color / mirror / code / Atom feed
From: Alyssa Ross <>
Cc: Ville Ilvonen <>
Subject: [PATCH] Documentation: add "Sending your First Patch"
Date: Wed, 10 Aug 2022 12:54:06 +0000	[thread overview]
Message-ID: <> (raw)

I think having this written down in tutorial style is important, so
people can follow through some step by step instructions.  We already
have some similar documentation on
<>, but it doesn't really go
into any detail, and I think this belongs in the main documentation.

Signed-off-by: Alyssa Ross <>
Ville, I'm CCing you in case you'd like to review, since we talked about
documenting the patch workflow a bit better before.

We also have this small document about reviewing patches on the list now,
at <>. :)

 Documentation/first-patch.adoc | 96 ++++++++++++++++++++++++++++++++++
 1 file changed, 96 insertions(+)
 create mode 100644 Documentation/first-patch.adoc

diff --git a/Documentation/first-patch.adoc b/Documentation/first-patch.adoc
new file mode 100644
index 0000000..22140e4
--- /dev/null
+++ b/Documentation/first-patch.adoc
@@ -0,0 +1,96 @@
+= Sending Your First Patch
+:page-parent: Tutorials
+// SPDX-FileCopyrightText: 2022 Unikie
+// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
+== Prerequisites
+This tutorial assumes that you already have basic
+[git] experience.
+Before beginning, you'll need to have a local git checkout of the
+[Spectrum source tree].  You'll also need
+to have configured `git send-email` — a guide for this can be found at
+== Making your changes
+If you've worked on any git repository before, the process for making
+your changes will probably be very familiar.
+1. Create a branch for your changes:
+git checkout -b fix-docs # for example
+2. Make changes in your editor.
+3. Stage and commit your changes:
+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
+Certificate of Origin], which is mandatory for Spectrum patches.
+== Submitting changes
+Once you're happy with how the commits on your branch look, run:
+git send-email --to --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
+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.  Please use
+the Reply All button to ensure that your messages are sent 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[`git rebase`] to create a new version of
+your patch(es), and submit it like this:
+git send-email -v2 --to --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'd 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
+mailing list], or in the
+[IRC/Matrix channel].

             reply	other threads:[~2022-08-10 12:56 UTC|newest]

Thread overview: 2+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2022-08-10 12:54 Alyssa Ross [this message]
2022-08-11 14:40 ` Alyssa Ross

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \ \ \ \ \
    --subject='Re: [PATCH] Documentation: add "Sending your First Patch"' \

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

Code repositories for project(s) associated with this inbox:

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).