[PATCH 0/3] rSTify SubmitAPatch, TrivialPatches, and SpellCheck wiki pages

[PATCH 0/3] rSTify SubmitAPatch, TrivialPatches, and SpellCheck wiki pages

[Kashyap Chamarthy]

As of writing this, qemu.org is down, so I've used a one-month old
copy[1] of the wiki from 27Aug2021 to do the rST conversion.

My main motivation was to convert SubmitAPatch (when Peter Maydell
pointed out on IRC that it's still on the wiki).  But it links to a
couple more small wiki pages; so I converted them too:

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

[1] https://web.archive.org/web/20210827130706/https://wiki.qemu.org/Contribute/SubmitAPatch

Kashyap Chamarthy (3):
  docs: rSTify the "SpellCheck" wiki
  docs: rSTify the "TrivialPatches" wiki
  docs: rSTify the "SubmitAPatch" wiki

 docs/devel/spell-check.rst        |  29 ++
 docs/devel/submitting-a-patch.rst | 460 ++++++++++++++++++++++++++++++
 docs/devel/trivial-patches.rst    |  53 ++++
 3 files changed, 542 insertions(+)
 create mode 100644 docs/devel/spell-check.rst
 create mode 100644 docs/devel/submitting-a-patch.rst
 create mode 100644 docs/devel/trivial-patches.rst

-- 
2.31.1

[PATCH 1/3] docs: rSTify the "SpellCheck" wiki

[Kashyap Chamarthy]

The original wiki is here[1].  I converted by copying the wiki source[2]
into a .wiki file and convert to rST using `pandoc`:

    $ pandoc -f Mediawiki -t rst spell-check.wiki -o spell-check.rst

[1] https://wiki.qemu.org/Contribute/SpellCheck
[2] https://web.archive.org/web/20170721031029/http://wiki.qemu.org/index.php?title=Contribute/SubmitAPatch&action=edit

Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com>
---
 docs/devel/spell-check.rst | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)
 create mode 100644 docs/devel/spell-check.rst

diff --git a/docs/devel/spell-check.rst b/docs/devel/spell-check.rst
new file mode 100644
index 0000000000..998cd7ef51
--- /dev/null
+++ b/docs/devel/spell-check.rst
@@ -0,0 +1,29 @@
+===========
+Spell Check
+===========
+
+QEMU uses British or American English in code and documentation. There
+are some typical spelling bugs which can be easily avoided by using
+tools like codespell.
+
+codespell is a python script which detects (and optionally fixes) the
+most common spelling bugs.
+
+If you installed codespell in your HOME directory, it can be called from
+the QEMU source directory like this::
+
+    ~/bin/codespell.py -d -r -s -x scripts/codespell.exclude -q 2 ~/share/codespell/dictionary.txt
+
+``-x scripts/codespell.exclude`` excludes some known lines from the check
+and needs a file which is not yet committed.
+
+.. _external_links:
+
+External Links
+--------------
+
+-  http://packages.profusion.mobi/codespell/ (download)
+-  http://git.profusion.mobi/cgit.cgi/lucas/codespell/ (git repository)
+-  https://github.com/lucasdemarchi/codespell (alternate git repository)
+-  http://en.wikipedia.org/wiki/Wikipedia:Lists_of_common_misspellings/For_machines
+-  http://grammar.yourdictionary.com/spelling-and-word-lists/misspelled.html
-- 
2.31.1

Re: [PATCH 1/3] docs: rSTify the "SpellCheck" wiki

[Peter Maydell]

On Wed, 22 Sept 2021 at 13:11, Kashyap Chamarthy <kchamart@redhat.com> wrote:
>
> The original wiki is here[1].  I converted by copying the wiki source[2]
> into a .wiki file and convert to rST using `pandoc`:
>
>     $ pandoc -f Mediawiki -t rst spell-check.wiki -o spell-check.rst
>
> [1] https://wiki.qemu.org/Contribute/SpellCheck
> [2] https://web.archive.org/web/20170721031029/http://wiki.qemu.org/index.php?title=Contribute/SubmitAPatch&action=edit
>
> Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com>
> ---
>  docs/devel/spell-check.rst | 29 +++++++++++++++++++++++++++++
>  1 file changed, 29 insertions(+)
>  create mode 100644 docs/devel/spell-check.rst
>
> diff --git a/docs/devel/spell-check.rst b/docs/devel/spell-check.rst
> new file mode 100644
> index 0000000000..998cd7ef51
> --- /dev/null
> +++ b/docs/devel/spell-check.rst
> @@ -0,0 +1,29 @@
> +===========
> +Spell Check
> +===========
> +
> +QEMU uses British or American English in code and documentation. There
> +are some typical spelling bugs which can be easily avoided by using
> +tools like codespell.
> +
> +codespell is a python script which detects (and optionally fixes) the
> +most common spelling bugs.
> +
> +If you installed codespell in your HOME directory, it can be called from
> +the QEMU source directory like this::
> +
> +    ~/bin/codespell.py -d -r -s -x scripts/codespell.exclude -q 2 ~/share/codespell/dictionary.txt
> +
> +``-x scripts/codespell.exclude`` excludes some known lines from the check
> +and needs a file which is not yet committed.

This command doesn't actually work, because there is no
scripts/codespell.exclude in the source tree. It also
assumes you have a ~/share/codespell/dictionary.txt in your
home directory.

I think Stefan proposed a patch adding the excludelist file to
the source repository back when he wrote this wiki page a decade
ago, but it did not get through code review.

thanks
-- PMM

Re: [PATCH 1/3] docs: rSTify the "SpellCheck" wiki

[Kashyap Chamarthy]

On Wed, Sep 22, 2021 at 02:10:43PM +0100, Peter Maydell wrote:
> On Wed, 22 Sept 2021 at 13:11, Kashyap Chamarthy <kchamart@redhat.com> wrote:

[...]

> > +If you installed codespell in your HOME directory, it can be called from
> > +the QEMU source directory like this::
> > +
> > +    ~/bin/codespell.py -d -r -s -x scripts/codespell.exclude -q 2 ~/share/codespell/dictionary.txt
> > +
> > +``-x scripts/codespell.exclude`` excludes some known lines from the check
> > +and needs a file which is not yet committed.
> 
> This command doesn't actually work, because there is no
> scripts/codespell.exclude in the source tree. It also
> assumes you have a ~/share/codespell/dictionary.txt in your
> home directory.
> 
> I think Stefan proposed a patch adding the excludelist file to
> the source repository back when he wrote this wiki page a decade
> ago, but it did not get through code review.

Thanks for catching it.  I couldn't find the unmerged
'codespell.exclude' from my searches online.  I don't know if it still
makes sense to include such a file.  But regardless, 'codespell' is
useful on its own.  

In v2, I can nuke that command altogether, and link to the README of
upstream 'codespell':

    https://github.com/codespell-project/codespell

