Signed-off-by: Peter Krempa <pkrempa@xxxxxxxxxx> --- 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";>Fedora - 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";>stackoverflow.</a> - 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";>Google 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
