Skip to contentSkip to conversation

rSTify a few more docs; move them to QEMU Git

PATCH Superseded Kashyap Chamarthy 4 participants 14 messages Mar 14, 2022 – Mar 21, 2022

v2 of 3 Superseded Latest is v3 →

lore
Share & tools
lore
#0 lore raw

v2 cover 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 (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
Signature · 1 line
2.33.1
#1 lore raw

PATCH v2 1/3 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.33.1
#2 lore raw

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

Quoted 95 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:

     $> 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 +57 -0
new file mode 100644
index 0000000000..cc1000fe43
@@ -0,0 +1,190 @@
+.. _security-process:
+
+Security Process
+================
+
+Please report any suspected security issue in QEMU to the security
+mailing list at:
+
+-  `<[email protected]> <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:
+
+-  `<[email protected]> <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/>`__

docs/devel/security-process.rst line 67

Quoted 10 lines
docs/devel/security-process.rst new file +10 -0
+   -  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

#3 lore raw

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

Quoted 1 line · Thomas Huth

On 14/03/2022 11.49, Kashyap Chamarthy wrote:

[...]

Quoted 7 lines

docs/devel/security-process.rst line 67

Quoted 4 lines
docs/devel/security-process.rst new file +4 -0
+   -  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 "<[email protected]>" or "<[email protected]>" at the top ... probably because they're hyperlinks.) Anyway, I'll add it back in v2.

Thanks for the eagle eyes!

Quoted 3 lines

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.

Signature · 1 line
/kashyap
#4 lore raw

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

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

---
 docs/devel/index.rst         |  1 +
 docs/devel/mailing-lists.rst | 53 ++++++++++++++++++++++++++++++++++++
 2 files changed, 54 insertions(+)
 create mode 100644 docs/devel/mailing-lists.rst
docs/devel/index.rst +1 -0
index 424eff9294..fb9d9f3a80 100644
@@ -12,6 +12,7 @@ modifying QEMU's source code.
 
    code-of-conduct
    conflict-resolution
+   mailing-lists
    build-system
    style
    kconfig
docs/devel/mailing-lists.rst new file +53 -0

53 lines not on this page · raw message

Signature · 1 line
2.33.1
#5 lore raw

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

Hi Kashyap,

Quoted 27 lines · 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.

---
  docs/devel/index.rst         |  1 +
  docs/devel/mailing-lists.rst | 53 ++++++++++++++++++++++++++++++++++++
  2 files changed, 54 insertions(+)

create mode 100644 docs/devel/mailing-lists.rst

docs/devel/mailing-lists.rst new file +3 -0
new file mode 100644
index 0000000000..53dcbfb007
@@ -0,0 +1,53 @@
+.. _mailing-lists:
+
+Mailing lists

docs/devel/mailing-lists.rst line 13

Quoted 10 lines
docs/devel/mailing-lists.rst new file +10 -0
+=============
+
+-  `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
. ...

Quoted 19 lines
docs/devel/mailing-lists.rst new file +19 -0
+.. _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>`__
#6 lore raw

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

Quoted 1 line · Philippe Mathieu-Daudé

Hi Kashyap,

Hi,

Quoted 1 line · Kashyap Chamarthy

[...]

Quoted 3 lines

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

Quoted 12 lines

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

Quoted 7 lines

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!

Quoted 9 lines

- susbsystem specific

> block layer

> architecture specific

. ARM
. PPC
. ...

[...]

Signature · 1 line
/kashyap
Reviewed-by on v2 2/3
#7 lore raw

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

In reply to Kashyap Chamarthy

docs/devel/mailing-lists.rst

Quoted 35 lines · 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.

---
  docs/devel/index.rst         |  1 +
  docs/devel/mailing-lists.rst | 53 ++++++++++++++++++++++++++++++++++++
  2 files changed, 54 insertions(+)

create mode 100644 docs/devel/mailing-lists.rst

docs/devel/index.rst +1 -0
index 424eff9294..fb9d9f3a80 100644
@@ -12,6 +12,7 @@ modifying QEMU's source code.
 
     code-of-conduct
     conflict-resolution
+   mailing-lists
     build-system
     style
     kconfig
docs/devel/mailing-lists.rst new file +0 -0
new file mode 100644
index 0000000000..53dcbfb007

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

Anyway:

#8 lore raw

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

Quoted 1 line · Thomas Huth

On 14/03/2022 11.49, Kashyap Chamarthy wrote:

[...]

Quoted 2 lines

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

Quoted 3 lines

Anyway:

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

Signature · 1 line
/kashyap
#9 lore raw

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

Quoted 6 lines · Kashyap Chamarthy
Quoted 1 line · Thomas Huth

On 14/03/2022 11.49, Kashyap Chamarthy wrote:

[...]

Quoted 8 lines
Quoted 2 lines

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

#10 lore raw

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

Quoted 16 lines · Peter Maydell
Quoted 6 lines · Kashyap Chamarthy
Quoted 1 line · Thomas Huth

On 14/03/2022 11.49, Kashyap Chamarthy wrote:

[...]

Quoted 8 lines
Quoted 2 lines

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

Quoted 6 lines

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.

Signature · 1 line
/kashyap
#11 lore raw

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

Quoted 22 lines · Kashyap Chamarthy
Quoted 20 lines · Peter Maydell
Quoted 6 lines · Kashyap Chamarthy
Quoted 1 line · Thomas Huth

On 14/03/2022 11.49, Kashyap Chamarthy wrote:

[...]

Quoted 8 lines
Quoted 2 lines

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.

Quoted 6 lines
Quoted 2 lines

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

#12 lore raw

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

Quoted 1 line · Peter Maydell

On Mon, 21 Mar 2022 at 09:55, Kashyap Chamarthy <[email protected]> wrote:

[...]

Quoted 7 lines
Quoted 7 lines
Quoted 6 lines

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

Quoted 6 lines
Quoted 3 lines

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.

Signature · 1 line
/kashyap
#13 lore raw

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

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

---
 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
docs/devel/getting-started-developers.rst new file +200 -0
new file mode 100644
index 0000000000..1299e1dfee
@@ -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.
docs/devel/index.rst +1 -0
index fb9d9f3a80..afead67200 100644
@@ -13,6 +13,7 @@ modifying QEMU's source code.
    code-of-conduct
    conflict-resolution
    mailing-lists
+   getting-started-developers
    build-system
    style
    kconfig
Signature · 1 line
2.33.1