I'll also edit the paragraph that talks about installing the the tool in
$HOME directory -- it's no longer required; many major distros packaged
it.  At least Debian, Ubuntu, and Fedora do (as 'codespell'), and the
dictionary file gets installed under:

    $> rpm -ql codespell | grep dictionary
    /usr/lib/python3.9/site-packages/codespell_lib/data/dictionary.txt
    /usr/lib/python3.9/site-packages/codespell_lib/data/dictionary_code.txt
    /usr/lib/python3.9/site-packages/codespell_lib/data/dictionary_en-GB_to_en-US.txt
    /usr/lib/python3.9/site-packages/codespell_lib/data/dictionary_informal.txt
    /usr/lib/python3.9/site-packages/codespell_lib/data/dictionary_names.txt
    /usr/lib/python3.9/site-packages/codespell_lib/data/dictionary_rare.txt
    /usr/lib/python3.9/site-packages/codespell_lib/data/dictionary_usage.txt

I'll also link to 'my-spell' from Alex Bennée, for Emacs users: 
https://github.com/stsquad/my-emacs-stuff/blob/master/my-spell.el

-- 
/kashyap

[PATCH 2/3] docs: rSTify the "TrivialPatches" wiki

[Kashyap Chamarthy]

The original wiki is here[1].  I converted by copying the wiki source
into a .wiki file and convert to rST using `pandoc`:

        $ pandoc -f Mediawiki -t rst trivial-patches.wiki -o trivial-patches.rst

[1] https://wiki.qemu.org/Contribute/TrivialPatches

Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com>
---
 docs/devel/trivial-patches.rst | 53 ++++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)
 create mode 100644 docs/devel/trivial-patches.rst

diff --git a/docs/devel/trivial-patches.rst b/docs/devel/trivial-patches.rst
new file mode 100644
index 0000000000..4ad0d25b9d
--- /dev/null
+++ b/docs/devel/trivial-patches.rst
@@ -0,0 +1,53 @@
+===============
+Trivial Patches
+===============
+
+Overview
+========
+
+Trivial patches that change just a few lines of code sometimes languish
+on the mailing list even though they require only a small amount of
+review. This is often the case for patches that do not fall under an
+actively maintained subsystem and therefore fall through the cracks.
+
+The trivial patches team take on the task of reviewing and building pull
+requests for patches that:
+
+- Do not fall under an actively maintained subsystem.
+- Are single patches or short series (max 2-4 patches).
+- Only touch a few lines of code.
+
+**You should hint that your patch is a candidate by CCing
+qemu-trivial@nongnu.org.**
+
+Repositories
+============
+
+Since the trivial patch team rotates maintainership there is only one
+active repository at a time:
+
+- git://git.corpit.ru/qemu.git trivial-patches - `browse <http://git.corpit.ru/?p=qemu.git;a=shortlog;h=refs/heads/trivial-patches>`__
+- git://github.com/vivier/qemu.git trivial-patches - `browse <https://github.com/vivier/qemu/tree/trivial-patches>`__
+
+Workflow
+========
+
+The trivial patches team rotates the duty of collecting trivial patches
+amongst its members. A team member's job is to:
+
+1. Identify trivial patches on the development mailing list.
+2. Review trivial patches, merge them into a git tree, and reply to state
+   that the patch is queued.
+3. Send pull requests to the development mailing list once a week.
+
+A single team member can be on duty as long as they like. The suggested
+time is 1 week before handing off to the next member.
+
+Team
+====
+
+If you would like to join the trivial patches team, contact Michael
+Tokarev. The current team includes:
+
+- Michael Tokarev
+- `Laurent Vivier <mailto:laurent@vivier.eu>`__
-- 
2.31.1

Re: [PATCH 2/3] docs: rSTify the "TrivialPatches" wiki

[Philippe Mathieu-Daudé]

Hi Kashyap,

On 9/22/21 14:10, Kashyap Chamarthy wrote:
> The original wiki is here[1].  I converted by copying the wiki source
> into a .wiki file and convert to rST using `pandoc`:
> 
>          $ pandoc -f Mediawiki -t rst trivial-patches.wiki -o trivial-patches.rst
> 
> [1] https://wiki.qemu.org/Contribute/TrivialPatches
> 
> Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com>
> ---
>   docs/devel/trivial-patches.rst | 53 ++++++++++++++++++++++++++++++++++
>   1 file changed, 53 insertions(+)
>   create mode 100644 docs/devel/trivial-patches.rst
> 
> diff --git a/docs/devel/trivial-patches.rst b/docs/devel/trivial-patches.rst
> new file mode 100644
> index 0000000000..4ad0d25b9d
> --- /dev/null
> +++ b/docs/devel/trivial-patches.rst
> @@ -0,0 +1,53 @@
> +===============
> +Trivial Patches
> +===============
> +
> +Overview
> +========
> +
> +Trivial patches that change just a few lines of code sometimes languish
> +on the mailing list even though they require only a small amount of
> +review. This is often the case for patches that do not fall under an
> +actively maintained subsystem and therefore fall through the cracks.
> +
> +The trivial patches team take on the task of reviewing and building pull
> +requests for patches that:
> +
> +- Do not fall under an actively maintained subsystem.
> +- Are single patches or short series (max 2-4 patches).
> +- Only touch a few lines of code.
> +
> +**You should hint that your patch is a candidate by CCing
> +qemu-trivial@nongnu.org.**
> +
> +Repositories
> +============
> +
> +Since the trivial patch team rotates maintainership there is only one
> +active repository at a time:
> +
> +- git://git.corpit.ru/qemu.git trivial-patches - `browse <http://git.corpit.ru/?p=qemu.git;a=shortlog;h=refs/heads/trivial-patches>`__
> +- git://github.com/vivier/qemu.git trivial-patches - `browse <https://github.com/vivier/qemu/tree/trivial-patches>`__
> +
> +Workflow
> +========
> +
> +The trivial patches team rotates the duty of collecting trivial patches
> +amongst its members. A team member's job is to:
> +
> +1. Identify trivial patches on the development mailing list.
> +2. Review trivial patches, merge them into a git tree, and reply to state
> +   that the patch is queued.
> +3. Send pull requests to the development mailing list once a week.
> +
> +A single team member can be on duty as long as they like. The suggested
> +time is 1 week before handing off to the next member.
> +
> +Team
> +====
> +
> +If you would like to join the trivial patches team, contact Michael
> +Tokarev. The current team includes:
> +
> +- Michael Tokarev
> +- `Laurent Vivier <mailto:laurent@vivier.eu>`__

I asked Michael if he could send a qemu-trivial@ pullreq last month
when Laurent was on PTO and he said he hasn't done it in years.

Indeed:

$ git log --committer='Michael Tokarev'
commit 9a232487aab8a7640ff8853d7d8d7c27106b44f8
Date:   Fri Apr 13 18:45:45 2018 +0200

So I think you are trying to commit obsolete information.

Anyway, up to Michael to adjust.

Thanks for rstifying the doc :)

Phil.

Re: [PATCH 2/3] docs: rSTify the "TrivialPatches" wiki

[Kashyap Chamarthy]

On Wed, Sep 22, 2021 at 03:05:02PM +0200, Philippe Mathieu-Daudé wrote:
> Hi Kashyap,

Heya,

> On 9/22/21 14:10, Kashyap Chamarthy wrote:

[...]

