[PATCH v3 0/4] In v3:

[PATCH v3 0/4] In v3:

[Kashyap Chamarthy]

- Add back the "<commit hash/link>" fragment in security-process.rst
  [Thomas]
- Add a docs/about/contacting-the-project.rst as per Peter's feedback
  here:
  https://lists.nongnu.org/archive/html/qemu-devel/2022-03/msg05178.html
  [pm215]
- Keep Thomas' R-by for "docs: rSTify MailingLists wiki; move it to QEMU
  Git"

v2 cover letter:
-----------------------------------------------------------------------
rSTify a few more docs; move them to QEMU Git

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 (4):
  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
  Add a new doc "contacting-the-project.rst"

 docs/about/contacting-the-project.rst     |  16 ++
 docs/about/index.rst                      |   1 +
 docs/devel/getting-started-developers.rst | 200 ++++++++++++++++++++++
 docs/devel/index.rst                      |   3 +
 docs/devel/mailing-lists.rst              |  51 ++++++
 docs/devel/security-process.rst           | 190 ++++++++++++++++++++
 6 files changed, 461 insertions(+)
 create mode 100644 docs/about/contacting-the-project.rst
 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.36.1

[PATCH v3 1/4] 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..965d11f588
--- /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: <commit hash/link>
+
+-  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.36.1

[PATCH v3 2/4] 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

The only change in this coversion is that I have removed the users
mailing list, as it will be referred to from a different document from
the docs/about/ directory.

Besides that, this is almost 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>
Reviewed-by: Thomas Huth <thuth@redhat.com>
---
 docs/devel/index.rst         |  1 +
 docs/devel/mailing-lists.rst | 51 ++++++++++++++++++++++++++++++++++++
 2 files changed, 52 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..4533179f1f
--- /dev/null
+++ b/docs/devel/mailing-lists.rst
@@ -0,0 +1,51 @@
+.. _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>`__
+
+.. _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.36.1

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

[Alistair Francis]

On Tue, Jun 7, 2022 at 2:46 AM Kashyap Chamarthy <kchamart@redhat.com> 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
>
> The only change in this coversion is that I have removed the users
> mailing list, as it will be referred to from a different document from
> the docs/about/ directory.
>
> Besides that, this is almost 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>
> Reviewed-by: Thomas Huth <thuth@redhat.com>

Reviewed-by: Alistair Francis <alistair.francis@wdc.com>

Alistair

> ---
>  docs/devel/index.rst         |  1 +
>  docs/devel/mailing-lists.rst | 51 ++++++++++++++++++++++++++++++++++++
>  2 files changed, 52 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..4533179f1f
> --- /dev/null
> +++ b/docs/devel/mailing-lists.rst
> @@ -0,0 +1,51 @@
> +.. _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>`__
> +
> +.. _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.36.1
>
>

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

[Thomas Huth]

On 06/06/2022 18.43, 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
> 
> The only change in this coversion is that I have removed the users
> mailing list, as it will be referred to from a different document from
> the docs/about/ directory.

Which document? I didn't spot it in the other two patches...?

  Thomas

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

[Kashyap Chamarthy]

