[libvirt PATCH 09/10] docs: Add best-practices.rst

[Andrea Bolognani]

These guidelines should already be familiar to people who have
contributed to other open source projects, so it doesn't make much
sense for them to be so prominent. Move them to a separate page.

Signed-off-by: Andrea Bolognani <abologna at redhat.com>
---
 docs/best-practices.rst | 37 +++++++++++++++++++++++++++++++++++++
 docs/hacking.rst        | 29 -----------------------------
 2 files changed, 37 insertions(+), 29 deletions(-)
 create mode 100644 docs/best-practices.rst

diff --git a/docs/best-practices.rst b/docs/best-practices.rst
new file mode 100644
index 0000000000..7c48ff10be
--- /dev/null
+++ b/docs/best-practices.rst
@@ -0,0 +1,37 @@
+==============
+Best practices
+==============
+
+These are a few guidelines to keep in mind when submitting patches
+to libvirt: following them will maximise the chance of your patches
+being reviewed in a timely manner and being accepted into libvirt
+with minimal back-and-forth.
+
+-  Discuss any large changes on the mailing list first. Post
+   patches early and listen to feedback.
+
+-  In your commit message, make the summary line reasonably short
+   (60 characters is typical), followed by a blank line, followed
+   by any longer description of why your patch makes sense. If the
+   patch fixes a regression, and you know what commit introduced
+   the problem, mentioning that is useful. If the patch resolves a
+   bugzilla report, mentioning the URL of the bug number is
+   useful; but also summarize the issue rather than making all
+   readers follow the link. You can use 'git shortlog -30' to get
+   an idea of typical summary lines.
+
+-  Split large changes into a series of smaller patches,
+   self-contained if possible, with an explanation of each patch
+   and an explanation of how the sequence of patches fits
+   together. Moreover, please keep in mind that it's required to
+   be able to compile cleanly (**including**
+   ``make check`` and ``make syntax-check``) after each
+   patch. A feature does not have to work until the end of a
+   series, but intermediate patches must compile and not cause
+   test-suite failures (this is to preserve the usefulness of
+   ``git bisect``, among other things).
+
+There is more on this subject, including lots of links to
+background reading on the subject, on `Richard Jones' guide to
+working with open source
+projects <http://people.redhat.com/rjones/how-to-supply-code-to-open-source-projects/>`__.
diff --git a/docs/hacking.rst b/docs/hacking.rst
index abede5f206..996999885e 100644
--- a/docs/hacking.rst
+++ b/docs/hacking.rst
@@ -7,9 +7,6 @@ Contributor guidelines
 General tips for contributing patches
 =====================================
 
-#. Discuss any large changes on the mailing list first. Post
-   patches early and listen to feedback.
-
 #. Official upstream repository is kept in git
    (``https://libvirt.org/git/libvirt.git``) and is browsable
    along with other libvirt-related repositories (e.g.
@@ -21,16 +18,6 @@ General tips for contributing patches
    The libvirt release process automatically pulls the latest
    version of each translation file from zanata.
 
-#. In your commit message, make the summary line reasonably short
-   (60 characters is typical), followed by a blank line, followed
-   by any longer description of why your patch makes sense. If the
-   patch fixes a regression, and you know what commit introduced
-   the problem, mentioning that is useful. If the patch resolves a
-   bugzilla report, mentioning the URL of the bug number is
-   useful; but also summarize the issue rather than making all
-   readers follow the link. You can use 'git shortlog -30' to get
-   an idea of typical summary lines.
-
 #. Contributors to libvirt projects **must** assert that they are
    in compliance with the `Developer Certificate of Origin
    1.1 <https://developercertificate.org/>`__. This is achieved by
@@ -39,17 +26,6 @@ General tips for contributing patches
    attests that the contributor has read the above lined DCO and
    agrees with its statements.
 
-#. Split large changes into a series of smaller patches,
-   self-contained if possible, with an explanation of each patch
-   and an explanation of how the sequence of patches fits
-   together. Moreover, please keep in mind that it's required to
-   be able to compile cleanly (**including**
-   ``make check`` and ``make syntax-check``) after each
-   patch. A feature does not have to work until the end of a
-   series, but intermediate patches must compile and not cause
-   test-suite failures (this is to preserve the usefulness of
-   ``git bisect``, among other things).
-
 #. Make sure your patches apply against libvirt GIT. Developers
    only follow GIT and don't care much about released versions.
 
@@ -72,8 +48,3 @@ General tips for contributing patches
    libvirt developers, such as code refactoring, don't belong in
    the release notes. Note that ``docs/news.xml`` should be
    updated in its own commit not to get in the way of backports.
-
-There is more on this subject, including lots of links to
-background reading on the subject, on `Richard Jones' guide to
-working with open source
-projects <http://people.redhat.com/rjones/how-to-supply-code-to-open-source-projects/>`__.
-- 
2.25.1