> > +If you would like to join the trivial patches team, contact Michael
> > +Tokarev. The current team includes:
> > +
> > +- Michael Tokarev
> > +- `Laurent Vivier <mailto:laurent@vivier.eu>`__
> 
> I asked Michael if he could send a qemu-trivial@ pullreq last month
> when Laurent was on PTO and he said he hasn't done it in years.
> 
> Indeed:
> 
> $ git log --committer='Michael Tokarev'
> commit 9a232487aab8a7640ff8853d7d8d7c27106b44f8
> Date:   Fri Apr 13 18:45:45 2018 +0200
> 
> So I think you are trying to commit obsolete information.
> 
> Anyway, up to Michael to adjust.
> 
> Thanks for rstifying the doc :)

Thanks for the quick review.  I first just did a 1-1 conversion of the
wiki, because I didn't want to mix content changes with the rST
conversion patch for various reasons we both know. :-)

If we don't hear from Michael on this, I'll let Peter/Laurent adjust the
doc while pushing the patch.

-- 
/kashyap

Re: [PATCH 2/3] docs: rSTify the "TrivialPatches" wiki

[Daniel P. Berrangé]

On Wed, Sep 22, 2021 at 03:05:02PM +0200, Philippe Mathieu-Daudé wrote:
> Hi Kashyap,
> 
> On 9/22/21 14:10, Kashyap Chamarthy wrote:
> > The original wiki is here[1].  I converted by copying the wiki source
> > into a .wiki file and convert to rST using `pandoc`:
> > 
> >          $ pandoc -f Mediawiki -t rst trivial-patches.wiki -o trivial-patches.rst
> > 
> > [1] https://wiki.qemu.org/Contribute/TrivialPatches
> > 
> > Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com>
> > ---
> >   docs/devel/trivial-patches.rst | 53 ++++++++++++++++++++++++++++++++++
> >   1 file changed, 53 insertions(+)
> >   create mode 100644 docs/devel/trivial-patches.rst
> > 
> > diff --git a/docs/devel/trivial-patches.rst b/docs/devel/trivial-patches.rst
> > new file mode 100644
> > index 0000000000..4ad0d25b9d
> > --- /dev/null
> > +++ b/docs/devel/trivial-patches.rst
> > @@ -0,0 +1,53 @@
> > +===============
> > +Trivial Patches
> > +===============
> > +
> > +Overview
> > +========
> > +
> > +Trivial patches that change just a few lines of code sometimes languish
> > +on the mailing list even though they require only a small amount of
> > +review. This is often the case for patches that do not fall under an
> > +actively maintained subsystem and therefore fall through the cracks.
> > +
> > +The trivial patches team take on the task of reviewing and building pull
> > +requests for patches that:
> > +
> > +- Do not fall under an actively maintained subsystem.
> > +- Are single patches or short series (max 2-4 patches).
> > +- Only touch a few lines of code.
> > +
> > +**You should hint that your patch is a candidate by CCing
> > +qemu-trivial@nongnu.org.**
> > +
> > +Repositories
> > +============
> > +
> > +Since the trivial patch team rotates maintainership there is only one
> > +active repository at a time:
> > +
> > +- git://git.corpit.ru/qemu.git trivial-patches - `browse <http://git.corpit.ru/?p=qemu.git;a=shortlog;h=refs/heads/trivial-patches>`__
> > +- git://github.com/vivier/qemu.git trivial-patches - `browse <https://github.com/vivier/qemu/tree/trivial-patches>`__
> > +
> > +Workflow
> > +========
> > +
> > +The trivial patches team rotates the duty of collecting trivial patches
> > +amongst its members. A team member's job is to:
> > +
> > +1. Identify trivial patches on the development mailing list.
> > +2. Review trivial patches, merge them into a git tree, and reply to state
> > +   that the patch is queued.
> > +3. Send pull requests to the development mailing list once a week.
> > +
> > +A single team member can be on duty as long as they like. The suggested
> > +time is 1 week before handing off to the next member.
> > +
> > +Team
> > +====
> > +
> > +If you would like to join the trivial patches team, contact Michael
> > +Tokarev. The current team includes:
> > +
> > +- Michael Tokarev
> > +- `Laurent Vivier <mailto:laurent@vivier.eu>`__
> 
> I asked Michael if he could send a qemu-trivial@ pullreq last month
> when Laurent was on PTO and he said he hasn't done it in years.
> 
> Indeed:
> 
> $ git log --committer='Michael Tokarev'
> commit 9a232487aab8a7640ff8853d7d8d7c27106b44f8
> Date:   Fri Apr 13 18:45:45 2018 +0200
> 
> So I think you are trying to commit obsolete information.

That's wikis for you.... pages of obsolete information. Bad info
is more likely to be noticed & updated if we have it in the qemu.git
repo where most developers work !


Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

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

[Kashyap Chamarthy]

- 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 small wiki pages (included in
  this patch series):

  - SpellCheck: https://wiki.qemu.org/Contribute/SpellCheck
  - 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>
---
NB: As of writing this, qemu.org is down, so I've used a one-month old
    copy[4] of the wiki from 27Aug2021 to do the rST conversion.

[4] https://web.archive.org/web/20210827130706/https://wiki.qemu.org/Contribute/SubmitAPatch

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