[-- Attachment #1: Type: text/plain, Size: 1133 bytes --]

Hi,

On Wednesday, June 8, 2022, Thomas Huth <thuth@redhat.com> wrote:

> On 06/06/2022 18.43, 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
>>
>> The only change in this coversion is that I have removed the users
>> mailing list, as it will be referred to from a different document from
>> the docs/about/ directory.
>>
>
> Which document? I didn't spot it in the other two patches...?


I was referring to the "contacting-the-project.rst" doc.
You're right in that it doesn't explicitly point to the users list. I
omitted it because the new doc refers to the "support" web page[1], which
explicitly calls out the users list.

If you think we should also call out the users list in
contacting-the-project.rst, let me know, I'll work it in.

PS: I'm away until 01July on PTO. I'll address your feedback here and any
other patches once I'm back.

[1] https://www.qemu.org/support


>  Thomas
>
>

[-- Attachment #2: Type: text/html, Size: 1806 bytes --]

[PATCH v3 3/4] 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.36.1

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

[Peter Maydell]

On Mon, 6 Jun 2022 at 17:43, Kashyap Chamarthy <kchamart@redhat.com> wrote:
>
> 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>

> +-  Its OK if your new implementation doesn't do everything (or has some

I noticed a typo here (should be "It's"), but we should fix
that separately from this automated conversion.

Reviewed-by: Peter Maydell <peter.maydell@linaro.org>

thanks
-- PMM

[PATCH v3 4/4] Add a new doc "contacting-the-project.rst"

[Kashyap Chamarthy]

This document slightly duplicates the "support"[1] page here, but
largely refers to the content in[1].

This is based on Peter Maydell's feedback[2] in v2: "there is some
merit in the documentation being standalone, even if it does mean a bit
of duplication with the website".

[1] https://www.qemu.org/support/
[2] https://lists.nongnu.org/archive/html/qemu-devel/2022-03/msg05178.html

Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com>
---
 docs/about/contacting-the-project.rst | 16 ++++++++++++++++
 docs/about/index.rst                  |  1 +
 2 files changed, 17 insertions(+)
 create mode 100644 docs/about/contacting-the-project.rst

diff --git a/docs/about/contacting-the-project.rst b/docs/about/contacting-the-project.rst
new file mode 100644
index 0000000000..83c1c50c48
--- /dev/null
+++ b/docs/about/contacting-the-project.rst
@@ -0,0 +1,16 @@
+.. _contacting-the-project:
+
+Contacting the project
+======================
+
+There are a multiple ways to reach out to upstream QEMU project,
+depending on what you're trying to do.
+
+If you have technical questions on QEMU usage, there are multiple
+channels for it -- mailing lists, real-time chat (IRC, etc).  Refer to
+`this web page <https://www.qemu.org/support>`__ for more precise
+details.
+
+If you think you have found a bug in QEMU, please follow the procedure
+outlined in `this document
+<https://www.qemu.org/contribute/report-a-bug>`__ on how to report it.
diff --git a/docs/about/index.rst b/docs/about/index.rst
index 5bea653c07..32831eb09a 100644
--- a/docs/about/index.rst
+++ b/docs/about/index.rst
@@ -26,3 +26,4 @@ convert and modify disk images.
    deprecated
    removed-features
    license
+   contacting-the-project
-- 
2.36.1

Re: [PATCH v3 4/4] Add a new doc "contacting-the-project.rst"

[Thomas Huth]

On 06/06/2022 18.43, Kashyap Chamarthy wrote:
> This document slightly duplicates the "support"[1] page here, but
> largely refers to the content in[1].
> 
> This is based on Peter Maydell's feedback[2] in v2: "there is some
> merit in the documentation being standalone, even if it does mean a bit
> of duplication with the website".
> 
> [1] https://www.qemu.org/support/
> [2] https://lists.nongnu.org/archive/html/qemu-devel/2022-03/msg05178.html
> 
> Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com>
> ---
>   docs/about/contacting-the-project.rst | 16 ++++++++++++++++
>   docs/about/index.rst                  |  1 +
>   2 files changed, 17 insertions(+)
>   create mode 100644 docs/about/contacting-the-project.rst
> 
> diff --git a/docs/about/contacting-the-project.rst b/docs/about/contacting-the-project.rst
> new file mode 100644
> index 0000000000..83c1c50c48
> --- /dev/null
> +++ b/docs/about/contacting-the-project.rst
> @@ -0,0 +1,16 @@
> +.. _contacting-the-project:
> +
> +Contacting the project
> +======================
> +
> +There are a multiple ways to reach out to upstream QEMU project,
> +depending on what you're trying to do.
> +
> +If you have technical questions on QEMU usage, there are multiple
> +channels for it -- mailing lists, real-time chat (IRC, etc).  Refer to
> +`this web page <https://www.qemu.org/support>`__ for more precise
> +details.
> +
> +If you think you have found a bug in QEMU, please follow the procedure
> +outlined in `this document
> +<https://www.qemu.org/contribute/report-a-bug>`__ on how to report it.

Could you maybe also put a direct link to 
https://www.qemu.org/contribute/security-process in here? ... some people 
still get it wrong how to report security issues, so putting this directly 
maybe helps a little bit...

  Thomas

[PATCH v4 0/4] rSTify a few more docs; move them to QEMU Git [Was: Re: [PATCH v3 0/4] In v3:]

[Kashyap Chamarthy]

Oops, messed up v3's cover-letter subject; now fixed.  Sorry.

On Mon, Jun 06, 2022 at 06:43:32PM +0200, Kashyap Chamarthy wrote:
> - Add back the "<commit hash/link>" fragment in security-process.rst
>   [Thomas]
> - Add a docs/about/contacting-the-project.rst as per Peter's feedback
>   here:
>   https://lists.nongnu.org/archive/html/qemu-devel/2022-03/msg05178.html
>   [pm215]
> - Keep Thomas' R-by for "docs: rSTify MailingLists wiki; move it to QEMU
>   Git"
> 
> v2 cover letter:
> -----------------------------------------------------------------------
> rSTify a few more docs; move them to QEMU Git
> 
> 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 (4):
>   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
>   Add a new doc "contacting-the-project.rst"
> 
>  docs/about/contacting-the-project.rst     |  16 ++
>  docs/about/index.rst                      |   1 +
>  docs/devel/getting-started-developers.rst | 200 ++++++++++++++++++++++
>  docs/devel/index.rst                      |   3 +
>  docs/devel/mailing-lists.rst              |  51 ++++++
>  docs/devel/security-process.rst           | 190 ++++++++++++++++++++
>  6 files changed, 461 insertions(+)
>  create mode 100644 docs/about/contacting-the-project.rst
>  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.36.1
> 

-- 
/kashyap

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

[Kashyap Chamarthy]

On Mon, Jun 06, 2022 at 06:49:49PM +0200, Kashyap Chamarthy wrote:
> Oops, messed up v3's cover-letter subject; now fixed.  Sorry.

Sigh, instead of "v3", I accidentally wrote "v4" in the cover-letter
subject.  Now fix that too; sorry for the noise.

> On Mon, Jun 06, 2022 at 06:43:32PM +0200, Kashyap Chamarthy wrote:
> > - Add back the "<commit hash/link>" fragment in security-process.rst
> >   [Thomas]
> > - Add a docs/about/contacting-the-project.rst as per Peter's feedback
> >   here:
> >   https://lists.nongnu.org/archive/html/qemu-devel/2022-03/msg05178.html
> >   [pm215]
> > - Keep Thomas' R-by for "docs: rSTify MailingLists wiki; move it to QEMU
> >   Git"
> > 
> > v2 cover letter:
> > -----------------------------------------------------------------------
> > rSTify a few more docs; move them to QEMU Git
> > 
> > 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 (4):
> >   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
> >   Add a new doc "contacting-the-project.rst"
> > 
> >  docs/about/contacting-the-project.rst     |  16 ++
> >  docs/about/index.rst                      |   1 +
> >  docs/devel/getting-started-developers.rst | 200 ++++++++++++++++++++++
> >  docs/devel/index.rst                      |   3 +
> >  docs/devel/mailing-lists.rst              |  51 ++++++
> >  docs/devel/security-process.rst           | 190 ++++++++++++++++++++
> >  6 files changed, 461 insertions(+)
> >  create mode 100644 docs/about/contacting-the-project.rst
> >  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.36.1
> > 
> 
> -- 
> /kashyap

-- 
/kashyap

Re: [PATCH v3 0/4] rSTify a few more docs; move them to QEMU Git

[Kashyap Chamarthy]

Ping.

Thomas/Peter: when you get some time, please have a look at this.

On Mon, Jun 06, 2022 at 06:55:47PM +0200, Kashyap Chamarthy wrote:
> On Mon, Jun 06, 2022 at 06:49:49PM +0200, Kashyap Chamarthy wrote:
> > Oops, messed up v3's cover-letter subject; now fixed.  Sorry.
> 
> Sigh, instead of "v3", I accidentally wrote "v4" in the cover-letter
> subject.  Now fix that too; sorry for the noise.
> 
> > On Mon, Jun 06, 2022 at 06:43:32PM +0200, Kashyap Chamarthy wrote:
> > > - Add back the "<commit hash/link>" fragment in security-process.rst
> > >   [Thomas]
> > > - Add a docs/about/contacting-the-project.rst as per Peter's feedback
> > >   here:
> > >   https://lists.nongnu.org/archive/html/qemu-devel/2022-03/msg05178.html
> > >   [pm215]
> > > - Keep Thomas' R-by for "docs: rSTify MailingLists wiki; move it to QEMU
> > >   Git"
> > > 
> > > v2 cover letter:
> > > -----------------------------------------------------------------------
> > > rSTify a few more docs; move them to QEMU Git
> > > 
> > > 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 (4):
> > >   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
> > >   Add a new doc "contacting-the-project.rst"
> > > 
> > >  docs/about/contacting-the-project.rst     |  16 ++
> > >  docs/about/index.rst                      |   1 +
> > >  docs/devel/getting-started-developers.rst | 200 ++++++++++++++++++++++
> > >  docs/devel/index.rst                      |   3 +
> > >  docs/devel/mailing-lists.rst              |  51 ++++++
> > >  docs/devel/security-process.rst           | 190 ++++++++++++++++++++
> > >  6 files changed, 461 insertions(+)
> > >  create mode 100644 docs/about/contacting-the-project.rst
> > >  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.36.1
> > > 
> > 
> > -- 
> > /kashyap
> 
> -- 
> /kashyap
> 
> 

-- 
/kashyap

Re: [PATCH v3 0/4] rSTify a few more docs; move them to QEMU Git

[Peter Maydell]

On Fri, 1 Jul 2022 at 09:53, Kashyap Chamarthy <kchamart@redhat.com> wrote:
>
> Ping.
>
> Thomas/Peter: when you get some time, please have a look at this.

I reviewed the one patch that had neither already got an R-by
or some review comments.

thanks
-- PMM

Re: [PATCH v3 0/4] rSTify a few more docs; move them to QEMU Git

[Thomas Huth]

On 01/07/2022 10.53, Kashyap Chamarthy wrote:
> Ping.
> 
> Thomas/Peter: when you get some time, please have a look at this.

I still had a question/request here that was not answered:

https://lore.kernel.org/qemu-devel/2fca7b7e-f95d-eae1-9973-9ede30cac3c1@redhat.com/

Also, for the first patch, I'd like to see a Reviewed-by by one of the 
security folks whether it's ok for them to move this page to a location that 
has different access rights.

  Thomas


> On Mon, Jun 06, 2022 at 06:55:47PM +0200, Kashyap Chamarthy wrote:
>> On Mon, Jun 06, 2022 at 06:49:49PM +0200, Kashyap Chamarthy wrote:
>>> Oops, messed up v3's cover-letter subject; now fixed.  Sorry.
>>
>> Sigh, instead of "v3", I accidentally wrote "v4" in the cover-letter
>> subject.  Now fix that too; sorry for the noise.
>>
>>> On Mon, Jun 06, 2022 at 06:43:32PM +0200, Kashyap Chamarthy wrote:
>>>> - Add back the "<commit hash/link>" fragment in security-process.rst
>>>>    [Thomas]
>>>> - Add a docs/about/contacting-the-project.rst as per Peter's feedback
>>>>    here:
>>>>    https://lists.nongnu.org/archive/html/qemu-devel/2022-03/msg05178.html
>>>>    [pm215]
>>>> - Keep Thomas' R-by for "docs: rSTify MailingLists wiki; move it to QEMU
>>>>    Git"
>>>>
>>>> v2 cover letter:
>>>> -----------------------------------------------------------------------
>>>> rSTify a few more docs; move them to QEMU Git
>>>>
>>>> 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 (4):
>>>>    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
>>>>    Add a new doc "contacting-the-project.rst"
>>>>
>>>>   docs/about/contacting-the-project.rst     |  16 ++
>>>>   docs/about/index.rst                      |   1 +
>>>>   docs/devel/getting-started-developers.rst | 200 ++++++++++++++++++++++
>>>>   docs/devel/index.rst                      |   3 +
>>>>   docs/devel/mailing-lists.rst              |  51 ++++++
>>>>   docs/devel/security-process.rst           | 190 ++++++++++++++++++++
>>>>   6 files changed, 461 insertions(+)
>>>>   create mode 100644 docs/about/contacting-the-project.rst
>>>>   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.36.1
>>>>
>>>
>>> -- 
>>> /kashyap
>>
>> -- 
>> /kashyap
>>
>>
>