9:59 a.m.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/contribute.html.in | 143 ----------------------------------------
docs/contribute.rst | 105 +++++++++++++++++++++++++++++
docs/meson.build | 2 +-
3 files changed, 106 insertions(+), 144 deletions(-)
delete mode 100644 docs/contribute.html.in
create mode 100644 docs/contribute.rst
diff --git a/docs/contribute.html.in b/docs/contribute.html.in
deleted file mode 100644
index 790114a56d..0000000000
--- a/docs/contribute.html.in
+++ /dev/null
@@ -1,143 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
- <body>
- <h1>Contributing to libvirt</h1>
-
- <p>
- This page provides guidance on how to contribute to the
- libvirt project.
- </p>
-
- <ul id="toc"></ul>
-
- <h2><a id="skills">Contributions required</a></h2>
-
- <p>
- The libvirt project is always looking for new contributors to
- participate in ongoing activities. While code development is a
- major part of the project, assistance is needed in many other
- areas including documentation writing, bug triage, testing,
- application integration, website / wiki content management,
- translation, branding, social media and more. The only
- requirement is an interest in virtualization and desire to
- help.
- </p>
-
- <p>
- The following is a non-exhaustive list of areas in which
- people can contribute to libvirt. If you have ideas for
- other contributions feel free to follow them.
- </p>
-
- <ul>
- <li><strong>Software development</strong>. The official upstream
code are
- kept in various <a href="https://gitlab.com/libvirt/">Git
repositories</a>.
- The core library / daemon (and thus the bulk of coding) is written in C,
- but there are language bindings written in Python, Perl, Java, Ruby,
- Php, OCaml and Go. There are also higher level wrappers
- mapping libvirt into other object frameworks, such GLib,
- CIM and SNMP. For those interested in working on the core parts of
- libvirt, the <a href="hacking.html">contributor
guidelines</a> are
- mandatory reading</li>
- <li><strong>Translation</strong>. All the libvirt modules aim to
support
- translations where appropriate. All translation is
- handling outside of the normal libvirt review process,
- using the <a
href="https://translate.fedoraproject.org/projects/libvirt/libvirt&q...
- instance</a> of the Weblate tool. Thus people wishing
- to contribute to translation should join the Fedora
- translation team</li>
- <li><strong>Documentation</strong>. There are docbook guides on
various
- aspects of libvirt, particularly application development
- guides for the C library and Python, and a virsh command
- reference. There is thus scope for work by people who are
- familiar with using or developing against libvirt, to
- write further content for these guides. There is also a
- need for people to review existing content for copy editing
- and identifying gaps in the docs</li>
- <li><strong>Website / wiki curation</strong>. The bulk of the
website is
- maintained in the primary GIT repository, while the wiki
- site uses mediawiki. In both cases there is a need for
- people to both write new content and curate existing
- content to identify outdated information, improve its
- organization and target gaps.</li>
- <li><strong>Testing</strong>. There are a number of tests suites
that can run
- automated tests against libvirt. The coverage of the tests
- is never complete, so there is a need for people to create
- new test suites and / or provide environments to actually
- run the tests in a variety of deployment scenarios.</li>
- <li><strong>Code analysis</strong>. The libvirt project has
access to the coverity
- tool to run static analysis against the codebase, however,
- there are other types of code analysis that can be useful.
- In particular fuzzing of the inputs can be very effective
- at identifying problematic edge cases.</li>
- <li><strong>Security handling</strong>. Downstream (operating
system) vendors
- who distribute libvirt may wish to propose a person to
- be part of the security handling team, to get early access
- to information about forthcoming vulnerability fixes.</li>
- <li><strong>Evangelism</strong>. Work done by the project is of
no benefit
- unless the (potential) user community knows that it
- exists. Thus it is critically important to the health
- and future growth of the project, that there are a people
- who evangelize the work created by the project. This can
- take many forms, writing blog posts (about usage of features,
- personal user experiences, areas for future work, and more),
- syndicating docs and blogs via social media, giving user
- group and/or conference talks about libvirt.</li>
- <li><strong>User assistance</strong>. Since documentation
- is never perfect, there are inevitably cases where users
- will struggle to attain a deployment goal they have, or
- run into trouble with managing an existing deployment.
- While some users may be able to contact a software vendor
- to obtain support, it is common to rely on community help
- forums such as <a href="contact.html#email">libvirt users
- mailing list</a>, or sites such as
- <a
href="https://stackoverflow.com/questions/tagged/libvirt">st...
- People who are familiar with libvirt and have ability &
- desire to help other users are encouraged to participate in
- these help forums.</li>
- </ul>
-
- <h2><a id="comms">Communication</a></h2>
-
- <p>
- For full details on contacting other project contributors
- read the <a href="contact.html">contact</a> page. There
- are two main channels that libvirt uses for communication
- between contributors:
- </p>
-
- <h3><a id="email">Mailing lists</a></h3>
-
- <p>
- The project has a number of
- <a href="contact.html#email">mailing lists</a> for
- general communication between contributors.
- In general any design discussions and review
- of contributions will take place on the mailing
- lists, so it is important for all contributors
- to follow the traffic.
- </p>
-
- <h3><a id="irc">Instant messaging / chat</a></h3>
-
- <p>
- Contributors to libvirt are encouraged to join the
- <a href="contact.html#irc">IRC channel</a> used by
- the project, where they can have live conversations
- with others members.
- </p>
-
- <h2><a id="outreach">Student / outreach coding
programs</a></h2>
-
- <p>
- Since 2016, the libvirt project directly participates as an
- organization in the <a
href="https://wiki.libvirt.org/page/Google_Summer_of_Code_Ideas"...
Summer of Code program</a>. Prior to
- this the project had a number of students in the program
- via a joint application with the QEMU project. People are
- encouraged to look at both the libvirt and QEMU programs
- to identify potentially interesting projects to work on.
- </p>
-
- </body>
-</html>
diff --git a/docs/contribute.rst b/docs/contribute.rst
new file mode 100644
index 0000000000..c95c8b59d2
--- /dev/null
+++ b/docs/contribute.rst
@@ -0,0 +1,105 @@
+=======================
+Contributing to libvirt
+=======================
+
+This page provides guidance on how to contribute to the libvirt project.
+
+.. contents::
+
+Contributions required
+----------------------
+
+The libvirt project is always looking for new contributors to participate in
+ongoing activities. While code development is a major part of the project,
+assistance is needed in many other areas including documentation writing, bug
+triage, testing, application integration, website / wiki content management,
+translation, branding, social media and more. The only requirement is an
+interest in virtualization and desire to help.
+
+The following is a non-exhaustive list of areas in which people can contribute
+to libvirt. If you have ideas for other contributions feel free to follow them.
+
+- **Software development**. The official upstream code are kept in various `Git
+ repositories <https://gitlab.com/libvirt/>`__. The core library / daemon (and
+ thus the bulk of coding) is written in C, but there are language bindings
+ written in Python, Perl, Java, Ruby, Php, OCaml and Go. There are also higher
+ level wrappers mapping libvirt into other object frameworks, such GLib, CIM
+ and SNMP. For those interested in working on the core parts of libvirt, the
+ `contributor guidelines <hacking.html>`__ are mandatory reading
+- **Translation**. All the libvirt modules aim to support translations where
+ appropriate. All translation is handling outside of the normal libvirt review
+ process, using the `Fedora
+ instance <https://translate.fedoraproject.org/projects/libvirt/libvirt>`__ of
+ the Weblate tool. Thus people wishing to contribute to translation should
+ join the Fedora translation team
+- **Documentation**. There are docbook guides on various aspects of libvirt,
+ particularly application development guides for the C library and Python, and
+ a virsh command reference. There is thus scope for work by people who are
+ familiar with using or developing against libvirt, to write further content
+ for these guides. There is also a need for people to review existing content
+ for copy editing and identifying gaps in the docs
+- **Website / wiki curation**. The bulk of the website is maintained in the
+ primary GIT repository, while the wiki site uses mediawiki. In both cases
+ there is a need for people to both write new content and curate existing
+ content to identify outdated information, improve its organization and target
+ gaps.
+- **Testing**. There are a number of tests suites that can run automated tests
+ against libvirt. The coverage of the tests is never complete, so there is a
+ need for people to create new test suites and / or provide environments to
+ actually run the tests in a variety of deployment scenarios.
+- **Code analysis**. The libvirt project has access to the coverity tool to run
+ static analysis against the codebase, however, there are other types of code
+ analysis that can be useful. In particular fuzzing of the inputs can be very
+ effective at identifying problematic edge cases.
+- **Security handling**. Downstream (operating system) vendors who distribute
+ libvirt may wish to propose a person to be part of the security handling
+ team, to get early access to information about forthcoming vulnerability
+ fixes.
+- **Evangelism**. Work done by the project is of no benefit unless the
+ (potential) user community knows that it exists. Thus it is critically
+ important to the health and future growth of the project, that there are a
+ people who evangelize the work created by the project. This can take many
+ forms, writing blog posts (about usage of features, personal user
+ experiences, areas for future work, and more), syndicating docs and blogs via
+ social media, giving user group and/or conference talks about libvirt.
+- **User assistance**. Since documentation is never perfect, there are
+ inevitably cases where users will struggle to attain a deployment goal they
+ have, or run into trouble with managing an existing deployment. While some
+ users may be able to contact a software vendor to obtain support, it is
+ common to rely on community help forums such as `libvirt users mailing
+ list <contact.html#email>`__, or sites such as
+ `stackoverflow. <https://stackoverflow.com/questions/tagged/libvirt>`__
+ People who are familiar with libvirt and have ability & desire to help other
+ users are encouraged to participate in these help forums.
+
+Communication
+-------------
+
+For full details on contacting other project contributors read the
+`contact <contact.html>`__ page. There are two main channels that libvirt uses
+for communication between contributors:
+
+Mailing lists
+~~~~~~~~~~~~~
+
+The project has a number of `mailing lists <contact.html#email>`__ for general
+communication between contributors. In general any design discussions and review
+of contributions will take place on the mailing lists, so it is important for
+all contributors to follow the traffic.
+
+Instant messaging / chat
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Contributors to libvirt are encouraged to join the `IRC
+channel <contact.html#irc>`__ used by the project, where they can have live
+conversations with others members.
+
+Student / outreach coding programs
+----------------------------------
+
+Since 2016, the libvirt project directly participates as an organization in the
+`Google Summer of Code
+program <https://wiki.libvirt.org/page/Google_Summer_of_Code_Ideas>`__. Prior to
+this the project had a number of students in the program via a joint application
+with the QEMU project. People are encouraged to look at both the libvirt and
+QEMU programs to identify potentially interesting projects to work on.
diff --git a/docs/meson.build b/docs/meson.build
index a719c268f6..bee7b3e6fc 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -22,7 +22,6 @@ docs_html_in_files = [
'bugs',
'cgroups',
'contact',
- 'contribute',
'csharp',
'dbus',
'docs',
@@ -89,6 +88,7 @@ docs_rst_files = [
'coding-style',
'committer-guidelines',
'compiling',
+ 'contribute',
'daemons',
'developer-tooling',
'drvqemu',
--
2.35.1