Re: [Qemu-devel] [PATCH] README: fill out some useful quickstart information

[John Snow]

On 09/17/2015 07:03 AM, Daniel P. Berrange wrote:
> The README file is usually the first thing consulted when a user
> or developer obtains a copy of the QEMU source. The current QEMU
> README is lacking immediately useful information and so not very
> friendly for first time encounters. It either redirects users to
> qemu-doc.html (which does not exist until they've actually
> compiled QEMU), or the website (which assumes the user has
> convenient internet access at time of reading).
> 
> This fills out the README file as simple quick-start guide on
> the topics of building source, submitting patches, licensing
> and how to contact the QEMU community. It does not intend to be
> comprehensive, instead referring people to an appropriate web
> page to obtain more detailed information. The intent is to give
> users quick guidance to get them going in the right direction.
> 
> Signed-off-by: Daniel P. Berrange <address@hidden>
> ---
>  README | 108 
> +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--
>  1 file changed, 106 insertions(+), 2 deletions(-)
> 
> diff --git a/README b/README
> index c7c990d..71142c3 100644
> --- a/README
> +++ b/README
> @@ -1,3 +1,107 @@
> -Read the documentation in qemu-doc.html or on http://wiki.qemu-project.org
> +         QEMU README
> +      ===========
>  
> -- QEMU team
> +QEMU is a generic and open source machine emulator and virtualizer. When used
> +as a machine emulator, QEMU can run OSes and programs made for one machine
> +(e.g. an ARM board) on a different machine (e.g. your own PC). By using 
> dynamic
> +translation, it achieves very good performance. When used as a virtualizer,
> +QEMU achieves near native performances by executing the guest code directly 
> on
> +the host CPU. QEMU supports virtualization when executing under the Xen
> +hypervisor or using the KVM kernel module in Linux.
> +
> +
> +Building
> +========
> +
> +QEMU is multi-platform software intended to be buildable on all modern Linux
> +platforms, OS-X, Win32 (via the Mingw64 toolchain) and a variety of other
> +UNIX targets. The simple process to build QEMU is
> +
> +  ./configure
> +  make
> +  sudo make install
> +
> +The configure script supports a number of arguments to turn on/off various
> +optional features. These can be seen with "configure --help".
> +
> +For additional information on building QEMU for Linux and Windows consult:
> +
> +  http://qemu-project.org/Hosts/Linux
> +  http://qemu-project.org/Hosts/W32
> +
> +
> +Submitting patches
> +==================
> +
> +The QEMU source code is maintained under the GIT version control system.
> +
> +   git clone git://git.qemu-project.org/qemu.git
> +
> +When submitting patches, the preferred approach is to use 'git format-patch'
> +and/or 'git send-email' to format & send the mail to the address@hidden
> +mailing list. All patches submitted must contain a 'Signed-off-by' line from
> +the author.
> +
> +For additional information on submitting patches consult:
> +
> +  http://qemu-project.org/Contribute/SubmitAPatch
> +  http://qemu-project.org/Contribute/TrivialPatches
> +

I'd mention the HACKING and CODING_STYLE files too, since they're likely
to be in the same folder as this README, which relates back to your
"useful offline" point in the commit message justification.

> +
> +Bug reporting
> +=============
> +
> +The QEMU project uses Launchpad as its primary upstream bug tracker. Bugs
> +found when running code built from QEMU git or upstream released sources
> +should be reported via:
> +
> +  https://bugs.launchpad.net/qemu/
> +
> +If using QEMU via an operating system vendor pre-built binary package, it
> +is preferrable to report bugs to the vendor's own bug tracker first. If the

Preferable, in US English at least. (As an aside: are we formalized on
en_US or en_GB? neither?)

> +bug is also known to affect latest upstream code, it can also be reported
> +via launchpad.
> +
> +For additional information on bug reporting consult:
> +
> +  http://qemu-project.org/Contribute/ReportABug
> +
> +
> +Licensing
> +=========
> +
> +  - QEMU as a whole is released under the GNU General Public License, 
> version 2.
> +
> +  - Parts of QEMU have specific licenses which are compatible with the GNU
> +    General Public License, version 2. Hence each source file contains its 
> own
> +    licensing information. Source files with no licensing information are
> +    released under the GNU General Public License, version 2 or (at your
> +    option) any later version. As of July 2013, contributions under version
> +    2 of the GNU General Public License (and no later version) are only
> +    accepted for the following files or directories: bsd-user/, linux-user/,
> +    hw/misc/vfio.c, hw/xen/xen_pt*.
> +
> +  - The Tiny Code Generator (TCG) is released under the BSD license (see
> +    license headers in files).
> +
> +  - QEMU is a trademark of Fabrice Bellard.
> +
> +For additional information on QEMU licensing consult:
> +

I think this and other uses could tolerate a comma.

"For additional information on QEMU licensing, consult: "

> +  http://qemu-project.org/License
> +

I would make clear that this is a licensing brief/summary and not the
actual authoritative text by which the project is licensed under the
GPL; again I would direct people to look at ./LICENSE and ./COPYING as
the authorities on the matter.

> +
> +Contact
> +=======
> +
> +The QEMU community can be contacted in a number of ways, with the two main
> +methods being E-Mail and IRC
> +

Grammar bikeshedding: "E-Mail" is absurdly formal. The common usage is
lower-cased "email."

> + - address@hidden (http://lists.nongnu.org/mailman/listinfo/qemu-devel)
> + - #qemu on irc.oftc.net
> +
> +For additional information on contacted the community consult:
> +

huh?

I think: "For additional information on [methods of] contacting the
community, consult:"

> +  http://qemu-project.org/Contribute/StartHere
> +
> +-- End
> 

As a random aside, it'd be nice to have a quick 101 somewhere obvious
that helps explain to users what QEMU's role in the ecosystem is.

For instance, the boundary between KVM, QEMU and libvirt seems to be
misunderstood frequently by first-time users and even contributors.

We touch on the qemu-kvm interaction in the first paragraph, but for
people even less familiar with the territory, a simplified explanation
might help:

"QEMU is capable of emulating a complete machine in software without any
need for hardware virtualization support. With the addition of Xen or
KVM on supported hardware platforms (e.g. x86's VT-x), QEMU can be
configured to emulate only the hardware and allows the hypervisor to
manage CPU and APIC emulation.

In common usage, QEMU behaves as the computer hardware while e.g. KVM
behaves as the CPU."

I'm sure my summary here is not resoundingly correct on all levels of
the metaphor, but it's roughly correct -- and someone with a better
technical mind than I should write a little disambiguation blurb about
what exactly the line between qemu+kvm is. I think it would help clear
up some things for some people.

And of course, further explaining the role of e.g. libvirt and
virt-manager may help get users up to speed on the norms for how the
project is used.

"QEMU is intended as a component in a full virtualization solution and
as-such does not provide robust or comprehensive UI solutions or
interfaces. QEMU does instead provide a robust and stable API for use by
management frameworks such as libvirt, which are used to build external
management applications such as virtual machine manager."

$0.02.

--js