[PATCH v2 0/3] rSTify a few more docs; move them to QEMU Git

[PATCH v2 0/3] rSTify a few more docs; move them to QEMU Git

[Kashyap Chamarthy]

This series rST-ifies:

  - security-process[1]
  - MailingLists[2]
  - GettingStartedDevelopers[3]

The 'security-process' page is from the QEMU web and is moved to
docs/devel/ in QEMU Git.  This is based on Paolo's feedback here[4].
The next two docs are converted from the Wiki.

[1] https://www.qemu.org/contribute/security-process
[2] https://wiki.qemu.org/Contribute/MailingLists
[3] https://wiki.qemu.org/Documentation/GettingStartedDevelopers
[4] https://lists.nongnu.org/archive/html/qemu-devel/2021-11/msg04002.html

Kashyap Chamarthy (3):
  docs: rSTify "security-process" page; move it to QEMU Git
  docs: rSTify MailingLists wiki; move it to QEMU Git
  docs: rSTify GettingStartedDevelopers wiki; move it to QEMU Git

 docs/devel/getting-started-developers.rst | 200 ++++++++++++++++++++++
 docs/devel/index.rst                      |   3 +
 docs/devel/mailing-lists.rst              |  53 ++++++
 docs/devel/security-process.rst           | 190 ++++++++++++++++++++
 4 files changed, 446 insertions(+)
 create mode 100644 docs/devel/getting-started-developers.rst
 create mode 100644 docs/devel/mailing-lists.rst
 create mode 100644 docs/devel/security-process.rst

-- 
2.33.1

[PATCH v2 1/3] docs: rSTify "security-process" page; move it to QEMU Git

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

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

Suggested-by: Paolo Bonzini <pbonzini@redhat.com>
Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com>
Reviewed-by: Peter Maydell <peter.maydell@linaro.org>
---
 docs/devel/index.rst            |   1 +
 docs/devel/security-process.rst | 190 ++++++++++++++++++++++++++++++++
 2 files changed, 191 insertions(+)
 create mode 100644 docs/devel/security-process.rst

diff --git a/docs/devel/index.rst b/docs/devel/index.rst
index afd937535e..424eff9294 100644
--- a/docs/devel/index.rst
+++ b/docs/devel/index.rst
@@ -48,3 +48,4 @@ modifying QEMU's source code.
    trivial-patches
    submitting-a-patch
    submitting-a-pull-request
