Re: [PATCH 1/2] docs: Fix botched rST conversion of 'submitting-a-patch.rst'

[Thomas Huth <thuth@redhat.com>]

On 19/11/2021 20.31, Kashyap Chamarthy wrote:
> I completely botched up the merged[0] rST conversion of this document by
> accidentally dropping entire hunks (!) of text. :-(  I made it very hard
> for reviewers to spot it, as the omitted text was buried deep in the
> document.  To fix my hatchet job, I reconverted the "SubmitAPatch"
> wiki[1] page from scratch and replaced the existing rST with it, while
> making sure I incorporated previous feedback.

Thanks for the quick update! I've now tripple-checked the differences 
between the old wiki page and the new rst page, and I think with some 
additional small changes on top (which I will do while picking up your 
patch, see below), we should be fine now.

[...]
> @@ -55,16 +55,15 @@ Writing your Patches
>   Use the QEMU coding style
>   ~~~~~~~~~~~~~~~~~~~~~~~~~
>   
> -You can run run *scripts/checkpatch.pl <patchfile>* before submitting to
> -check that you are in compliance with our coding standards. Be aware
> -that ``checkpatch.pl`` is not infallible, though, especially where C
> +You can run run *scripts/checkpatch.pl <patch file>* before submitting
> +to check that you are in compliance with our coding standards. Be aware
> +that checkpatch.pl is not infallible, though, especially where C
>   preprocessor macros are involved; use some common sense too. See also:
>   
> -- `QEMU Coding Style
> -  <https://qemu-project.gitlab.io/qemu/devel/style.html>`__
> -
> +-  `QEMU Coding Style <https://qemu-project.gitlab.io/qemu/devel/style.html>`__

While we're at it, I'll replace the link with an internal link when picking 
up this patch (so that it can also be used in offline documentation).

>   -  `Automate a checkpatch run on
> -   commit <http://blog.vmsplice.net/2011/03/how-to-automatically-run-checkpatchpl.html>`__
> +   commit <https://blog.vmsplice.net/2011/03/how-to-automatically-run-checkpatchpl.html>`__
> +-  Spell check your patches

I'll add the link to https://wiki.qemu.org/Contribute/SpellCheck again.

> @@ -85,7 +91,7 @@ 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
> +```git bisect`` <http://git-scm.com/docs/git-bisect>`__ without hitting

You've re-introduced the broken git-bisect link. I'll fix it again.

> @@ -170,11 +175,74 @@ displays the subject line some distance apart (that is, a body that
>   starts with "... so that" as a continuation of the subject line is
>   harder to follow).
>   
> +If your patch fixes a commit that is already in the repository, please
> +add a line with "Fixes: ("Fixed commit subject")" below the patch

Missing the "<at-least-12-digits-of-SHA-commit-id>" from the Wiki page. I'll 
add it.

> +description / before your "Signed-off-by:" line in the commit message.
> +
> +If your patch fixes a bug in the gitlab bug tracker, please add a line
> +with "Resolves: " to the commit message, too. Gitlab can close bugs

Missing the "<URL-of-the-bug>" from the Wiki. I'll add it.

> +automatically once commits with the "Resolved:" keyword get merged into
> +the master branch of the project. And if your patch addresses a bug in
> +another public bug tracker, you can also use a line with "Buglink: " for

dito.

> @@ -223,13 +291,22 @@ use --numbered so the cover and the patch have distinct subject lines).

I noticed that the --numbered will be translated into –numbered, so I'll add 
some `` quotes here.

> @@ -288,6 +370,18 @@ it's best to:
>      of the patchset you're looking for review on, and why reviewers
>      should care
>   
> +.. _consider_whether_your_patch_is_applicable_for_stable:
> +
> +Consider whether your patch is applicable for stable
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +If your patch fixes a severe issue or a regression, it may be applicable
> +for stable. In that case, consider adding ``Cc: qemu-stable@nongnu.org``
> +to your patch to notify the stable maintainers.
> +
> +For more details on how QEMU's stable process works, refer to
> +`docs/devel/stable-process.rst <https://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/devel/stable-process.rst;hb=HEAD>`__.

While at this, I'll also replace this external link with an internal one.

>   Is my patch in?
>   ~~~~~~~~~~~~~~~
>   
> +QEMU has some Continuous Integration machines that try to catch patch
> +submission problems as soon as possible.  `patchew
> +<http://patchew.org/QEMU/>`__ includes a web interface for tracking the
> +status of various threads that have been posted to the list, and may
> +send you an automated mail if it detected a problem with your patch.
> +
>   Once your patch has had enough review on list, the maintainer for that
>   area of code will send notification to the list that they are including
>   your patch in a particular staging branch. Periodically, the maintainer
>   then sends a `pull request
>   <https://qemu-project.gitlab.io/qemu/devel/submitting-a-pull-request.html>`__

I'll also use an internal link for this reference here.

> -for aggregating topic branches into mainline qemu. Generally, you do not
> +for aggregating topic branches into mainline QEMU. Generally, you do not
>   need to send a pull request unless you have contributed enough patches
>   to become a maintainer over a particular section of code. Maintainers
>   may further modify your commit, by resolving simple merge conflicts or

  Thomas