rSTify 'report-a-bug' and 'security-process'; move them to QEMU Git
cover rSTify 'report-a-bug' and 'security-process'; move them to QEMU Git
This series rSTifies the said web pages[1][2] from the QEMU web and moves them to docs/devel/ in QEMU Git. This is based on Paolo's feedback here[3].
The rename to 'reporting-a-bug' is done to be consistent with the other in-tree docs. And I put 'security-process' first because, we refer to it from 'reporting-a-bug'. (If we reverse the order, the build fails -- correctly so.)
[1] https://www.qemu.org/contribute/report-a-bug/
[2] https://www.qemu.org/contribute/security-process
[3] https://lists.nongnu.org/archive/html/qemu-devel/2021-11/msg04002.html
Kashyap Chamarthy (2):
docs: rSTify "security-process" page; move it to QEMU Git
docs: rSTify "report-a-bug" page; move it to QEMU Git
docs/devel/index.rst | 9 +- docs/devel/reporting-a-bug.rst | 37 +++++++ docs/devel/security-process.rst | 190 ++++++++++++++++++++++++++++++++ 3 files changed, 233 insertions(+), 3 deletions(-) create mode 100644 docs/devel/reporting-a-bug.rst create mode 100644 docs/devel/security-process.rst
Signature · 1 line
2.31.1
PATCH 1/2 docs: rSTify "security-process" page; move it to QEMU Git
This is based on Paolo's suggestion[1] that the 'security-process'[2] page being a candidate for docs/devel.
Converted from Markdown to rST using:
$> pandoc -f markdown -t rst security-process.md \
-o security-process.rstIt's a 1-1 conversion (I double-checked to the best I could). I've also checked that the hyperlinks work correctly post-conversion.
[1] https://lists.nongnu.org/archive/html/qemu-devel/2021-11/msg04002.html
[2] https://www.qemu.org/contribute/security-process
--- docs/devel/index.rst | 1 + docs/devel/security-process.rst | 190 ++++++++++++++++++++++++++++++++ 2 files changed, 191 insertions(+) create mode 100644 docs/devel/security-process.rst
docs/devel/index.rst +1 -0
@@ -48,3 +48,4 @@ modifying QEMU's source code. trivial-patches submitting-a-patch submitting-a-pull-request + security-process
docs/devel/security-process.rst new file +190 -0
190 lines not on this page · raw message
Signature · 1 line
2.31.1
Re: [PATCH 1/2] docs: rSTify "security-process" page; move it to QEMU Git
Quoted 6 lines · Kashyap Chamarthy
This is based on Paolo's suggestion[1] that the 'security-process'[2] page being a candidate for docs/devel.
Converted from Markdown to rST using:
Quoted 9 lines
$> pandoc -f markdown -t rst security-process.md \ -o security-process.rstIt's a 1-1 conversion (I double-checked to the best I could). I've also checked that the hyperlinks work correctly post-conversion.
[1] https://lists.nongnu.org/archive/html/qemu-devel/2021-11/msg04002.html
[2] https://www.qemu.org/contribute/security-process
thanks
-- PMM
PATCH 2/2 docs: rSTify "report-a-bug" page; move it to QEMU Git
In reply to Kashyap ChamarthyThis is also based on Paolo's suggestion[1] of "report-a-bug" page[2] from the QEMU website being a candidate for docs/devel.
Converted from Markdown to rST using:
$> pandoc -f markdown -t rst report-a-bug.md \
-o reporting-a-bug.rstModifications:
- Rename this from "report-a-bug" page to "reporting-a-bug" to be consistent with existing in-tree docs.
- Use internal rST reference to "submitting-a-patch.rst"; and slightly tweak the sentence where this is referenced.
- Also tweak the description at the top of the 'index.rst' to to reflect that the manual also documents some of QEMU's development processes.
[1] https://lists.nongnu.org/archive/html/qemu-devel/2021-11/msg04002.html
[2] https://www.qemu.org/contribute/report-a-bug/
--- docs/devel/index.rst | 8 +++++--- docs/devel/reporting-a-bug.rst | 37 ++++++++++++++++++++++++++++++++++ 2 files changed, 42 insertions(+), 3 deletions(-) create mode 100644 docs/devel/reporting-a-bug.rst
docs/devel/index.rst +5 -3
@@ -2,9 +2,10 @@ Developer Information --------------------- -This section of the manual documents various parts of the internals of QEMU. -You only need to read it if you are interested in reading or -modifying QEMU's source code. +This section of the manual documents some of QEMU's development +practises, and various internals of QEMU. These documents are +particularly useful for those interested in reading or modifying QEMU's +source code. .. toctree:: :maxdepth: 2
@@ -49,3 +50,4 @@ modifying QEMU's source code. submitting-a-patch submitting-a-pull-request security-process + reporting-a-bug
docs/devel/reporting-a-bug.rst new file +37 -0
@@ -0,0 +1,37 @@ +.. _reporting-a-bug: + +Reporting a bug +=============== + +Bugs can be filed at our `bug +tracker <https://gitlab.com/qemu-project/qemu/-/issues>`__, which is +hosted on GitLab. Note: If you’ve got a problem with how your Linux +distribution packages QEMU, please use the bug tracker from your distro +instead. + +When submitting a bug report, please try to do the following: + +- Include the QEMU release version or the git commit hash into the + description, so that it is later still clear in which version you + have found the bug. Reports against the `latest + release </download/#source>`__ or even the latest development tree + are usually acted upon faster. + +- Include the full command line used to launch the QEMU guest. + +- Reproduce the problem directly with a QEMU command-line. Avoid + frontends and management stacks, to ensure that the bug is in QEMU + itself and not in a frontend. + +- Include information about the host and guest (operating system, + version, 32/64-bit). + +QEMU does not use GitLab merge requests; patches are sent to the mailing +list according to the guidelines mentioned here: :ref:`submitting-a-patch`. + +Do **NOT** report security issues (or other bugs, too) as “confidential” +bugs in the bug tracker. QEMU has a :ref:`security-process` for issues +that should be reported in a non-public way instead. + +For problems with KVM in the kernel, use the kernel bug tracker instead; +the `KVM wiki <https://www.linux-kvm.org/page/Bugs>`__ has the details.
Signature · 1 line
2.31.1
Re: [PATCH 2/2] docs: rSTify "report-a-bug" page; move it to QEMU Git
Quoted 23 lines · Kashyap Chamarthy
This is also based on Paolo's suggestion[1] of "report-a-bug" page[2] from the QEMU website being a candidate for docs/devel.
Converted from Markdown to rST using:
$> pandoc -f markdown -t rst report-a-bug.md \ -o reporting-a-bug.rstModifications:
- Rename this from "report-a-bug" page to "reporting-a-bug" to be consistent with existing in-tree docs.
- Use internal rST reference to "
submitting-a-patch.rst"; and slightly tweak the sentence where this is referenced.- Also tweak the description at the top of the '
index.rst' to to reflect that the manual also documents some of QEMU's development processes.[1] https://lists.nongnu.org/archive/html/qemu-devel/2021-11/msg04002.html
[2] https://www.qemu.org/contribute/report-a-bug/
Quoted 7 lines
Suggested-by Paolo Bonzini <[email protected]>Signed-off-by Kashyap Chamarthy <[email protected]>--- docs/devel/index.rst | 8 +++++--- docs/devel/reporting-a-bug.rst | 37 ++++++++++++++++++++++++++++++++++ 2 files changed, 42 insertions(+), 3 deletions(-) create mode 100644 docs/devel/reporting-a-bug.rst
I don't think the bug-reporting instructions really belong in 'devel', because we would like all users to report bugs, not just developers. I think the /about/ section would be a better home for this file.
-- PMM
Re: [PATCH 2/2] docs: rSTify "report-a-bug" page; move it to QEMU Git
Quoted 1 line · Peter Maydell
On Wed, 24 Nov 2021 at 14:27, Kashyap Chamarthy <[email protected]> wrote:
[...]
Quoted 11 lines
Quoted 10 lines
[1] https://lists.nongnu.org/archive/html/qemu-devel/2021-11/msg04002.html
[2] https://www.qemu.org/contribute/report-a-bug/Suggested-by Paolo Bonzini <[email protected]>Signed-off-by Kashyap Chamarthy <[email protected]>--- docs/devel/index.rst | 8 +++++--- docs/devel/reporting-a-bug.rst | 37 ++++++++++++++++++++++++++++++++++ 2 files changed, 42 insertions(+), 3 deletions(-) create mode 100644 docs/devel/reporting-a-bug.rst
Quoted 3 lines
I don't think the bug-reporting instructions really belong in 'devel', because we would like all users to report bugs, not just developers. I think the /about/ section would be a better home for this file.
(Sorry for the slowness, I was out the last 4 days.)
Yeah; fair point. Not sure why I didn't think about it :-). I'll drop this one.
- - -
What do you think about these two pages:
https://wiki.qemu.org/Contribute/FAQ
https://wiki.qemu.org/Documentation/GettingStartedDevelopers
I think the 'Contribute/FAQ' page could be on the website, because the same argument: FAQ can be used by any contributor, not just developers. But 'GettingStartedDevelopers' can be in docs/devel/.
Let me know if you think differently.
Signature · 1 line
/kashyap