+   security-process
diff --git a/docs/devel/security-process.rst b/docs/devel/security-process.rst
new file mode 100644
index 0000000000..cc1000fe43
--- /dev/null
+++ b/docs/devel/security-process.rst
@@ -0,0 +1,190 @@
+.. _security-process:
+
+Security Process
+================
+
+Please report any suspected security issue in QEMU to the security
+mailing list at:
+
+-  `<qemu-security@nongnu.org> <https://lists.nongnu.org/mailman/listinfo/qemu-security>`__
+
+To report an issue via `GPG <https://gnupg.org/>`__ encrypted email,
+please send it to the Red Hat Product Security team at:
+
+-  `<secalert@redhat.com> <https://access.redhat.com/security/team/contact/#contact>`__
+
+**Note:** after the triage, encrypted issue details shall be sent to the
+upstream ‘qemu-security’ mailing list for archival purposes.
+
+How to report an issue
+----------------------
+
+-  Please include as many details as possible in the issue report. Ex:
+
+   -  QEMU version, upstream commit/tag
+   -  Host & Guest architecture x86/Arm/PPC, 32/64 bit etc.
+   -  Affected code area/snippets
+   -  Stack traces, crash details
+   -  Malicious inputs/reproducer steps etc.
+   -  Any configurations/settings required to trigger the issue.
+
+-  Please share the QEMU command line used to invoke a guest VM.
+
+-  Please specify whom to acknowledge for reporting this issue.
+
+How we respond
+~~~~~~~~~~~~~~
+
+-  Process of handling security issues comprises following steps:
+
+   0) **Acknowledge:**
+
+   -  A non-automated response email is sent to the reporter(s) to
+      acknowledge the reception of the report. (*60 day’s counter starts
+      here*)
+
+   1) **Triage:**
+
+   -  Examine the issue details and confirm whether the issue is genuine
+   -  Validate if it can be misused for malicious purposes
+   -  Determine its worst case impact and severity
+      [Low/Moderate/Important/Critical]
+
+   2) **Response:**
+
+   -  Negotiate embargo timeline (if required, depending on severity)
+   -  Request a `CVE <https://cveform.mitre.org/>`__ and open an
+      upstream `bug <https://www.qemu.org/contribute/report-a-bug/>`__
+   -  Create an upstream fix patch annotated with
+
+      -  CVE-ID
+      -  Link to an upstream bugzilla
+      -  Reported-by, Tested-by etc. tags
+
+   -  Once the patch is merged, close the upstream bug with a link to
+      the commit
+
+      -  Fixed in:
+
+-  Above security lists are operated by select analysts, maintainers
+   and/or representatives from downstream communities.
+
+-  List members follow a **responsible disclosure** policy. Any
+   non-public information you share about security issues, is kept
+   confidential within members of the QEMU security team and a minimal
+   supporting staff in their affiliated companies. Such information will
+   not be disclosed to third party organisations/individuals without
+   prior permission from the reporter(s).
+
+-  We aim to process security issues within maximum of **60 days**. That
+   is not to say that issues will remain private for 60 days, nope.
+   After the triaging step above
+
+   -  If severity of the issue is sufficiently low, an upstream public
+      bug will be created immediately.
+   -  If severity of the issue requires co-ordinated disclosure at a
+      future date, then the embargo process below is followed, and
+      upstream bug will be opened at the end of the embargo period.
+
+   This will allow upstream contributors to create, test and track fix
+   patch(es).
+
+Publication embargo
+~~~~~~~~~~~~~~~~~~~
+
+-  If a security issue is reported that is not already public and its
+   severity requires coordinated disclosure, then an embargo date will
+   be set and communicated to the reporter(s).
+
+-  Embargo periods will be negotiated by mutual agreement between
+   reporter(s), members of the security list and other relevant parties
+   to the problem. The preferred embargo period is upto `2
+   weeks <https://oss-security.openwall.org/wiki/mailing-lists/distros>`__.
+   However, longer embargoes may be negotiated if the severity of the
+   issue requires it.
+
+-  Members of the security list agree not to publicly disclose any
+   details of an embargoed security issue until its embargo date
+   expires.
+
+CVE allocation
+~~~~~~~~~~~~~~
+
+Each security issue is assigned a `CVE <https://cveform.mitre.org/>`__
+number. The CVE number is allocated by one of the vendor security
+engineers on the security list.
+
+When to contact the QEMU Security List
+--------------------------------------
+
+You should contact the Security List if: \* You think there may be a
+security vulnerability in QEMU. \* You are unsure about how a known
+vulnerability affects QEMU. \* You can contact us in English. We are
+unable to respond in other languages.
+
+When *not* to contact the QEMU Security List
+--------------------------------------------
+
+-  You need assistance in a language other than English.
+-  You require technical assistance (for example, “how do I configure
+   QEMU?”).
+-  You need help upgrading QEMU due to security alerts.
+-  Your issue is not security related.
+
+How impact and severity of a bug is decided
+-------------------------------------------
+
+**Security criterion:** ->
+https://www.qemu.org/docs/master/system/security.html
+
+All security issues in QEMU are not equal. Based on the parts of the
+QEMU sources wherein the bug is found, its impact and severity could
+vary.
+
+In particular, QEMU is used in many different scenarios; some of them
+assume that the guest is trusted, some of them don’t. General
+considerations to triage QEMU issues and decide whether a configuration
+is security sensitive include:
+
+-  Is there any feasible way for a malicious party to exploit this flaw
+   and cause real damage? (e.g. from a guest or via downloadable images)
+-  Does the flaw require access to the management interface? Would the
+   management interface be accessible in the scenario where the flaw
+   could cause real damage?
+-  Is QEMU used in conjunction with a hypervisor (as opposed to TCG
+   binary translation)?
+-  Is QEMU used to offer virtualised production services, as opposed to
+   usage as a development platform?
+
+Whenever some or all of these questions have negative answers, what
+appears to be a major security flaw might be considered of low severity
+because it could only be exercised in use cases where QEMU and
+everything interacting with it is trusted.
+
+For example, consider upstream commit `9201bb9 “sdhci.c: Limit the
+maximum block
+size” <https://gitlab.com/qemu-project/qemu/-/commit/9201bb9>`__, an of
+out of bounds (OOB) memory access (ie. buffer overflow) issue that was
+found and fixed in the SD Host Controller emulation (hw/sd/sdhci.c).
+
+On the surface, this bug appears to be a genuine security flaw, with
+potentially severe implications. But digging further down, there are
+only two ways to use SD Host Controller emulation, one is via
+‘sdhci-pci’ interface and the other is via ‘generic-sdhci’ interface.
+
+Of these two, the ‘sdhci-pci’ interface had actually been disabled by
+default in the upstream QEMU releases (commit `1910913 “sdhci: Make
+device”sdhci-pci" unavailable with
+-device" <https://gitlab.com/qemu-project/qemu/-/commit/1910913>`__ at
+the time the flaw was reported; therefore, guests could not possibly use
+‘sdhci-pci’ for any purpose.
+
+The ‘generic-sdhci’ interface, instead, had only one user in ‘Xilinx
+Zynq Baseboard emulation’ (hw/arm/xilinx_zynq.c). Xilinx Zynq is a
+programmable systems on chip (SoC) device. While QEMU does emulate this
+device, in practice it is used to facilitate cross-platform
+developmental efforts, i.e. QEMU is used to write programs for the SoC
+device. In such developer environments, it is generally assumed that the
+guest is trusted.
+
+And thus, this buffer overflow turned out to be a security non-issue.
-- 
2.33.1

Re: [PATCH v2 1/3] docs: rSTify "security-process" page; move it to QEMU Git

[Thomas Huth]

On 14/03/2022 11.49, Kashyap Chamarthy wrote:
> 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
> 
> Suggested-by: Paolo Bonzini <pbonzini@redhat.com>
> Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com>
> Reviewed-by: Peter Maydell <peter.maydell@linaro.org>
> ---
>   docs/devel/index.rst            |   1 +
>   docs/devel/security-process.rst | 190 ++++++++++++++++++++++++++++++++
>   2 files changed, 191 insertions(+)
>   create mode 100644 docs/devel/security-process.rst
> 
> diff --git a/docs/devel/index.rst b/docs/devel/index.rst
> index afd937535e..424eff9294 100644
> --- a/docs/devel/index.rst
> +++ b/docs/devel/index.rst
> @@ -48,3 +48,4 @@ modifying QEMU's source code.
>      trivial-patches
>      submitting-a-patch
>      submitting-a-pull-request
> +   security-process
> diff --git a/docs/devel/security-process.rst b/docs/devel/security-process.rst
> new file mode 100644
> index 0000000000..cc1000fe43
> --- /dev/null
> +++ b/docs/devel/security-process.rst
> @@ -0,0 +1,190 @@
> +.. _security-process:
> +
> +Security Process
> +================
> +
> +Please report any suspected security issue in QEMU to the security
> +mailing list at:
> +
> +-  `<qemu-security@nongnu.org> <https://lists.nongnu.org/mailman/listinfo/qemu-security>`__
> +
> +To report an issue via `GPG <https://gnupg.org/>`__ encrypted email,
> +please send it to the Red Hat Product Security team at:
> +
> +-  `<secalert@redhat.com> <https://access.redhat.com/security/team/contact/#contact>`__
> +
> +**Note:** after the triage, encrypted issue details shall be sent to the
> +upstream ‘qemu-security’ mailing list for archival purposes.
> +
> +How to report an issue
> +----------------------
> +
> +-  Please include as many details as possible in the issue report. Ex:
> +
> +   -  QEMU version, upstream commit/tag
> +   -  Host & Guest architecture x86/Arm/PPC, 32/64 bit etc.
> +   -  Affected code area/snippets
> +   -  Stack traces, crash details
> +   -  Malicious inputs/reproducer steps etc.
> +   -  Any configurations/settings required to trigger the issue.
> +
> +-  Please share the QEMU command line used to invoke a guest VM.
> +
> +-  Please specify whom to acknowledge for reporting this issue.
> +
> +How we respond
> +~~~~~~~~~~~~~~
> +
> +-  Process of handling security issues comprises following steps:
> +
> +   0) **Acknowledge:**
> +
> +   -  A non-automated response email is sent to the reporter(s) to
> +      acknowledge the reception of the report. (*60 day’s counter starts
> +      here*)
> +
> +   1) **Triage:**
> +
> +   -  Examine the issue details and confirm whether the issue is genuine
> +   -  Validate if it can be misused for malicious purposes
> +   -  Determine its worst case impact and severity
> +      [Low/Moderate/Important/Critical]
> +
> +   2) **Response:**
> +
> +   -  Negotiate embargo timeline (if required, depending on severity)
> +   -  Request a `CVE <https://cveform.mitre.org/>`__ and open an
> +      upstream `bug <https://www.qemu.org/contribute/report-a-bug/>`__
> +   -  Create an upstream fix patch annotated with
> +
> +      -  CVE-ID
> +      -  Link to an upstream bugzilla
> +      -  Reported-by, Tested-by etc. tags
> +
> +   -  Once the patch is merged, close the upstream bug with a link to
> +      the commit
> +
> +      -  Fixed in:

