From e6fdf04467905cca3afbc67f102605f3eb7a2051 Mon Sep 17 00:00:00 2001
From: Martijn Vermaat <martijn@vermaat.name>
Date: Thu, 11 Dec 2014 14:08:13 +0100
Subject: [PATCH] Update documentation on contributing and releases
---
README.rst | 14 +++-
doc/contributing.rst | 74 +++++++++++++++++++++
doc/development.rst | 154 -------------------------------------------
doc/index.rst | 22 +++++--
doc/release.rst | 84 +++++++++++++++++++++++
doc/testing.rst | 19 ++++++
6 files changed, 206 insertions(+), 161 deletions(-)
create mode 100644 doc/contributing.rst
delete mode 100644 doc/development.rst
create mode 100644 doc/release.rst
create mode 100644 doc/testing.rst
diff --git a/README.rst b/README.rst
index 3c266c97..1f601c6c 100644
--- a/README.rst
+++ b/README.rst
@@ -13,8 +13,18 @@ User documentation can be found on the `wiki
submit bug reports and feature requests.
Developer documentation is `hosted at Read The Docs
-<http://mutalyzer.readthedocs.org>`_. Contributions to Mutalyzer are welcome
-as `GitHub pull requests <https://github.com/LUMC/mutalyzer/pulls>`_.
+<http://mutalyzer.readthedocs.org>`_.
+
+
+Contributing
+------------
+
+Contributions to Mutalyzer are very welcome! They can be feature requests, bug
+reports, bug fixes, unit tests, documentation updates, or anything els you may
+come up with.
+
+Please refer to the documentation for `more information on contributions
+<http://mutalyzer.readthedocs.org/en/latest/contributing.html>`_.
Copyright
diff --git a/doc/contributing.rst b/doc/contributing.rst
new file mode 100644
index 00000000..a825419f
--- /dev/null
+++ b/doc/contributing.rst
@@ -0,0 +1,74 @@
+.. highlight:: none
+
+.. _contributing:
+
+Contributing
+============
+
+Contributions to Mutalyzer are very welcome! They can be feature requests, bug
+reports, bug fixes, unit tests, documentation updates, or anything els you may
+come up with.
+
+Development of Mutalyzer happens on GitHub:
+https://github.com/LUMC/mutalyzer
+
+
+Coding style
+------------
+
+In general, try to follow the `PEP 8`_ guidelines for Python code and `PEP
+257`_ for docstrings.
+
+
+Installation
+------------
+
+As a developer, you probably want to install the Mutalyzer package in
+development mode. This will allow you to edit files directly in the source
+directory without having to reinstall.
+
+Please refer to :ref:`install` for general installation instructions. For
+development mode installation, instead of using ``python setup.py install``,
+use::
+
+ python setup.py develop
+
+
+Creating a pull request
+-----------------------
+
+Contributions are most welcome as GitHub pull requests. If you're familiar
+with the typical GitHub pull request workflow, you can skip this section.
+
+New features are best implemented in their own branches, isolating the work
+from unrelated developments. In fact, it's good practice to *never work
+directly on the master branch* but always in a separate branch. When your work
+is ready, a feature branch can be merged back into master via a *pull request*
+in GitHub.
+
+Before starting your work, fork the Mutalyzer repository to your own namespace
+in GitHub and work from this fork. Before starting work on your feature,
+create a branch for it::
+
+ git clone https://github.com/<you>/mutalyzer.git && cd mutalyzer
+ git checkout -b your-feature
+
+Commit changes on this branch. If you're happy with it, push to GitHub::
+
+ git push origin your-feature -u
+
+Now create a pull request to discuss the implementation with the Mutalyzer
+maintainers. This might involve adding additional commits which are included
+in the pull request by pushing your branch again::
+
+ git commit
+ git push
+
+If the work is done, a maintainer can merge your branch and close the pull
+request. After the branch was merged you can safely delete it::
+
+ git branch -d your-feature
+
+
+.. _PEP 8: http://www.python.org/dev/peps/pep-0008/
+.. _PEP 257: http://www.python.org/dev/peps/pep-0257/
diff --git a/doc/development.rst b/doc/development.rst
deleted file mode 100644
index 354ee9a2..00000000
--- a/doc/development.rst
+++ /dev/null
@@ -1,154 +0,0 @@
-.. highlight:: none
-
-.. _development:
-
-Development
-===========
-
-Development of Mutalyzer happens on GitHub:
-https://github.com/LUMC/mutalyzer
-
-
-Contributing
-------------
-
-Contributions to Mutalyzer are very welcome! They can be feature requests, bug
-reports, bug fixes, unit tests, documentation updates, or anything els you may
-come up with.
-
-
-Coding style
-------------
-
-In general, try to follow the `PEP 8`_ guidelines for Python code and `PEP
-257`_ for docstrings.
-
-
-Installation
-------------
-
-As a developer, you probably want to install the Mutalyzer package in
-development mode. This will allow you to edit files directly in the source
-directory without having to reinstall.
-
-Please refer to :ref:`install` for general installation instructions. For
-development mode installation, instead of using ``python setup.py install``,
-use::
-
- python setup.py develop
-
-
-Unit tests
-----------
-
-We use `pytest`_ for the unit tests. To run them, just type ``py.test`` from
-the Mutalyzer source directory.
-
-.. note:: The Mutalyzer package must be installed before running the unit
- tests.
-
-
-Working with feature branches
------------------------------
-
-New features are best implemented in their own branches, isolating the work
-from unrelated developments. In fact, it's good practice to *never work
-directly on the master branch* but always in a separate branch. When your work
-is ready, a feature branch can be merged back into master via a *pull request*
-in GitHub.
-
-We assume you forked the Mutalyzer repository to your own namespace in GitHub
-and are working from this fork. Before starting work on your feature, create a
-branch for it::
-
- git checkout -b your-feature
-
-Commit changes on this branch. If you're happy with it, push to GitHub::
-
- git push origin your-feature -u
-
-Now create a pull request to discuss the implementation with the Mutalyzer
-maintainers. This might involve adding additional commits which are included
-in the pull request by pushing your branch again::
-
- git commit
- git push
-
-You may also be asked to rebase your branch on the master branch if it has
-changed since you started your work. This will require a forced push::
-
- git fetch
- git rebase origin/master
- git push -f
-
-If the work is done, a maintainer can merge your branch and close the pull
-request. After the branch was merged you can safely delete it::
-
- git branch -d your-feature
-
-
-Versioning
-----------
-
-A normal version number takes the form X.Y.Z where X is the major version, Y
-is the minor version, and Z is the patch version. Development versions take
-the form X.Y.Z.dev where X.Y.Z is the closest future release version.
-
-Note that this scheme is not 100% compatible with `SemVer`_ which would
-require X.Y.Z-dev instead of X.Y.Z.dev but `compatibility with setuptools
-<http://peak.telecommunity.com/DevCenter/setuptools#specifying-your-project-s-version>`_
-is more important for us. Other than that, version semantics are as described
-by SemVer.
-
-Releases are available from the GitHub git repository as tags. Additionally,
-the latest release is available from the `release` branch.
-
-.. note:: Older Mutalyzer version numbers took the form 2.0.beta-X where X was
- incremented on release.
-
-
-Release procedure
-^^^^^^^^^^^^^^^^^
-
-Releasing a new version is done as follows:
-
-1. Make sure the section in the ``CHANGES`` file for this release is
- complete and there are no uncommitted changes.
-
- .. note::
-
- Commits since release X.Y.Z can be listed with ``git log vX.Y.Z..`` for
- quick inspection.
-
-2. Update the ``CHANGES`` file to state the current date for this release
- and edit ``mutalyzer/__init__.py`` by updating `__date__` and removing the
- ``dev`` value from `__version_info__`.
-
- Commit and tag the version update::
-
- git commit -am 'Bump version to X.Y.Z'
- git tag -a 'vX.Y.Z'
-
-3. Push to the GitHub repository (assuming the remote name is `github` and you
- are working on the `master` branch::
-
- git push github master
- git push github master:release --tags
-
-4. Add a new entry at the top of the ``CHANGES`` file like this::
-
- Version X.Y.Z+1
- ---------------
-
- Release date to be decided.
-
- Increment the patch version and add a ``dev`` value to `__version_info__`
- in ``mutalyzer/__init__.py`` and commit these changes::
-
- git commit -am 'Open development for X.Y.Z+1'
-
-
-.. _pytest: http://pytest.org/
-.. _PEP 8: http://www.python.org/dev/peps/pep-0008/
-.. _PEP 257: http://www.python.org/dev/peps/pep-0257/
-.. _SemVer: http://semver.org/
diff --git a/doc/index.rst b/doc/index.rst
index e0da8e0d..83cd08a1 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -25,15 +25,31 @@ Information for getting Mutalyzer running on a system.
deploy
+Development
+-----------
+
+General information for Mutalyzer developers.
+
+.. toctree::
+ :maxdepth: 2
+
+ issues
+ contributing
+ testing
+ release
+
+
Technical reference
-------------------
-Application design and complete API reference.
+Application design notes and API reference.
.. toctree::
:maxdepth: 2
design
+ strings
+ new-organism
api
@@ -43,10 +59,6 @@ Additional notes
.. toctree::
:maxdepth: 2
- development
- issues
- new-organism
- strings
changelog
copyright
diff --git a/doc/release.rst b/doc/release.rst
new file mode 100644
index 00000000..74043bd0
--- /dev/null
+++ b/doc/release.rst
@@ -0,0 +1,84 @@
+.. highlight:: none
+
+.. _releases:
+
+Releases
+========
+
+
+Versioning
+----------
+
+A normal version number takes the form X.Y.Z where X is the major version, Y
+is the minor version, and Z is the patch version. Development versions take
+the form X.Y.Z.dev where X.Y.Z is the closest future release version.
+
+Note that this scheme is not 100% compatible with `SemVer`_ which would
+require X.Y.Z-dev instead of X.Y.Z.dev but `compatibility with setuptools
+<http://peak.telecommunity.com/DevCenter/setuptools#specifying-your-project-s-version>`_
+is more important for us. Other than that, version semantics are as described
+by SemVer.
+
+Releases are available from the GitHub git repository as tags. Additionally,
+the latest release is available from the `release` branch.
+
+.. note:: Older Mutalyzer version numbers took the form 2.0.beta-X where X was
+ incremented on release.
+
+
+Release procedure
+-----------------
+
+Releasing a new version is done as follows. This assumes remote `origin` is
+the upstream Mutalyzer repository and you have push rights there.
+
+1. Start a release branch and make sure the section in the ``CHANGES.rst``
+ file for this release is complete::
+
+ git checkout -b release-X.Y.Z
+ git add CHANGES.rst
+ git commit -m 'Update changelog'
+
+ .. note::
+
+ Commits since release X.Y.Z can be listed with ``git log vX.Y.Z..`` for
+ quick inspection.
+
+2. Update the ``CHANGES.rst`` file to state the current date for this release
+ and edit ``mutalyzer/__init__.py`` by updating `__date__` and removing the
+ ``dev`` value from `__version_info__`.
+
+ Commit and tag the version update::
+
+ git commit -am 'Bump version to X.Y.Z'
+ git tag -a 'vX.Y.Z' release-X.Y.Z^
+
+3. Add a new entry at the top of the ``CHANGES.rst`` file like this::
+
+ Version X.Y.Z+1
+ ---------------
+
+ Release date to be decided.
+
+ Increment the patch version and add a ``dev`` value to `__version_info__`
+ in ``mutalyzer/__init__.py`` and commit these changes::
+
+ git commit -am 'Open development for X.Y.Z+1'
+
+4. Push these commits to GitHub::
+
+ git push origin release-X.Y.Z -u
+
+ And submit a pull request for this branch.
+
+5. If everything looks ok and the pull request has been accepted you can push
+ the tag and update the `release` branch. Beware to re-tag if the pull
+ request was updated meanwhile. The working branch can be deleted.
+
+ ::
+
+ git push origin vX.Y.Z:release --tags
+ git branch -d release-X.Y.Z
+
+
+.. _SemVer: http://semver.org/
diff --git a/doc/testing.rst b/doc/testing.rst
new file mode 100644
index 00000000..99d3b1f3
--- /dev/null
+++ b/doc/testing.rst
@@ -0,0 +1,19 @@
+.. highlight:: none
+
+.. _testing:
+
+Testing
+=======
+
+We use `pytest`_ for the unit tests. To run them, just type ``py.test`` from
+the Mutalyzer source directory.
+
+.. note:: The Mutalyzer package must be installed before running the unit
+ tests.
+
+Tests are `run automatically on Travis CI
+<https://travis-ci.org/LUMC/mutalyzer>`_ for each pull request and push on
+GitHub.
+
+
+.. _pytest: http://pytest.org/
--
GitLab