Merge pull request #44 from zhmcclient/andy/doc-contributing

Integrated CONTRIBUTING.rst content in Development section of docs.

README.rst

@@ -121,12 +121,12 @@ The zhmcclient documentation is on RTD:
 .. _Documentation for version on Pypi: http://python-zhmcclient.readthedocs.io/en/stable/
 .. _Documentation for master branch in Git repo: http://python-zhmcclient.readthedocs.io/en/latest/
 
-Contributing
-============
+Development, testing, and contributing
+======================================
 
-Contribution rules are described in `CONTRIBUTING.rst`_.
+For more details, see the `Development section`_ in the documentation.
 
-.. _CONTRIBUTING.rst: https://github.com/zhmcclient/python-zhmcclient/tree/master/CONTRIBUTING.rst
+.. _Development section: http://python-zhmcclient.readthedocs.io/en/stable/development.html
 
 License
 =======

docs/development.rst

@@ -112,7 +112,97 @@ syntax of its ``-k`` option.
 Contributing
 ------------
 
-You are welcome to contribute to the project! The rules for contributing are
-described in the file `CONTRIBUTING.rst`_.
+Third party contributions to this project are welcome!
 
-.. _CONTRIBUTING.rst: https://github.com/zhmcclient/python-zhmcclient/tree/master/CONTRIBUTING.rst
+In order to contribute, create a `Git pull request`_, considering this:
+
+.. _Git pull request: https://help.github.com/articles/using-pull-requests/
+
+* Test is required.
+* Each commit should only contain one "logical" change.
+* A "logical" change should be put into one commit, and not split over multiple
+  commits.
+* Large new features should be split into stages.
+* The commit message should not only summarize what you have done, but explain
+  why the change is useful.
+* The commit message must follow the format explained below.
+
+What comprises a "logical" change is subject to sound judgement. Sometimes, it
+makes sense to produce a set of commits for a feature (even if not large).
+For example, a first commit may introduce a (presumably) compatible API change
+without exploitation of that feature. With only this commit applied, it should
+be demonstrable that everything is still working as before. The next commit may
+be the exploitation of the feature in other components.
+
+For further discussion of good and bad practices regarding commits, see:
+
+* `OpenStack Git Commit Good Practice`_
+* `How to Get Your Change Into the Linux Kernel`_
+
+.. _OpenStack Git Commit Good Practice: https://wiki.openstack.org/wiki/GitCommitMessages
+.. _How to Get Your Change Into the Linux Kernel: https://www.kernel.org/doc/Documentation/SubmittingPatches
+
+Format of commit messages
+-------------------------
+
+A commit message must start with a short summary line, followed by a blank
+line.
+
+Optionally, the summary line may start with an identifier that helps
+identifying the type of change or the component that is affected, followed by
+a colon.
+
+It can include a more detailed description after the summary line. This is
+where you explain why the change was done, and summarize what was done.
+
+It must end with the DCO (Developer Certificate of Origin) sign-off line in the
+format shown in the example below, using your name and a valid email address of
+yours. The DCO sign-off line certifies that you followed the rules stated in
+`DCO 1.1`_. In short, you certify that you wrote the patch or otherwise have
+the right to pass it on as an open-source patch.
+
+.. _DCO 1.1: https://raw.githubusercontent.com/zhmcclient/python-zhmcclient/master/DCO1.1.txt
+
+We use `GitCop`_ during creation of a pull request to check whether the commit
+messages in the pull request comply to this format.
+If the commit messages do not comply, GitCop will add a comment to the pull
+request with a description of what was wrong.
+
+.. _GitCop: http://gitcop.com/
+
+Example commit message:
+
+::
+
+    cookies: Add support for delivering cookies
+
+    Cookies are important for many people. This change adds a pluggable API for
+    delivering cookies to the user, and provides a default implementation.
+
+    Signed-off-by: Random J Developer <[email protected]>
+
+Use ``git commit --amend`` to edit the commit message, if you need to.
+
+Use the ``--signoff`` (``-s``) option of ``git commit`` to append a sign-off
+line to the commit message with your name and email as known by Git.
+
+If you like filling out the commit message in an editor instead of using
+the ``-m`` option of ``git commit``, you can automate the presence of the
+sign-off line by using a commit template file:
+
+* Create a file outside of the repo (say, ``~/.git-signoff.template``)
+  that contains, for example:
+
+  ::
+
+      <one-line subject>
+
+      <detailed description>
+
+      Signed-off-by: Random J Developer <[email protected]>
+
+* Configure Git to use that file as a commit template for your repo:
+
+  ::
+
+      git config commit.template ~/.git-signoff.template