There used to be a "<commit hash/link>" after that "Fixed in" on the 
original page, seems like you've lost that somewhere along the way?

Anyway, I'd like to hear from the security folks whether they are OK with 
moving this page to the main git repo, or whether it rather should stay in 
the qemu-web repo.

  Thomas

Re: [PATCH v2 1/3] docs: rSTify "security-process" page; move it to QEMU Git

[Kashyap Chamarthy]

On Tue, Mar 15, 2022 at 01:47:38PM +0100, Thomas Huth wrote:
> On 14/03/2022 11.49, Kashyap Chamarthy wrote:

[...]

> > +   -  Once the patch is merged, close the upstream bug with a link to
> > +      the commit
> > +
> > +      -  Fixed in:
> 
> There used to be a "<commit hash/link>" after that "Fixed in" on the
> original page, seems like you've lost that somewhere along the way?

Ouch, Pandoc seems to have eaten it during conversion, because of "< >"?
(But it didn't eat "<qemu-security@nongnu.org>" or
"<secalert@redhat.com>" at the top ... probably because they're
hyperlinks.)  Anyway, I'll add it back in v2.

Thanks for the eagle eyes!
 
> Anyway, I'd like to hear from the security folks whether they are OK with
> moving this page to the main git repo, or whether it rather should stay in
> the qemu-web repo.

Sure.

-- 
/kashyap

[PATCH v2 2/3] docs: rSTify MailingLists wiki; move it to QEMU Git

[Kashyap Chamarthy]

This document is referred to from the GettingStartedDevelopers wiki
which will be rSTified in a follow-up commit.

