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

["Daniel P. Berrangé" <berrange@redhat.com>]

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