Extend CONTRIBUTING guide

Explain the branching model, and how to keep topic branches tidy.
Also adds a Code of Conduct

Author: goerz

CONTRIBUTING.rst

@@ -7,6 +7,17 @@ Contributing
 Contributions are welcome, and they are greatly appreciated! Every little bit
 helps, and credit will always be given.
 
+
+Code of Conduct
+---------------
+
+Everyone interacting in the QDYN-pylib project's code base,
+issue tracker, and any communication channels is expected to follow the
+`PyPA Code of Conduct`_.
+
+.. _`PyPA Code of Conduct`: https://www.pypa.io/en/latest/code-of-conduct/
+
+
 Report Bugs
 -----------
 
@@ -32,12 +43,6 @@ If you are proposing a feature:
   are welcome :)
 
 
-Fix Bugs / Implement Features
------------------------------
-
-Look through the GitHub issues for bugs or feature requests. Anybody is welcome to submit a pull request for open issues.
-
-
 Pull Request Guidelines
 -----------------------
 
@@ -99,6 +104,119 @@ You still can (and should) look at https://travis-ci.org/qucontrol/qdynpylib/ to
 .. _qucontrol organization: https://github.com/qucontrol
 
 
+Branching Model
+---------------
+
+For developers with direct access to the repository,
+QDYN-pylib  uses a simple branching model where all
+developments happens directly on the ``master`` branch. Releases are tags on
+``master``. All commits on ``master`` *should* pass all tests and be
+well-documented. This is so that ``git bisect`` can be effective. For any
+non-trivial issue, it is recommended to create a topic branch, instead of
+working on ``master``. There are no restrictions on commits on topic branches,
+they do not need to contain complete documentation, pass any tests, or even be
+able to run.
+
+To create a topic-branch named ``issue1``::
+
+    $ git branch issue1
+    $ git checkout issue1
+
+You can then make commits, and push them to Github to trigger Continuous
+Integration testing::
+
+    $ git push -u origin issue1
+
+Commit early and often! At the same time, try to keep your topic branch
+as clean and organized as possible. If you have not yet pushed your topic
+branch to the "origin" remote:
+
+* Avoid having a series of meaningless granular commits like "start bugfix",
+  "continue development", "add more work on bugfix", "fix typos", and so forth.
+  Instead, use ``git commit --amend`` to add to your previous commit. This is
+  the ideal way to "commit early and often". You do not have to wait until a
+  commit is "perfect"; it is a good idea to make hourly/daily "snapshots" of
+  work in progress. Amending a commit also allows you to change the commit
+  message of your last commit.
+* You can combine multiple existing commits by "squashing" them. For example,
+  use ``git rebase -i HEAD~4`` to combined the previous four commits into one.
+  See the `"Rewriting History" section of Pro Git book`_ for details (if you
+  feel this is too far outside of your git comfort zone, just skip it).
+* If you work on a topic branch for a long time, and there is significant work
+  on ``master`` in the meantime, periodically rebase your topic branch on the
+  current master (``git rebase master``). Avoid merging ``master`` into your
+  topic branch. See `Merging vs. Rebasing`_.
+
+If you have already pushed your topic branch to the remote origin, you have to
+be a bit more careful. If you are sure that you are the only one working on
+that topic branch, you can still follow the above guidelines, and force-push
+the issue branch (``git push --force``). This also applies if you are an
+external contributor preparing a pull request in your own clone of the project.
+If you are collaborating with others on the topic branch, coordinate with them
+whether they are OK with rewriting the history. If not, merge instead of
+rebasing. You must never rewrite history on the ``master`` branch (nor will you
+be able to, as the ``master`` branch is "protected" and can only be force-pushed to
+in coordination with the project maintainer).  If something goes wrong with any
+advanced "history rewriting", there is always `"git reflog"`_ as a safety net
+-- you will never lose work that was committed before.
+
+When you are done with a topic branch (the issue has been fixed), finish up by
+merging the topic branch back into ``master``::
+
+    $ git checkout master
+    $ git merge --no-ff issue1
+
+The ``--no-ff`` option is critical, so that an explicit merge commit is created
+(especially if you rebased).  Summarize the changes of the branch relative to
+``master`` in the commit message.
+
+Then, you can push master and delete the topic branch both locally and on Github::
+
+    $ git push origin master
+    $ git push --delete origin issue1
+    $ git branch -D issue1
+
+.. _"Rewriting History" section of Pro Git book: https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History
+.. _Merging vs. Rebasing: https://www.atlassian.com/git/tutorials/merging-vs-rebasing
+.. _"git reflog": https://www.atlassian.com/git/tutorials/rewriting-history/git-reflog
+
+
+Commit Message Guidelines
+-------------------------
+
+Write commit messages according to this template:
+
+.. code-block:: none
+
+    Short (50 chars or less) summary ("subject line")
+
+    More detailed explanatory text. Wrap it to 72 characters. The blank
+    line separating the summary from the body is critical (unless you omit
+    the body entirely).
+
+    Write your subject line in the imperative: "Fix bug" and not "Fixed
+    bug" or "Fixes bug." This convention matches up with commit messages
+    generated by commands like git merge and git revert. A properly formed
+    git commit subject line should always be able to complete the sentence
+    "If applied, this commit will <your subject line here>".
+
+    Further paragraphs come after blank lines.
+
+    - Bullet points are okay, too.
+    - Typically a hyphen or asterisk is used for the bullet, followed by a
+      single space. Use a hanging indent.
+
+    You should reference any issue that is being addressed in the commit, as
+    e.g. "#1" for issue #1. If the commit closes an issue, state this on the
+    last line of the message (see below). This will automatically close the
+    issue on Github as soon as the commit is pushed there.
+
+    Closes #1
+
+See `Closing issues using keywords`_ for details on references to issues that
+Github will understand.
+
+
 Testing
 -------
 