diff --git a/docs/devel/submitting-a-patch.rst b/docs/devel/submitting-a-patch.rst
new file mode 100644
index 0000000000..1d85404438
--- /dev/null
+++ b/docs/devel/submitting-a-patch.rst
@@ -0,0 +1,460 @@
+==================
+Submitting a Patch
+==================
+
+QEMU welcomes contributions of code (either fixing bugs or adding new
+functionality). However, we get a lot of patches, and so we have some
+guidelines about submitting patches. If you follow these, you'll help
+make our task of code review easier and your patch is likely to be
+committed faster.
+
+This page seems very long, so if you are only trying to post a quick
+one-shot fix, the bare minimum we ask is that:
+
+-  You **must** provide a Signed-off-by: line (this is a hard
+   requirement because it's how you say "I'm legally okay to contribute
+   this and happy for it to go into QEMU", modeled after the `Linux
+   kernel <http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/SubmittingPatches?id=f6f94e2ab1b33f0082ac22d71f66385a60d8157f#n297>`__
+   policy.) ``git commit -s`` or ``git format-patch -s`` will add one.
+-  All contributions to QEMU must be **sent as patches** to the
+   qemu-devel `mailing list <MailingLists>`__. Patch contributions
+   should not be posted on the bug tracker, posted on forums, or
+   externally hosted and linked to. (We have other mailing lists too,
+   but all patches must go to qemu-devel, possibly with a Cc: to another
+   list.) ``git send-email`` works best for delivering the patch without
+   mangling it (`hints for setting it
+   up <http://lxr.free-electrons.com/source/Documentation/process/email-clients.rst>`__),
+   but attachments can be used as a last resort on a first-time
+   submission.
+-  You must read replies to your message, and be willing to act on them.
+   Note, however, that maintainers are often willing to manually fix up
+   first-time contributions, since there is a learning curve involved in
+   making an ideal patch submission.
+
+You do not have to subscribe to post (list policy is to reply-to-all to
+preserve CCs and keep non-subscribers in the loop on the threads they
+start), although you may find it easier as a subscriber to pick up good
+ideas from other posts. If you do subscribe, be prepared for a high
+volume of email, often over one thousand messages in a week. The list is
+moderated; first-time posts from an email address (whether or not you
+subscribed) may be subject to some delay while waiting for a moderator
+to whitelist your address.
+
+The larger your contribution is, or if you plan on becoming a long-term
+contributor, then the more important the rest of this page becomes.
+Reading the table of contents below should already give you an idea of
+the basic requirements. Use the table of contents as a reference, and
+read the parts that you have doubts about.
+
+.. _writing_your_patches:
+
+Writing your Patches
+====================
+
+.. _use_the_qemu_coding_style:
+
+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
+preprocessor macros are involved; use some common sense too. See also:
+
+- `QEMU Coding Style
+  <https://qemu-project.gitlab.io/qemu/devel/style.html>`__
+
+-  `Automate a checkpatch run on
+   commit <http://blog.vmsplice.net/2011/03/how-to-automatically-run-checkpatchpl.html>`__
+
+- `Spell Check
+  <https://qemu-project.gitlab.io/qemu/devel/spell-check.html>`__ your
+  patches
+
+.. _base_patches_against_current_git_master:
+
+Base patches against current git master
+---------------------------------------
+
+There's no point submitting a patch which is based on a released version
+of QEMU because development will have moved on from then and it probably
+won't even apply to master. We only apply selected bugfixes to release
+branches and then only as backports once the code has gone into master.
+
+.. _split_up_long_patches:
+
+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
+points in the commit history where QEMU doesn't work for reasons
+unrelated to the bug they're chasing.) Put documentation first, not
+last, so that someone reading the series can do a clean-room evaluation
+of the documentation, then validate that the code matched the
+documentation. A commit message that mentions "Also, ..." is often a
+good candidate for splitting into multiple patches. For more thoughts on
+properly splitting patches and writing good commit messages, see `this
+advice from
+OpenStack <https://wiki.openstack.org/wiki/GitCommitMessages>`__.
+
+.. _make_code_motion_patches_easy_to_review:
+
+Make code motion patches easy to review
+---------------------------------------
+
+If a series requires large blocks of code motion, there are tricks for
+making the refactoring easier to review. Split up the series so that
+semantic changes (or even function renames) are done in a separate patch
+from the raw code motion. Use a one-time setup of
+``git config diff.renames true; git config diff.algorithm patience``
+(Refer to `git-config <http://git-scm.com/docs/git-config>`__.)  The
+``diff.renames`` property ensures file rename patches will be given in a
+more compact representation that focuses only on the differences across
+the file rename, instead of showing the entire old file as a deletion
+and the new file as an insertion. Meanwhile, the 'diff.algorithm'
+property ensures that extracting a non-contiguous subset of one file
+into a new file, but where all extracted parts occur in the same order
+both before and after the patch, will reduce churn in trying to treat
+unrelated ``}`` lines in the original file as separating hunks of
+changes.
+
+Ideally, a code motion patch can be reviewed by doing::
+
+    git format-patch --stdout -1 > patch;
+    diff -u <(sed -n 's/^-//p' patch) <(sed -n 's/^\+//p' patch)
+
+to focus on the few changes that weren't wholesale code motion.
+
+.. _dont_include_irrelevant_changes:
+
+Don't include irrelevant changes
+--------------------------------
+
+In particular, don't include formatting, coding style or whitespace
+changes to bits of code that would otherwise not be touched by the
+patch. (It's OK to fix coding style issues in the immediate area (few
+lines) of the lines you're changing.) If you think a section of code
+really does need a reindent or other large-scale style fix, submit this
+as a separate patch which makes no semantic changes; don't put it in the
+same patch as your bug fix.
+
+For smaller patches in less frequently changed areas of QEMU, consider
+using the `trivial patches process
+<https://qemu-project.gitlab.io/qemu/devel/style.html>`__.
+
+.. _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 ".". 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
+they don't go into the final commit message). Make sure the body of the
+commit message can be read in isolation even if the reader's mailer
+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).
+
+.. _submitting_your_patches:
+
+Submitting your Patches
+=======================
+
+.. _cc_the_relevant_maintainer:
+
+CC the relevant maintainer
+--------------------------
+
+Send patches both to the mailing list and CC the maintainer(s) of the
+files you are modifying. look in the MAINTAINERS file to find out who
+that is. Also try using scripts/get_maintainer.pl from the repository
+for learning the most common committers for the files you touched.
+
+Example::
+
+    ~/src/qemu/scripts/get_maintainer.pl -f hw/ide/core.c
+
+In fact, you can automate this, via a one-time setup of ``git config
+sendemail.cccmd 'scripts/get_maintainer.pl --nogit-fallback'`` (Refer to
+`git-config <http://git-scm.com/docs/git-config>`__.)
+
+.. _do_not_send_as_an_attachment:
+
+Do not send as an attachment
+----------------------------
+
+Send patches inline so they are easy to reply to with review comments.
+Do not put patches in attachments.
+
+.. _use_git_format_patch:
+
+Use ``git format-patch``
+------------------------
+
+Use the right diff format.
+`git format-patch <http://git-scm.com/docs/git-format-patch>`__ will
+produce patch emails in the right format (check the documentation to
+find out how to drive it). You can then edit the cover letter before
+using ``git send-email`` to mail the files to the mailing list. (We
+recommend `git send-email <http://git-scm.com/docs/git-send-email>`__
+because mail clients often mangle patches by wrapping long lines or
+messing up whitespace. Some distributions do not include send-email in a
+default install of git; you may need to download additional packages,
+such as 'git-email' on Fedora-based systems.) Patch series need a cover
+letter, with shallow threading (all patches in the series are
+in-reply-to the cover letter, but not to each other); single unrelated
+patches do not need a cover letter (but if you do send a cover letter,
+use --numbered so the cover and the patch have distinct subject lines).
+Patches are easier to find if they start a new top-level thread, rather
+than being buried in-reply-to another existing thread.
+
+.. _patch_emails_must_include_a_signed_off_by_line:
+
+Patch emails must include a ``Signed-off-by:`` line
+---------------------------------------------------
+
+For more information see `1.12) Sign your work
+<http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/SubmittingPatches?id=f6f94e2ab1b33f0082ac22d71f66385a60d8157f#n296>`__.
+This is vital or we will not be able to apply your patch! Please use
+your real name to sign a patch (not an alias or acronym).
+
+If you wrote the patch, make sure your "From:" and "Signed-off-by:"
+lines use the same spelling. It's okay if you subscribe or contribute to
+the list via more than one address, but using multiple addresses in one
+commit just confuses things. If someone else wrote the patch, git will
+include a "From:" line in the body of the email (different from your
+envelope From:) that will give credit to the correct author; but again,
+that author's Signed-off-by: line is mandatory, with the same spelling.
+
+.. _include_a_meaningful_cover_letter:
+
+Include a meaningful cover letter
+---------------------------------
+
+This usually applies only to a series that includes multiple patches;
+the cover letter explains the overall goal of such a series.
+
+When reviewers don't know your goal at the start of their review, they
+may object to early changes that don't make sense until the end of the
+series, because they do not have enough context yet at that point of
+their review. A series where the goal is unclear also risks a higher
+number of review-fix cycles because the reviewers haven't bought into
+the idea yet. If the cover letter can explain these points to the
+reviewer, the process will be smoother patches will get merged faster.
+Make sure your cover letter includes a diffstat of changes made over the
+entire series; potential reviewers know what files they are interested
+in, and they need an easy way determine if your series touches them.
+
+.. _use_the_rfc_tag_if_needed:
+
+Use the RFC tag if needed
+-------------------------
+
+For example, "[PATCH RFC v2]". ``git format-patch --subject-prefix=RFC``
+can help.
+
+"RFC" means "Request For Comments" and is a statement that you don't
+intend for your patchset to be applied to master, but would like some
+review on it anyway. Reasons for doing this include:
+
+-  the patch depends on some pending kernel changes which haven't yet
+   been accepted, so the QEMU patch series is blocked until that
+   dependency has been dealt with, but is worth reviewing anyway
+-  the patch set is not finished yet (perhaps it doesn't cover all use
+   cases or work with all targets) but you want early review of a major
+   API change or design structure before continuing
+
+In general, since it's asking other people to do review work on a
+patchset that the submitter themselves is saying shouldn't be applied,
+it's best to:
+
+-  use it sparingly
+-  in the cover letter, be clear about why a patch is an RFC, what areas
+   of the patchset you're looking for review on, and why reviewers
+   should care
+
+.. _participating_in_code_review:
+
+Participating in Code Review
+============================
+
+All patches submitted to the QEMU project go through a code review
+process before they are accepted. Some areas of code that are well
+maintained may review patches quickly, lesser-loved areas of code may
+have a longer delay.
+
+.. _stay_around_to_fix_problems_raised_in_code_review:
+
+Stay around to fix problems raised in code review
+-------------------------------------------------
+
+Not many patches get into QEMU straight away -- it is quite common that
+developers will identify bugs, or suggest a cleaner approach, or even
+just point out code style issues or commit message typos. You'll need to
+respond to these, and then send a second version of your patches with
+the issues fixed. This takes a little time and effort on your part, but
+if you don't do it then your changes will never get into QEMU. It's also
+just polite -- it is quite disheartening for a developer to spend time
+reviewing your code and suggesting improvements, only to find that
+you're not going to do anything further and it was all wasted effort.
+
+When replying to comments on your patches **reply to all and not just
+the sender** -- keeping discussion on the mailing list means everybody
+can follow it.
+
+.. _pay_attention_to_review_comments:
+
+Pay attention to review comments
+--------------------------------
+
+Someone took their time to review your work, and it pays to respect that
+effort; repeatedly submitting a series without addressing all comments
+from the previous round tends to alienate reviewers and stall your
+patch. Reviewers aren't always perfect, so it is okay if you want to
+argue that your code was correct in the first place instead of blindly
+doing everything the reviewer asked. On the other hand, if someone
+pointed out a potential issue during review, then even if your code
+turns out to be correct, it's probably a sign that you should improve
+your commit message and/or comments in the code explaining why the code
+is correct.
+
+If you fix issues that are raised during review **resend the entire
+patch series** not just the one patch that was changed. This allows
+maintainers to easily apply the fixed series without having to manually
+identify which patches are relevant. Send the new version as a complete
+fresh email or series of emails -- don't try to make it a followup to
+version 1. (This helps automatic patch email handling tools distinguish
+between v1 and v2 emails.)
+
+.. _when_resending_patches_add_a_version_tag:
+
+When resending patches add a version tag
+----------------------------------------
+
+All patches beyond the first version should include a version tag -- for
+example, "[PATCH v2]". This means people can easily identify whether
+they're looking at the most recent version. (The first version of a
+patch need not say "v1", just [PATCH] is sufficient.) For patch series,
+the version applies to the whole series -- even if you only change one
+patch, you resend the entire series and mark it as "v2". Don't try to
+track versions of different patches in the series separately.  `git
+format-patch <http://git-scm.com/docs/git-format-patch>`__ and `git
+send-email <http://git-scm.com/docs/git-send-email>`__ both understand
+the ``-v2`` option to make this easier. Send each new revision as a new
+top-level thread, rather than burying it in-reply-to an earlier
+revision, as many reviewers are not looking inside deep threads for new
+patches.
+
+.. _include_version_history_in_patchset_revisions:
+
+Include version history in patchset revisions
+---------------------------------------------
+
+For later versions of patches, include a summary of changes from
+previous versions, but not in the commit message itself. In an email
+formatted as a git patch, the commit message is the part above the "---"
+line, and this will go into the git changelog when the patch is
+committed. This part should be a self-contained description of what this
+version of the patch does, written to make sense to anybody who comes
+back to look at this commit in git in six months' time. The part below
+the "---" line and above the patch proper (git format-patch puts the
+diffstat here) is a good place to put remarks for people reading the
+patch email, and this is where the "changes since previous version"
+summary belongs. The
+`git-publish <https://github.com/stefanha/git-publish>`__ script can
+help with tracking a good summary across versions. Also, the
+`git-backport-diff <https://github.com/codyprime/git-scripts>`__ script
+can help focus reviewers on what changed between revisions.
+
+.. _tips_and_tricks:
+
+Tips and Tricks
+===============
+
+.. _proper_use_of_reviewed_by_tags_can_aid_review:
+
+Proper use of Reviewed-by: tags can aid review
+----------------------------------------------
+
+When reviewing a large series, a reviewer can reply to some of the
+patches with a Reviewed-by tag, stating that they are happy with that
+patch in isolation (sometimes conditional on minor cleanup, like fixing
+whitespace, that doesn't affect code content). You should then update
+those commit messages by hand to include the Reviewed-by tag, so that in
+the next revision, reviewers can spot which patches were already clean
+from the previous round. Conversely, if you significantly modify a patch
+that was previously reviewed, remove the reviewed-by tag out of the
+commit message, as well as listing the changes from the previous
+version, to make it easier to focus a reviewer's attention to your
+changes.
+
+.. _if_your_patch_seems_to_have_been_ignored:
+
+If your patch seems to have been ignored
+----------------------------------------
+
+If your patchset has received no replies you should "ping" it after a
+week or two, by sending an email as a reply-to-all to the patch mail,
+including the word "ping" and ideally also a link to the page for the
+patch on
+`patchwork <http://patchwork.ozlabs.org/project/qemu-devel/list/>`__ or
+GMANE. It's worth double-checking for reasons why your patch might have
+been ignored (forgot to CC the maintainer? annoyed people by failing to
+respond to review comments on an earlier version?), but often for
+less-maintained areas of QEMU patches do just slip through the cracks.
+If your ping is also ignored, ping again after another week or so. As
+the submitter, you are the person with the most motivation to get your
+patch applied, so you have to be persistent.
+
+.. _is_my_patch_in:
+
+Is my patch in?
+---------------
+
+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 <Contribute/SubmitAPullRequest>`__ 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
+fixing minor typos pointed out during review, but will always add a
+Signed-off-by line in addition to yours, indicating that it went through
+their tree. Occasionally, the maintainer's pull request may hit more
+difficult merge conflicts, where you may be requested to help rebase and
+resolve the problems. It may take a couple of weeks between when your
+patch first had a positive review to when it finally lands in qemu.git;
+release cycle freezes may extend that time even longer.
+
+.. _return_the_favor:
+
+Return the favor
+----------------
+
+Peer review only works if everyone chips in a bit of review time. If
+everyone submitted more patches than they reviewed, we would have a
+patch backlog. A good goal is to try to review at least as many patches
+from others as what you submit. Don't worry if you don't know the code
+base as well as a maintainer; it's perfectly fine to admit when your
+review is weak because you are unfamiliar with the code.
-- 
2.31.1

Re: [PATCH 0/3] rSTify SubmitAPatch, TrivialPatches, and SpellCheck wiki pages

[Peter Maydell]

On Wed, 22 Sept 2021 at 13:11, Kashyap Chamarthy <kchamart@redhat.com> wrote:
>
> As of writing this, qemu.org is down, so I've used a one-month old
> copy[1] of the wiki from 27Aug2021 to do the rST conversion.

The wiki is now back up, and it says the most recent change to
any of these 3 pages was May 2021, so there shouldn't be any
recent changes missed by using that old copy.

thanks
-- PMM

Re: [PATCH 0/3] rSTify SubmitAPatch, TrivialPatches, and SpellCheck wiki pages

[Kashyap Chamarthy]

On Wed, Sep 22, 2021 at 02:05:24PM +0100, Peter Maydell wrote:
> On Wed, 22 Sept 2021 at 13:11, Kashyap Chamarthy <kchamart@redhat.com> wrote:
> >
> > As of writing this, qemu.org is down, so I've used a one-month old
> > copy[1] of the wiki from 27Aug2021 to do the rST conversion.
> 
> The wiki is now back up, and it says the most recent change to
> any of these 3 pages was May 2021, so there shouldn't be any
> recent changes missed by using that old copy.

Saves a re-spin; thanks for checking. :)

-- 
/kashyap

Re: [PATCH 0/3] rSTify SubmitAPatch, TrivialPatches, and SpellCheck wiki pages

[Paolo Bonzini]

On 22/09/21 14:10, Kashyap Chamarthy wrote:
> As of writing this, qemu.org is down, so I've used a one-month old
> copy[1] of the wiki from 27Aug2021 to do the rST conversion.
> 
> My main motivation was to convert SubmitAPatch (when Peter Maydell
> pointed out on IRC that it's still on the wiki).  But it links to a
> couple more small wiki pages; so I converted them too:
> 
>    - SpellCheck: https://wiki.qemu.org/Contribute/SpellCheck
>    - TrivialPatches: https://wiki.qemu.org/Contribute/TrivialPatches
> 
> [1] https://web.archive.org/web/20210827130706/https://wiki.qemu.org/Contribute/SubmitAPatch
> 
> Kashyap Chamarthy (3):
>    docs: rSTify the "SpellCheck" wiki
>    docs: rSTify the "TrivialPatches" wiki
>    docs: rSTify the "SubmitAPatch" wiki
> 
>   docs/devel/spell-check.rst        |  29 ++
>   docs/devel/submitting-a-patch.rst | 460 ++++++++++++++++++++++++++++++
>   docs/devel/trivial-patches.rst    |  53 ++++
>   3 files changed, 542 insertions(+)
>   create mode 100644 docs/devel/spell-check.rst
>   create mode 100644 docs/devel/submitting-a-patch.rst
>   create mode 100644 docs/devel/trivial-patches.rst
> 

I think this is missing a link to the new documents in the toctree?

Also, I would prefer to have the headings as "===" "---" "~~~" 
consistently (I have posted some patches this morning that do this for a 
few more files).

Paolo

Re: [PATCH 0/3] rSTify SubmitAPatch, TrivialPatches, and SpellCheck wiki pages

[Kashyap Chamarthy]

On Tue, Sep 28, 2021 at 07:31:26PM +0200, Paolo Bonzini wrote:
> On 22/09/21 14:10, Kashyap Chamarthy wrote:

[...]

> >   docs/devel/spell-check.rst        |  29 ++
> >   docs/devel/submitting-a-patch.rst | 460 ++++++++++++++++++++++++++++++
> >   docs/devel/trivial-patches.rst    |  53 ++++
> >   3 files changed, 542 insertions(+)
> >   create mode 100644 docs/devel/spell-check.rst
> >   create mode 100644 docs/devel/submitting-a-patch.rst
> >   create mode 100644 docs/devel/trivial-patches.rst
> > 
> 
> I think this is missing a link to the new documents in the toctree?

You're right; will do in v2.  (I accidentally added 'toctree' to the
same doc, but then I realized, "no, you should update the index.rst" and
I still missed it.)

> Also, I would prefer to have the headings as "===" "---" "~~~" consistently
> (I have posted some patches this morning that do this for a few more files).

Sure.  I actually checked a couple of existing docs in-tree
build-system.rst and qapi-code-gen.rst) before I used this set of
headings. 

[1] https://www.kernel.org/doc/html/v4.10/doc-guide/sphinx.html#specific-guidelines-for-the-kernel-documentation

-- 
/kashyap

Re: [PATCH 0/3] rSTify SubmitAPatch, TrivialPatches, and SpellCheck wiki pages

[Stefan Hajnoczi]

[-- Attachment #1: Type: text/plain, Size: 1333 bytes --]

On Wed, Sep 22, 2021 at 02:10:51PM +0200, Kashyap Chamarthy wrote:
> As of writing this, qemu.org is down, so I've used a one-month old
> copy[1] of the wiki from 27Aug2021 to do the rST conversion.
> 
> My main motivation was to convert SubmitAPatch (when Peter Maydell
> pointed out on IRC that it's still on the wiki).  But it links to a
> couple more small wiki pages; so I converted them too:
> 
>   - SpellCheck: https://wiki.qemu.org/Contribute/SpellCheck
>   - TrivialPatches: https://wiki.qemu.org/Contribute/TrivialPatches

What is the motivation for moving these pages from the wiki to qemu.git
(https://qemu-project.gitlab.io/qemu/devel/index.html)?

> [1] https://web.archive.org/web/20210827130706/https://wiki.qemu.org/Contribute/SubmitAPatch
> 
> Kashyap Chamarthy (3):
>   docs: rSTify the "SpellCheck" wiki
>   docs: rSTify the "TrivialPatches" wiki
>   docs: rSTify the "SubmitAPatch" wiki
> 
>  docs/devel/spell-check.rst        |  29 ++
>  docs/devel/submitting-a-patch.rst | 460 ++++++++++++++++++++++++++++++
>  docs/devel/trivial-patches.rst    |  53 ++++
>  3 files changed, 542 insertions(+)
>  create mode 100644 docs/devel/spell-check.rst
>  create mode 100644 docs/devel/submitting-a-patch.rst
>  create mode 100644 docs/devel/trivial-patches.rst
> 
> -- 
> 2.31.1
> 
> 

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: [PATCH 0/3] rSTify SubmitAPatch, TrivialPatches, and SpellCheck wiki pages

[Kashyap Chamarthy]

On Tue, Oct 05, 2021 at 03:01:17PM +0100, Stefan Hajnoczi wrote:
> On Wed, Sep 22, 2021 at 02:10:51PM +0200, Kashyap Chamarthy wrote:
> > As of writing this, qemu.org is down, so I've used a one-month old
> > copy[1] of the wiki from 27Aug2021 to do the rST conversion.
> > 
> > My main motivation was to convert SubmitAPatch (when Peter Maydell
> > pointed out on IRC that it's still on the wiki).  But it links to a
> > couple more small wiki pages; so I converted them too:
> > 
> >   - SpellCheck: https://wiki.qemu.org/Contribute/SpellCheck
> >   - TrivialPatches: https://wiki.qemu.org/Contribute/TrivialPatches
> 
> What is the motivation for moving these pages from the wiki to qemu.git
> (https://qemu-project.gitlab.io/qemu/devel/index.html)?

They were linked to from the SubmitAPatch page.  I thought having one
doc in qemu.git and the other two related docs on the Wiki was clunky.
I can leave them on the Wiki as-is.  But I thought upstream is wants to
move away from the Wiki to in-tree docs where it makes sense.

[...]

-- 
/kashyap

Re: [PATCH 0/3] rSTify SubmitAPatch, TrivialPatches, and SpellCheck wiki pages

[Stefan Hajnoczi]

[-- Attachment #1: Type: text/plain, Size: 1285 bytes --]

On Tue, Oct 05, 2021 at 04:11:54PM +0200, Kashyap Chamarthy wrote:
> On Tue, Oct 05, 2021 at 03:01:17PM +0100, Stefan Hajnoczi wrote:
> > On Wed, Sep 22, 2021 at 02:10:51PM +0200, Kashyap Chamarthy wrote:
> > > As of writing this, qemu.org is down, so I've used a one-month old
> > > copy[1] of the wiki from 27Aug2021 to do the rST conversion.
> > > 
> > > My main motivation was to convert SubmitAPatch (when Peter Maydell
> > > pointed out on IRC that it's still on the wiki).  But it links to a
> > > couple more small wiki pages; so I converted them too:
> > > 
> > >   - SpellCheck: https://wiki.qemu.org/Contribute/SpellCheck
> > >   - TrivialPatches: https://wiki.qemu.org/Contribute/TrivialPatches
> > 
> > What is the motivation for moving these pages from the wiki to qemu.git
> > (https://qemu-project.gitlab.io/qemu/devel/index.html)?
> 
> They were linked to from the SubmitAPatch page.  I thought having one
> doc in qemu.git and the other two related docs on the Wiki was clunky.
> I can leave them on the Wiki as-is.  But I thought upstream is wants to
> move away from the Wiki to in-tree docs where it makes sense.

I meant SubmitAPatch too :). I may have forgotten or missed the IRC
discussion so I wanted to understand the reason.

Stefan

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: [PATCH 0/3] rSTify SubmitAPatch, TrivialPatches, and SpellCheck wiki pages

[Kashyap Chamarthy]

On Tue, Oct 05, 2021 at 03:24:06PM +0100, Stefan Hajnoczi wrote:
> On Tue, Oct 05, 2021 at 04:11:54PM +0200, Kashyap Chamarthy wrote:

[...]

> > They were linked to from the SubmitAPatch page.  I thought having one
> > doc in qemu.git and the other two related docs on the Wiki was clunky.
> > I can leave them on the Wiki as-is.  But I thought upstream is wants to
> > move away from the Wiki to in-tree docs where it makes sense.
> 
> I meant SubmitAPatch too :). I may have forgotten or missed the IRC
> discussion so I wanted to understand the reason.

I converted it based on ththe following chat with Peter on #qemu, OFTC.
This was on 22Sep2021 (if you have the IRC log archives).  I agree with
Peter, SubmitAPatch doc should be in-tree:

  ...
  <pm215> (we absolutely do have stuff on the wiki that should be in
          the docs, eg the networking page)
  <pm215> the "how to contribute a patch" page ought to be in
          docs/devel/
  <danpb> all the platform specific build guides should be too
  ...

Then, Peter and DanPB pointed more sources of unmaintained docs: 

  - All the pages under https://wiki.qemu.org/Documentation - Peter
    suggests to incorporate them information into the actual
    documentation in docs/.  
  
  - The "Feature" pages:
    https://wiki.qemu.org/Special:AllPages.  DanPB asked how many of
    them are actually accurate.  As some of them go back to 10 years.

  - Then there are the "lonely pages (pointed out by Peter):
    https://wiki.qemu.org/Special:LonelyPages - these are
    unreachable.  DanPB noted that there are 151 "lonely pages".  This
    doesn't mean they're obsolete, though - some of them were written in
    2021.

-- 
/kashyap

Re: [PATCH 0/3] rSTify SubmitAPatch, TrivialPatches, and SpellCheck wiki pages

[Philippe Mathieu-Daudé]

On 10/5/21 16:24, Stefan Hajnoczi wrote:
> On Tue, Oct 05, 2021 at 04:11:54PM +0200, Kashyap Chamarthy wrote:
>> On Tue, Oct 05, 2021 at 03:01:17PM +0100, Stefan Hajnoczi wrote:
>>> On Wed, Sep 22, 2021 at 02:10:51PM +0200, Kashyap Chamarthy wrote:
>>>> As of writing this, qemu.org is down, so I've used a one-month old
>>>> copy[1] of the wiki from 27Aug2021 to do the rST conversion.
>>>>
>>>> My main motivation was to convert SubmitAPatch (when Peter Maydell
>>>> pointed out on IRC that it's still on the wiki).  But it links to a
>>>> couple more small wiki pages; so I converted them too:
>>>>
>>>>   - SpellCheck: https://wiki.qemu.org/Contribute/SpellCheck
>>>>   - TrivialPatches: https://wiki.qemu.org/Contribute/TrivialPatches
>>>
>>> What is the motivation for moving these pages from the wiki to qemu.git
>>> (https://qemu-project.gitlab.io/qemu/devel/index.html)?
>>
>> They were linked to from the SubmitAPatch page.  I thought having one
>> doc in qemu.git and the other two related docs on the Wiki was clunky.
>> I can leave them on the Wiki as-is.  But I thought upstream is wants to
>> move away from the Wiki to in-tree docs where it makes sense.
> 
> I meant SubmitAPatch too :). I may have forgotten or missed the IRC
> discussion so I wanted to understand the reason.

One point Peter raised on IRC is it is easier to update a Wiki page
than get a patch merged into the repository. IOW we are making things
harder.

GitLab provides a wiki for all tiers, but requires contributors to have
the Developer role to be able to modify the wiki:
https://docs.gitlab.com/ee/user/project/wiki/#edit-a-wiki-page
I suppose this is a no-go since currently it is enought having
contributors as reporters (to fill issues).

Alternative could be to have a qemu-wiki project within qemu-project
gitlab namespace, and have point to this one instead (currently we
point to the external wiki).

Re: [PATCH 0/3] rSTify SubmitAPatch, TrivialPatches, and SpellCheck wiki pages

[Daniel P. Berrangé]

On Tue, Oct 05, 2021 at 05:07:06PM +0200, Philippe Mathieu-Daudé wrote:
> On 10/5/21 16:24, Stefan Hajnoczi wrote:
> > On Tue, Oct 05, 2021 at 04:11:54PM +0200, Kashyap Chamarthy wrote:
> >> On Tue, Oct 05, 2021 at 03:01:17PM +0100, Stefan Hajnoczi wrote:
> >>> On Wed, Sep 22, 2021 at 02:10:51PM +0200, Kashyap Chamarthy wrote:
> >>>> As of writing this, qemu.org is down, so I've used a one-month old
> >>>> copy[1] of the wiki from 27Aug2021 to do the rST conversion.
> >>>>
> >>>> My main motivation was to convert SubmitAPatch (when Peter Maydell
> >>>> pointed out on IRC that it's still on the wiki).  But it links to a
> >>>> couple more small wiki pages; so I converted them too:
> >>>>
> >>>>   - SpellCheck: https://wiki.qemu.org/Contribute/SpellCheck
> >>>>   - TrivialPatches: https://wiki.qemu.org/Contribute/TrivialPatches
> >>>
> >>> What is the motivation for moving these pages from the wiki to qemu.git
> >>> (https://qemu-project.gitlab.io/qemu/devel/index.html)?
> >>
> >> They were linked to from the SubmitAPatch page.  I thought having one
> >> doc in qemu.git and the other two related docs on the Wiki was clunky.
> >> I can leave them on the Wiki as-is.  But I thought upstream is wants to
> >> move away from the Wiki to in-tree docs where it makes sense.
> > 
> > I meant SubmitAPatch too :). I may have forgotten or missed the IRC
> > discussion so I wanted to understand the reason.
> 
> One point Peter raised on IRC is it is easier to update a Wiki page
> than get a patch merged into the repository. IOW we are making things
> harder.

There are factors to consider beyond ease of contributions.

Certain information here is documenting a fundamental part of the
QEMU community operation & processes. That ought to have a high
trust level and be subject to review of content changes.  I'd say
the SubmitAPatch page falls in this category.

Other information is essentially random adhoc user written content
that isn't critical to the project. This can live with a low trust
level and little-to-no review.

IMHO, the wiki should only be considered for the latter type of
content, with any important project content being subject to
review.

I also feel like docs in git is more likely to be kept upto date
by the regular maintainers, than wikis which can become a bit of
outdated mess.

It is a shame that our normal contribution workflow doesn't make
it easy for simple docs changes to be accepted and merged :-(

> GitLab provides a wiki for all tiers, but requires contributors to have
> the Developer role to be able to modify the wiki:
> https://docs.gitlab.com/ee/user/project/wiki/#edit-a-wiki-page
> I suppose this is a no-go since currently it is enought having
> contributors as reporters (to fill issues).

It is a no-go because "Developer" role gives people commit privs to
the git repo and other related services. We can't give that perm,
even to 99% of our regular contributors, as it puts a hole in our
trust model for code changes, let alone give it to passing one-off
contributors.

> Alternative could be to have a qemu-wiki project within qemu-project
> gitlab namespace, and have point to this one instead (currently we
> point to the external wiki).

I don't consider that all that much better, as even with a separate
project you're giving users permissions todo pretty much anything
with this project, on top of the wiki. 

IMHO gitlab wiki is simply unusable for any projects where the likely
contributors are 3rd parties. Its permission model is clearly designed
only for usage by a trusted development team, all directly committing
to the same repo. This doesn't work in an open source world, only for
private on-site gitlab hosting.


Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

In-tree docs vs. Wiki [Was: Re: [PATCH 0/3] rSTify SubmitAPatch, TrivialPatches, and SpellCheck wiki pages]

[Kashyap Chamarthy]

On Tue, Oct 05, 2021 at 04:37:50PM +0100, Daniel P. Berrangé wrote:
> On Tue, Oct 05, 2021 at 05:07:06PM +0200, Philippe Mathieu-Daudé wrote:

[...]

> > One point Peter raised on IRC is it is easier to update a Wiki page
> > than get a patch merged into the repository. IOW we are making things
> > harder.
> 
> There are factors to consider beyond ease of contributions.
> 
> Certain information here is documenting a fundamental part of the
> QEMU community operation & processes. That ought to have a high
> trust level and be subject to review of content changes.  I'd say
> the SubmitAPatch page falls in this category.
> 
> Other information is essentially random adhoc user written content
> that isn't critical to the project. This can live with a low trust
> level and little-to-no review.
> 
> IMHO, the wiki should only be considered for the latter type of
> content, with any important project content being subject to
> review.
> 
> I also feel like docs in git is more likely to be kept upto date
> by the regular maintainers, than wikis which can become a bit of
> outdated mess.

I agree.  Here's an example that proves your point: had I written this
huge 'live-block-operations.rst'[1] doc as a Wiki, pretty sure it
would've been slowly rotting away.  Now I see 5 other contributors
besides me (including Peter, yourself, and Paolo in this thread) that
have patched it ... by virtue of it being in-tree.

That makes me even more convinced that having development, interface,
and any valuable docs that are in-tree are more well-maintained.

(FWIW, I seem to have more motivation to write docs in rST or similar
formats that can be iterated over, with in-line reviews like regular
patches.  I can't claim the same level of motivation to write Wiki pages
somehow.)

> It is a shame that our normal contribution workflow doesn't make
> it easy for simple docs changes to be accepted and merged :-(

Yeah; improving that can be nicer.

[1] https://qemu.readthedocs.io/en/latest/interop/live-block-operations.html

-- 
/kashyap

Re: In-tree docs vs. Wiki [Was: Re: [PATCH 0/3] rSTify SubmitAPatch, TrivialPatches, and SpellCheck wiki pages]

[Philippe Mathieu-Daudé]

On 10/5/21 18:03, Kashyap Chamarthy wrote:
> On Tue, Oct 05, 2021 at 04:37:50PM +0100, Daniel P. Berrangé wrote:
>> On Tue, Oct 05, 2021 at 05:07:06PM +0200, Philippe Mathieu-Daudé wrote:
> 
> [...]
> 
>>> One point Peter raised on IRC is it is easier to update a Wiki page
>>> than get a patch merged into the repository. IOW we are making things
>>> harder.
>>
>> There are factors to consider beyond ease of contributions.
>>
>> Certain information here is documenting a fundamental part of the
>> QEMU community operation & processes. That ought to have a high
>> trust level and be subject to review of content changes.  I'd say
>> the SubmitAPatch page falls in this category.
>>
>> Other information is essentially random adhoc user written content
>> that isn't critical to the project. This can live with a low trust
>> level and little-to-no review.
>>
>> IMHO, the wiki should only be considered for the latter type of
>> content, with any important project content being subject to
>> review.
>>
>> I also feel like docs in git is more likely to be kept upto date
>> by the regular maintainers, than wikis which can become a bit of
>> outdated mess.
> 
> I agree.  Here's an example that proves your point: had I written this
> huge 'live-block-operations.rst'[1] doc as a Wiki, pretty sure it
> would've been slowly rotting away.  Now I see 5 other contributors
> besides me (including Peter, yourself, and Paolo in this thread) that
> have patched it ... by virtue of it being in-tree.
> 
> That makes me even more convinced that having development, interface,
> and any valuable docs that are in-tree are more well-maintained.

This example is very convincing :)

> (FWIW, I seem to have more motivation to write docs in rST or similar
> formats that can be iterated over, with in-line reviews like regular
> patches.  I can't claim the same level of motivation to write Wiki pages
> somehow.)
> 
>> It is a shame that our normal contribution workflow doesn't make
>> it easy for simple docs changes to be accepted and merged :-(
> 
> Yeah; improving that can be nicer.
> 
> [1] https://qemu.readthedocs.io/en/latest/interop/live-block-operations.html
>