Converted from Mediawiki to rST using:

    $> pandoc -f Mediawiki -t rst MailingLists.wiki
        -o mailing-lists.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.

Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com>
---
 docs/devel/index.rst         |  1 +
 docs/devel/mailing-lists.rst | 53 ++++++++++++++++++++++++++++++++++++
 2 files changed, 54 insertions(+)
 create mode 100644 docs/devel/mailing-lists.rst

diff --git a/docs/devel/index.rst b/docs/devel/index.rst
index 424eff9294..fb9d9f3a80 100644
--- a/docs/devel/index.rst
+++ b/docs/devel/index.rst
@@ -12,6 +12,7 @@ modifying QEMU's source code.
 
    code-of-conduct
    conflict-resolution
+   mailing-lists
    build-system
    style
    kconfig
diff --git a/docs/devel/mailing-lists.rst b/docs/devel/mailing-lists.rst
new file mode 100644
index 0000000000..53dcbfb007
--- /dev/null
+++ b/docs/devel/mailing-lists.rst
@@ -0,0 +1,53 @@
+.. _mailing-lists:
+
+Mailing lists
+=============
+
+-  `QEMU developers mailing
+   list <http://lists.nongnu.org/mailman/listinfo/qemu-devel>`__
+-  `QEMU stable mailing
+   list <http://lists.nongnu.org/mailman/listinfo/qemu-stable>`__
+-  `QEMU trivial patch mailing
+   list <http://lists.nongnu.org/mailman/listinfo/qemu-trivial>`__
+-  `QEMU users mailing
+   list <http://lists.nongnu.org/mailman/listinfo/qemu-discuss>`__
+
+.. _subsystem_specific_lists:
+
+Subsystem Specific Lists
+------------------------
+
+These exist to make it a little easier to follow subsystem specific
+patches. You should however continue to CC qemu-devel so your series
+gets wide visibility.
+
+-  `QEMU ARM mailing
+   list <https://lists.nongnu.org/mailman/listinfo/qemu-arm>`__
+-  `QEMU block devices mailing
+   list <https://lists.nongnu.org/mailman/listinfo/qemu-block>`__
+-  `QEMU PowerPC mailing
+   list <https://lists.nongnu.org/mailman/listinfo/qemu-ppc>`__
+-  `QEMU RISC-V mailing
+   list <https://lists.nongnu.org/mailman/listinfo/qemu-riscv>`__
+-  `QEMU s390x mailing
+   list <https://lists.nongnu.org/mailman/listinfo/qemu-s390x>`__
+
+If a subsystem maintainer thinks that a new mailing list for their
+subsystem would make life easier, we're happy to create one -- mail
+qemu-devel to suggest it (ideally cc'ing the people listed as Savannah
+project admins in our `AdminContacts <AdminContacts>`__ page, as they
+are the ones with the ability to make the change).
+
+If you are a Savannah project admin, you may want the `technical notes
+on how to create and configure a new
+list <Contribute/MailingLists/Creation>`__.
+
+.. _access_via_lore.kernel.org:
+
+Access via lore.kernel.org
+--------------------------
+
+The qemu-devel mailing list is also archived via
+`public-inbox <https://public-inbox.org/>`__ on
+https://lore.kernel.org/qemu-devel/ and accessible via NNTP at
+nntp.lore.kernel.org (newsgroup org.nongnu.qemu-devel).
-- 
2.33.1

Re: [PATCH v2 2/3] docs: rSTify MailingLists wiki; move it to QEMU Git

[Philippe Mathieu-Daudé]

Hi Kashyap,

On 14/3/22 11:49, Kashyap Chamarthy wrote:
> This document is referred to from the GettingStartedDevelopers wiki
> which will be rSTified in a follow-up commit.
> 
> Converted from Mediawiki to rST using:
> 
>      $> pandoc -f Mediawiki -t rst MailingLists.wiki
>          -o mailing-lists.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.
> 
> Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com>
> ---
>   docs/devel/index.rst         |  1 +
>   docs/devel/mailing-lists.rst | 53 ++++++++++++++++++++++++++++++++++++
>   2 files changed, 54 insertions(+)
>   create mode 100644 docs/devel/mailing-lists.rst

> diff --git a/docs/devel/mailing-lists.rst b/docs/devel/mailing-lists.rst
> new file mode 100644
> index 0000000000..53dcbfb007
> --- /dev/null
> +++ b/docs/devel/mailing-lists.rst
> @@ -0,0 +1,53 @@
> +.. _mailing-lists:
> +
> +Mailing lists
> +=============
> +
> +-  `QEMU developers mailing
> +   list <http://lists.nongnu.org/mailman/listinfo/qemu-devel>`__
> +-  `QEMU stable mailing
> +   list <http://lists.nongnu.org/mailman/listinfo/qemu-stable>`__
> +-  `QEMU trivial patch mailing
> +   list <http://lists.nongnu.org/mailman/listinfo/qemu-trivial>`__
> +-  `QEMU users mailing
> +   list <http://lists.nongnu.org/mailman/listinfo/qemu-discuss>`__

This is a fair conversion from 
https://wiki.qemu.org/Contribute/MailingLists, but a good opportunity to 
improve (could be on top).

