Skip to contentSkip to conversation

rSTify 'report-a-bug' and 'security-process'; move them to QEMU Git

PATCH Superseded Kashyap Chamarthy 2 participants 6 messages Nov 24, 2021 – Dec 3, 2021

v1 of 3 Superseded Latest is v3 →

lore
Share & tools
lore
#0 lore raw

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
#1 lore raw

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

It'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
index afd937535e..424eff9294 100644
@@ -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
Reviewed-by on v1 1/2
#2 lore raw

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

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

#3 lore raw

PATCH 2/2 docs: rSTify "report-a-bug" page; move it to QEMU Git

In reply to 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.rst

Modifications:

- 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
index 424eff9294..39797679de 100644
@@ -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
new file mode 100644
index 0000000000..a72f91caf4
@@ -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
#4 lore raw

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

Modifications:

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

#5 lore raw

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/

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