patches and low-level development discussion
 help / color / mirror / code / Atom feed
From: Alyssa Ross <hi@alyssa.is>
To: devel@spectrum-os.org
Cc: Ville Ilvonen <ville.ilvonen@unikie.com>
Subject: [PATCH] Documentation: add "Sending your First Patch"
Date: Wed, 10 Aug 2022 12:54:06 +0000	[thread overview]
Message-ID: <20220810125405.1133177-1-hi@alyssa.is> (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
<https://spectrum-os.org/contributing.html>, but it doesn't really go
into any detail, and I think this belongs in the main documentation.

Signed-off-by: Alyssa Ross <hi@alyssa.is>
---
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 <https://spectrum-os.org/doc/reviewing-patches.html>. :)

 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
+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 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
+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:
+
+----
+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.  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 https://git-rebase.io/[`git rebase`] to create a new version of
+your patch(es), and submit it like this:
+
+----
+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'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
+https://spectrum-os.org/participating.html#spectrum-devel[development
+mailing list], or in the
+https://spectrum-os.org/participating.html#irc[IRC/Matrix channel].
-- 
2.35.1



             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:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

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

  git send-email \
    --in-reply-to=20220810125405.1133177-1-hi@alyssa.is \
    --to=hi@alyssa.is \
    --cc=devel@spectrum-os.org \
    --cc=ville.ilvonen@unikie.com \
    --subject='Re: [PATCH] Documentation: add "Sending your First Patch"' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* 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:

	https://spectrum-os.org/git/crosvm
	https://spectrum-os.org/git/doc
	https://spectrum-os.org/git/mktuntap
	https://spectrum-os.org/git/nixpkgs
	https://spectrum-os.org/git/spectrum
	https://spectrum-os.org/git/ucspi-vsock
	https://spectrum-os.org/git/www

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).