We could sort as:

  * qemu-discuss

    Meant for users. Ideally help should point at Documentation link,
    and in case of missing doc we should add it or at least a GitLab
    @Documentation ticket.

  * qemu-devel

    Meant for developers. "All patches must be sent there".

    Then developer sub-lists:

    - qemu-trivial

    - qemu-stable (this is kinda borderline, security issue fixes should
      Cc this list, however it has to be treated as a write-only list
      - a way to tag patches - no discussion happens there).

    - susbsystem specific

      > block layer

      > architecture specific

        . ARM
        . PPC
        . ...

> +.. _subsystem_specific_lists:
> +
> +Subsystem Specific Lists
> +------------------------
> +
> +These exist to make it a little easier to follow subsystem specific
> +patches. You should however continue to CC qemu-devel so your series
> +gets wide visibility.
> +
> +-  `QEMU ARM mailing
> +   list <https://lists.nongnu.org/mailman/listinfo/qemu-arm>`__
> +-  `QEMU block devices mailing
> +   list <https://lists.nongnu.org/mailman/listinfo/qemu-block>`__
> +-  `QEMU PowerPC mailing
> +   list <https://lists.nongnu.org/mailman/listinfo/qemu-ppc>`__
> +-  `QEMU RISC-V mailing
> +   list <https://lists.nongnu.org/mailman/listinfo/qemu-riscv>`__
> +-  `QEMU s390x mailing
> +   list <https://lists.nongnu.org/mailman/listinfo/qemu-s390x>`__

Re: [PATCH v2 2/3] docs: rSTify MailingLists wiki; move it to QEMU Git

[Kashyap Chamarthy]

On Mon, Mar 14, 2022 at 02:45:30PM +0100, Philippe Mathieu-Daudé wrote:
> Hi Kashyap,

Hi,

> On 14/3/22 11:49, Kashyap Chamarthy wrote:

[...]

> This is a fair conversion from
> https://wiki.qemu.org/Contribute/MailingLists, but a good opportunity to
> improve (could be on top).

Yeah, definitely.  I'll make a TODO to add it on top.  (I didn't wanted
to mix in content edits with conversion changes, as it puts additional
burden on the reviewers.)

> We could sort as:
> 
>  * qemu-discuss
> 
>    Meant for users. Ideally help should point at Documentation link,
>    and in case of missing doc we should add it or at least a GitLab
>    @Documentation ticket.
> 
>  * qemu-devel
> 
>    Meant for developers. "All patches must be sent there".
> 
>    Then developer sub-lists:
> 
>    - qemu-trivial
> 
>    - qemu-stable (this is kinda borderline, security issue fixes should
>      Cc this list, however it has to be treated as a write-only list
>      - a way to tag patches - no discussion happens there).

Nit: The term "kinda boderline" here can mean anything from "its
purpose is questionable" to "it is used for unintended purposes", etc.
Let's avoid vague phrasing in public-facing text.  We can just be
descriptive of what the purpose of the list is. :-)

Thanks for the review!

>    - susbsystem specific
> 
>      > block layer
> 
>      > architecture specific
> 
>        . ARM
>        . PPC
>        . ...

[...]


-- 
/kashyap

Re: [PATCH v2 2/3] docs: rSTify MailingLists wiki; move it to QEMU Git

[Thomas Huth]

On 14/03/2022 11.49, Kashyap Chamarthy wrote:
> This document is referred to from the GettingStartedDevelopers wiki
> which will be rSTified in a follow-up commit.
> 
> Converted from Mediawiki to rST using:
> 
>      $> pandoc -f Mediawiki -t rst MailingLists.wiki
>          -o mailing-lists.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.
> 
> Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com>
> ---
>   docs/devel/index.rst         |  1 +
>   docs/devel/mailing-lists.rst | 53 ++++++++++++++++++++++++++++++++++++
>   2 files changed, 54 insertions(+)
>   create mode 100644 docs/devel/mailing-lists.rst
> 
> diff --git a/docs/devel/index.rst b/docs/devel/index.rst
> index 424eff9294..fb9d9f3a80 100644
> --- a/docs/devel/index.rst
> +++ b/docs/devel/index.rst
> @@ -12,6 +12,7 @@ modifying QEMU's source code.
>   
>      code-of-conduct
>      conflict-resolution
> +   mailing-lists
>      build-system
>      style
>      kconfig
> diff --git a/docs/devel/mailing-lists.rst b/docs/devel/mailing-lists.rst
> new file mode 100644
> index 0000000000..53dcbfb007
> --- /dev/null
> +++ b/docs/devel/mailing-lists.rst

At least the "users" mailing list is not related to development, so maybe 
this should rather go into docs/about/ instead?

Anyway:

Reviewed-by: Thomas Huth <thuth@redhat.com>

Re: [PATCH v2 2/3] docs: rSTify MailingLists wiki; move it to QEMU Git

[Kashyap Chamarthy]

On Tue, Mar 15, 2022 at 02:25:05PM +0100, Thomas Huth wrote:
> On 14/03/2022 11.49, Kashyap Chamarthy wrote:

