[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [PATCH v3 3/3] docs: rSTify the "SubmitAPatch" wiki

From: Thomas Huth
Subject: Re: [PATCH v3 3/3] docs: rSTify the "SubmitAPatch" wiki
Date: Wed, 17 Nov 2021 10:08:52 +0100
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101 Thunderbird/91.3.0

On 10/11/2021 15.49, Kashyap Chamarthy wrote:
- The original wiki is here[1]. I copied the wiki source[2] into a .wiki
   file, and used `pandoc` to convert it to rST:

     $> pandoc -f Mediawiki -t rst submitting-a-patch.wiki -o

- The only minor touch-ups I did was to fix URLs.  But 99%, it is a 1-1

   (An example of a "touch-up": under the section "Patch emails must
   include a Signed-off-by: line", I updated the "see SubmittingPatches
   1.12"  to "1.12) Sign your work")

- I have also converted a couple other related wiki pages (included in
   this patch series) that were hyperlinked within the SubmitAPatch page,
   or a page that it refers to:

   - SubmitAPullRequest: https://wiki.qemu.org/Contribute/SubmitAPullRequest
   - TrivialPatches: https://wiki.qemu.org/Contribute/TrivialPatches

- Over time, many people contributed to this wiki page; you can find all
   the authors in the wiki history[3].

[1] https://wiki.qemu.org/Contribute/SubmitAPatch
[2] http://wiki.qemu.org/index.php?title=Contribute/SubmitAPatch&action=edit
[3] http://wiki.qemu.org/index.php?title=Contribute/SubmitAPatch&action=history

Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com>
  docs/devel/index.rst              |   1 +
  docs/devel/submitting-a-patch.rst | 456 ++++++++++++++++++++++++++++++
  2 files changed, 457 insertions(+)
  create mode 100644 docs/devel/submitting-a-patch.rst

diff --git a/docs/devel/index.rst b/docs/devel/index.rst
index 816eb7b7b0..c3cfa9e41f 100644
--- a/docs/devel/index.rst
+++ b/docs/devel/index.rst
@@ -47,3 +47,4 @@ modifying QEMU's source code.
+   submitting-a-patch

I'd suggest to insert this before the pull-request entry, in case anybody reads the manual sequentially, it might be better to learn about the patch submission process first before reading about pull requests.
(I can fix this up when picking up the patch, no need to resend)

diff --git a/docs/devel/submitting-a-patch.rst 
new file mode 100644
index 0000000000..c80dad47fa
--- /dev/null
+++ b/docs/devel/submitting-a-patch.rst
+Split up long patches
+Split up longer patches into a patch series of logical code changes.
+Each change should compile and execute successfully. For instance, don't
+add a file to the makefile in patch one and then add the file itself in
+patch two. (This rule is here so that people can later use tools like
+```git bisect`` <http://git-scm.com/docs/git-bisect>`__ without hitting

That hyperlink showed up in the rendered output. I'll fix it up by removing the "``" quotes.

+.. _write_a_meaningful_commit_message:
+Write a meaningful commit message
+Commit messages should be meaningful and should stand on their own as a
+historical record of why the changes you applied were necessary or
+QEMU follows the usual standard for git commit messages: the first line
+(which becomes the email subject line) is "subsystem: single line
+summary of change". Whether the "single line summary of change" starts
+with a capital is a matter of taste, but we prefer that the summary does
+not end in ".".

That ".". looks a little bit weird in the output ... maybe we should replace it with "does not end with a dot." ?

Look at ``git shortlog -30`` for an idea of sample
+subject lines. Then there is a blank line and a more detailed
+description of the patch, another blank and your Signed-off-by: line.
+Please do not use lines that are longer than 76 characters in your
+commit message (so that the text still shows up nicely with "git show"
+in a 80-columns terminal window).
+The body of the commit message is a good place to document why your
+change is important. Don't include comments like "This is a suggestion
+for fixing this bug" (they can go below the "---" line in the email so

That --- gets translated into a — character ... I'll replace the "---" with ``---`` to fix it.


reply via email to

[Prev in Thread] Current Thread [Next in Thread]