| Message ID | 20210922121054.1458051-1-kchamart@redhat.com (mailing list archive) |
|---|---|
| Headers | show |
| Series | rSTify SubmitAPatch, TrivialPatches, and SpellCheck wiki pages | expand |
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. :)
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
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. [...]
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.
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
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
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 >