[...]

> At least the "users" mailing list is not related to development, so maybe
> this should rather go into docs/about/ instead?

Yeah, makes sense.  I wonder if should create a new doc in docs/about/
for user-lists, as none of the existing docs fit the bill:

    build-platforms.rst  deprecated.rst  index.rst license.rst
    removed-features.rst

> Anyway:
> 
> Reviewed-by: Thomas Huth <thuth@redhat.com>

Thank you.

Related: I just sent the below patch to the list and Cced you (it hasn't
yet appeared on the archives as of this writing):

    "docs/devel: Fix broken internal link to mailing lists"

The above should be merged on top of the current patch[1] you've just
reviewed.  Otherwise Sphinx will complain (correctly so).
    

[1] https://lists.nongnu.org/archive/html/qemu-devel/2022-03/msg03488.html
    -- docs: rSTify MailingLists wiki; move it to QEMU Git



-- 
/kashyap

Re: [PATCH v2 2/3] docs: rSTify MailingLists wiki; move it to QEMU Git

[Peter Maydell]

On Tue, 15 Mar 2022 at 16:00, Kashyap Chamarthy <kchamart@redhat.com> wrote:
>
> On Tue, Mar 15, 2022 at 02:25:05PM +0100, Thomas Huth wrote:
> > On 14/03/2022 11.49, Kashyap Chamarthy wrote:
>
> [...]
>
> > At least the "users" mailing list is not related to development, so maybe
> > this should rather go into docs/about/ instead?
>
> Yeah, makes sense.  I wonder if should create a new doc in docs/about/
> for user-lists, as none of the existing docs fit the bill:
>
>     build-platforms.rst  deprecated.rst  index.rst license.rst
>     removed-features.rst

Yes, I think that about/ should have a document something like
"Contacting the project" or "Support", which could tell users about not just
the user-facing mailing lists but also where to file bugs, and so on.

In fact, it should probably look rather like the
https://www.qemu.org/support/ page...

-- PMM

Re: [PATCH v2 2/3] docs: rSTify MailingLists wiki; move it to QEMU Git

[Kashyap Chamarthy]

On Tue, Mar 15, 2022 at 04:12:50PM +0000, Peter Maydell wrote:
> On Tue, 15 Mar 2022 at 16:00, Kashyap Chamarthy <kchamart@redhat.com> wrote:
> >
> > On Tue, Mar 15, 2022 at 02:25:05PM +0100, Thomas Huth wrote:
> > > On 14/03/2022 11.49, Kashyap Chamarthy wrote:
> >
> > [...]
> >
> > > At least the "users" mailing list is not related to development, so maybe
> > > this should rather go into docs/about/ instead?
> >
> > Yeah, makes sense.  I wonder if should create a new doc in docs/about/
> > for user-lists, as none of the existing docs fit the bill:
> >
> >     build-platforms.rst  deprecated.rst  index.rst license.rst
> >     removed-features.rst
> 
> Yes, I think that about/ should have a document something like
> "Contacting the project" or "Support", which could tell users about not just
> the user-facing mailing lists but also where to file bugs, and so on.
> 
> In fact, it should probably look rather like the
> https://www.qemu.org/support/ page...

Heh, thanks, I missed that page.  So, if I parsed you right, you're
implying, given the above qemu-web page, there's no need for a separate
about/support.rst doc.

-- 
/kashyap

Re: [PATCH v2 2/3] docs: rSTify MailingLists wiki; move it to QEMU Git

[Peter Maydell]

On Mon, 21 Mar 2022 at 09:55, Kashyap Chamarthy <kchamart@redhat.com> wrote:
>
> On Tue, Mar 15, 2022 at 04:12:50PM +0000, Peter Maydell wrote:
> > On Tue, 15 Mar 2022 at 16:00, Kashyap Chamarthy <kchamart@redhat.com> wrote:
> > >
> > > On Tue, Mar 15, 2022 at 02:25:05PM +0100, Thomas Huth wrote:
> > > > On 14/03/2022 11.49, Kashyap Chamarthy wrote:
> > >
> > > [...]
> > >
> > > > At least the "users" mailing list is not related to development, so maybe
> > > > this should rather go into docs/about/ instead?
> > >
> > > Yeah, makes sense.  I wonder if should create a new doc in docs/about/
> > > for user-lists, as none of the existing docs fit the bill:
> > >
> > >     build-platforms.rst  deprecated.rst  index.rst license.rst
> > >     removed-features.rst
> >
> > Yes, I think that about/ should have a document something like
> > "Contacting the project" or "Support", which could tell users about not just
> > the user-facing mailing lists but also where to file bugs, and so on.
> >
> > In fact, it should probably look rather like the
> > https://www.qemu.org/support/ page...
>
> Heh, thanks, I missed that page.  So, if I parsed you right, you're
> implying, given the above qemu-web page, there's no need for a separate
> about/support.rst doc.

I think there is some merit in the documentation being standalone,
even if it does mean a bit of duplication with the website.

-- PMM

Re: [PATCH v2 2/3] docs: rSTify MailingLists wiki; move it to QEMU Git