@@ -235,77 +353,6 @@ some local virtual environments that development relies on).
 
 .. _how-to-work-on-a-topic-branch:
 
-How to work on a topic branch
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-When working on an non-trivial issue, it is recommended to create a topic
-branch, instead of pushing to ``master``.
-
-To create a branch named ``issue18``::
-
-    $ git branch issue18
-    $ git checkout issue18
-
-You can then make commits, and push them to Github to trigger Continuous Integration testing::
-
-    $ git push origin issue18
-
-It is ok to force-push on an issue branch
-
-When you are done (the issue has been fixed), finish up by merging the topic
-branch back into ``master``::
-
-    $ git checkout master
-    $ git merge --no-ff issue18
-
-The ``--no-ff`` option is critical, so that an explicit merge commit is created.
-Summarize the changes of the branch relative to ``master`` in the commit
-message.
-
-Then, you can push master and delete the topic branch both locally and on Github::
-
-    $ git push origin master
-    $ git push --delete origin issue18
-    $ git branch -D issue18
-
-
-Commit Message Guidelines
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Write commit messages according to this template:
-
-.. code-block:: none
-
-    Short (50 chars or less) summary
-
-    More detailed explanatory text. Wrap it to 72 characters. The blank
-    line separating the summary from the body is critical (unless you omit
-    the body entirely).
-
-    Write your commit message in the imperative: "Fix bug" and not "Fixed
-    bug" or "Fixes bug." This convention matches up with commit messages
-    generated by commands like git merge and git revert.
-
-    Further paragraphs come after blank lines.
-
-    - Bullet points are okay, too.
-    - Typically a hyphen or asterisk is used for the bullet, followed by a
-      single space. Use a hanging indent.
-
-A properly formed git commit subject line should always be able to complete the
-sentence "If applied, this commit will <your subject line here>".
-
-
-How to reference a Github issue in a commit message
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Simply put e.g. ``#14`` anywhere in your commit message, and Github will
-automatically link to your commit on the page for issue number 14.
-
-You may also use something like ``Closes #14`` as the last line of your
-commit message to automatically close the issue.
-See `Closing issues using keywords`_ for details.
-
 
 How to install QuTiP from source ("illegal instruction" in QuTiP conda install)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~