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

[Thomas Huth <thuth@redhat.com>]

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
>         submitting-a-patch.rst
> 
> - The only minor touch-ups I did was to fix URLs.  But 99%, it is a 1-1
>    conversion.
> 
>    (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.
>      writing-qmp-commands
>      trivial-patches
>      submitting-a-pull-request
> +   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 b/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
> +useful.
> +
> +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.

  Thomas