[Kashyap Chamarthy]

On Mon, Mar 21, 2022 at 11:01:28AM +0000, Peter Maydell wrote:
> On Mon, 21 Mar 2022 at 09:55, Kashyap Chamarthy <kchamart@redhat.com> wrote:

[...]

> > > Yes, I think that about/ should have a document something like
> > > "Contacting the project" or "Support", which could tell users about not just
> > > the user-facing mailing lists but also where to file bugs, and so on.
> > >
> > > In fact, it should probably look rather like the
> > > https://www.qemu.org/support/ page...
> >
> > Heh, thanks, I missed that page.  So, if I parsed you right, you're
> > implying, given the above qemu-web page, there's no need for a separate
> > about/support.rst doc.
> 
> I think there is some merit in the documentation being standalone,
> even if it does mean a bit of duplication with the website.

Yeah, fair point.  I'll add an appropriate page as part of v2.  Thanks
for the quick feedback.

-- 
/kashyap

[PATCH v2 3/3] docs: rSTify GettingStartedDevelopers wiki; move it to QEMU Git

[Kashyap Chamarthy]

Converted the wiki[1] from Markdown to rST using:

    $> pandoc -f Mediawiki -t rst getting-started-developers.wiki
        -o getting-started-developers.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://wiki.qemu.org/Documentation/GettingStartedDevelopers

Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com>
---
 docs/devel/getting-started-developers.rst | 200 ++++++++++++++++++++++
 docs/devel/index.rst                      |   1 +
 2 files changed, 201 insertions(+)
 create mode 100644 docs/devel/getting-started-developers.rst

