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

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

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

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

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

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

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

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

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

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

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
> 

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

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