reworks the documentation on how to release and how the versioning should be done in pyndl (#159)

* reworks the documentation on how to release and how the versioning should be done in pyndl

* refers to versioning section in Github release step

Author: derNarr

doc/source/development.rst

@@ -180,16 +180,19 @@ request for another license is made and agreed on.
 
 Release Process
 ---------------
+1. Ensure, that the version of the branch to be mered, is adequately increased
+   see Versioning_ below.
 
-1. Merge Pull Requests with new features or bugfixes into *pyndl*'s' ``master``
-   branch. Ensure, that the version is adequately increased (``X.Y+1.Z`` for new
-   features and ``X.Y.Z+1`` for a bugfix).
+2. Merge Pull Requests with new features or bugfixes into *pyndl*'s' ``master``
+   branch.
 
-2. Create a new release on Github of the `master` branch of the form ``vX.Y.Z``.
-   Add a description of the new feature or bugfix
+3. Create a new release on Github of the `master` branch of the form ``vX.Y.Z``
+   (where ``X``, ``Y``, and ``Z`` refer to the new version).  Add a description
+   of the new feature or bugfix. For details on the version number see
+   Versioning_ below.
 
-3. Pull the repository and checkout the tag and create the distribution files
-   using
+4. Pull the repository and checkout the tag and create the distribution files
+   using:
 
 .. code:: bash
 
@@ -198,16 +201,51 @@ Release Process
     python setup.py build  # to compile *.pyx -> *.c
     python setup.py sdist
 
-4. Create GPG signatures of the distribution files using
+5. Create GPG signatures of the distribution files using:
 
 .. code:: bash
 
     gpg --detach-sign -a dist/pyndl-X.Y.Z.tar.gz
 
-5. (maintainers only) Upload the distribution files to PyPI using twine.
+6. (maintainers only) Upload the distribution files to PyPI using twine.
 
 .. code:: bash
 
     twine upload -s dist/*
 
-6. Check if the new version is on pypi (https://pypi.python.org/pypi/pyndl/).
+7. (maintainers only) Check if the new version is on pypi (https://pypi.python.org/pypi/pyndl/).
+
+
+Versioning
+----------
+We use a semvers versioning scheme. Assuming the current version is ``X.Y.Z``
+than ``X`` refers to the major version, ``Y`` refers to the minor version and
+``Z`` refers to a bugfix version.
+
+
+Bugfix release
+^^^^^^^^^^^^^^
+For a bugfix only merge, which does not add any new features and does not
+break any existing API increase the bugfix version by one (``X.Y.Z ->
+X.Y.Z+1``).
+
+Minor release
+^^^^^^^^^^^^^
+If a merge adds new features or breaks with the existing API a deprecation
+warning has to be supplied which should keep the existing API. The minor
+version is increased by one (``X.Y.Z -> X.Y+1.Z``). Deprecation warnings should
+be kept until the next major version. They should warn the user that the old
+API is only usable in this major version and will not be available any more
+with the next major ``X+1.0.0`` release onwards. The deprecation warning should
+give the exact version number when the API becomes unavailable and the way of
+achieving the same behaviour.
+
+Major release
+^^^^^^^^^^^^^
+If enough changes are accumulated to justify a new major release, create a new
+pull request which only contains the following two changes:
+
+- the change of the version number from ``X.Y.Z`` to ``X+1.0.0``
+- remove all the API with deprecation warning introduced in the current
+  ``X.Y.Z`` release
+