diff --git a/docs/devel/getting-started-developers.rst b/docs/devel/getting-started-developers.rst
new file mode 100644
index 0000000000..1299e1dfee
--- /dev/null
+++ b/docs/devel/getting-started-developers.rst
@@ -0,0 +1,200 @@
+.. _getting-started-developers:
+
+Getting Started for Developers
+==============================
+
+You want to contribute code, documentation or patches to QEMU?
+
+Then...
+
+-  ... you should probably first join the :ref:`mailing-lists`.
+
+   -  Mailing lists are moderated. Non-subscribers may post, so list
+      policy is reply-to-all to ensure original poster is included.
+   -  Be prepared for upwards of one thousand messages per week if you
+      subscribe.
+   -  First-time posts (whether subscribed or not) are subject to a
+      moderation delay until a human can whitelist your email address.
+
+-  Also check out the `patch
+   submission <https://www.qemu.org/docs/master/devel/submitting-a-patch.html>`__
+   page for some hints on mail contributions.
+
+Wiki
+----
+
+-  To create an account in the QEMU wiki, you must ask on the mailing
+   list for someone else to do it on your behalf (self-creation is
+   prohibited to cut down on spam accounts).
+-  Start with reading the QEMU wiki.
+-  Contribute to the QEMU wiki by adding new topics or improving and
+   expanding existing topics. It should help you and others in the
+   future.
+
+Documentation
+-------------
+
+-  Continue with reading the `existing documentation <Documentation>`__
+   and `Contributions Guide <Contribute>`__.
+
+   Be prepared that all written documentation might be invalid - either
+   because it is too old or because it was never correct. And it is
+   never complete...
+
+-  If you find bugs in the documentation then fix them and send patches
+   to the mailing list. See
+   `Contribute/ReportABug <Contribute/ReportABug>`__.
+-  If you find problems in the wiki, then fix them if you can, or add
+   notes to either the applicable page or the Discussion page.
+-  Depending on how much computer architecture / hardware background you
+   have, it may help to read some general books. Suggestions include:
+
+   -  "Computers as Components, Second Edition: Principles of Embedded
+      Computing System Design", Wayne Wolf, ISBN-13: 978-0123743978
+
+Code
+----
+
+-  Get the code. If you want to be a developer, you almost certainly
+   want to be building from git (see the
+   `Download <http://www.qemu-project.org/download/#source>`__ page for
+   the right tree).
+-  Compile the code. Here are some instructions how to do this:
+
+   -  `QEMU on Linux hosts <Hosts/Linux>`__
+   -  `QEMU on OS X (macOS) hosts <Hosts/Mac>`__
+   -  `QEMU on Windows hosts <Hosts/W32>`__
+
+-  Run the QEMU system and user mode emulation for different targets
+   (x86, mips, powerpc, ...). Images can be obtained from the
+   `Testing <Testing>`__ page.
+-  QEMU has a lot of different parts (hardware device emulation, target
+   emulation, code generation for different hosts, configuration, ...).
+
+   -  Choose an interesting part and concentrate on it for some time and
+      read the code. Its going to take some effort, so try to find
+      something that you are really interested in - something that will
+      be a least a little bit fun for you.
+   -  It will be easier if you choose a part of the code that has an
+      active / responsive maintainer (since this gives you someone to
+      discuss things with).
+
+-  If you find bugs in the code, then fix them and send a patch to the
+   mailing list (see `patch submission
+   process <https://www.qemu.org/docs/master/devel/submitting-a-patch.html>`__)
+
+   -  Patches need to go the mailing list, and possibly also to a
+      specific maintainer (read the MAINTAINERS text file in the top of
+      the source code tree).
+   -  Read the HACKING and CODING_STYLE text files (in the top of the
+      source code tree) before writing the patch
+   -  Run your patch through the . See
+      http://blog.vmsplice.net/2011/03/how-to-automatically-run-checkpatchpl.html
+      for how to hook it into git.
+   -  For very small, simple changes, you can do it as a single patch.
+      If your change is more complex, you need to break it into smaller,
+      separate patches (which together form a set of patches, or a
+      patchset). Each step in the patch process can rely on previous
+      patches, but not later patches - otherwise "git bisect" will
+      break. This will require more effort on your part, but it saves a
+      lot of work for everyone else.
+   -  If you have a lot of patches in a patchset (say five or more),
+      then it may help to have a public git tree. You can get hosting
+      from many places (repo.or.cz and github seem popular).
+
+.. _getting_to_know_the_code:
+
+Getting to know the code
+------------------------
+
+-  QEMU does not have a high level design description document - only
+   the source code tells the full story.
+-  There are some useful (although usually dated) descriptions for
+   infrastructure code in various parts of the wiki, and sometimes in
+   mailing list descriptions:
+
+   -  Tracing framework is described at
+      `Features/Tracing <Features/Tracing>`__ and in docs/tracing.txt in
+      the source tree.
+   -  Some of the internal functionality (and a bit of the human
+      monitoring / control interface) is implemented in
+      `QAPI <Features/QAPI>`__ and `QMP <Documentation/QMP>`__. See also
+      https://www.linux-kvm.org/images/1/17/2010-forum-qmp-status-talk.pp.pdf
+   -  If you're into devices (new virtual hardware) it will help to know
+      about QDEV:
+      http://www.linux-kvm.org/images/f/fe/2010-forum-armbru-qdev.pdf
+      and docs/qdev-device-use.txt in the source tree
+
+-  Things do change -- we improve our APIs and develop better ways of
+   doing things all the time. Reading the mailing list is important to
+   keep on top of these changes. You may also find the
+   `DeveloperNews <DeveloperNews>`__ wiki page a useful summary. We try
+   to track API and design changes currently in progress on the
+   `ToDo/CodeTransitions <ToDo/CodeTransitions>`__ page; this may help
+   you avoid accidentally copying existing code which is out-of-date or
+   no longer following best practices.
+
+   -  We also maintain a list of
+      `Contribute/BiteSizedTasks <Contribute/BiteSizedTasks>`__ that can
+      help
+
+getting familiar with the code, and complete those transitions to make
+things easier for the next person!
+
+-  QEMU converts instructions in the guest system into instructions on
+   the host system via Tiny Code Generator (TCG). See tcg/README in the
+   source tree as a starting point if you want to understand this.
+-  Some of QEMU makes extensive use of pre-processor operations
+   (especially token pasting with ## operation) which can make it harder
+   to determine where a particular function comes from. Mulyadi Santosa
+   pointed out that you can use the gcc "--save-temps" option to see the
+   results of the pre-processor stage - see
+   http://the-hydra.blogspot.com/2011/04/getting-confused-when-exploring-qemu.html
+   for more detail.
+
+Bugs
+----
+
+-  Read the Bug Tracker.
+-  Check for topics in it for which you feel capable of handling and try
+   to fix the issue. Send patches.
+
+.. _testing_your_changes:
+
+Testing your changes
+--------------------
+
+-  You must compile test for all targets (i.e. don't restrict the
+   target-list at configure time). Make sure its a clean build if you
+   are not sure.
+-  Think about what you've changed (review the patches) and do testing
+   consistent with those changes. For example:
+
+   -  If you've developed a new driver (say an AHCI virtual device -
+      used for SATA disks), make sure that it works. Make sure anything
+      related still works (e.g. for AHCI, check the IDE driver, and no
+      disk configurations). If your new device supports migration, make
+      sure migration and snapshots work.
+   -  If you're working on Xen Hardware Virtual Machine (HVM - full
+      virtualization), then make sure that Xen para-virtualization
+      works.
+
+-  Its OK if your new implementation doesn't do everything (or has some
+   deficiencies / bugs). You do need to declare that in the patch
+   submission though.
+-  Main page for testing resources: `Testing <Testing>`__
+
+.. _getting_help:
+
+Getting Help
+------------
+
+-  IRC might be useful
+
+   -  The #qemu channel is on irc://irc.oftc.net (note: no longer on
+      Freenode).
+   -  You may also get a response on the #kvm channel on
+      irc://irc.freenode.net
+
+Please don't post large text dumps on IRC. Use a pastebin service to
+post logs so the channel doesn't get flooded.
diff --git a/docs/devel/index.rst b/docs/devel/index.rst
index fb9d9f3a80..afead67200 100644
--- a/docs/devel/index.rst
+++ b/docs/devel/index.rst
@@ -13,6 +13,7 @@ modifying QEMU's source code.
    code-of-conduct
    conflict-resolution
    mailing-lists
+   getting-started-developers
    build-system
    style
    kconfig
-- 
2.33.1