updates documentation

documentation/sphinx_static/development.rst

@@ -10,46 +10,40 @@ Versioning guidelines
 Version tracking for :mod:`TurTLE` is done with ``git`` (see https://git-scm.com/
 for description).
 The branching model described at
-http://nvie.com/posts/a-successful-git-branching-model/ should be
-adhered to as strictly as possible.
+http://nvie.com/posts/a-successful-git-branching-model/ is used for
+inspiration.
+However, experience shows that our team does not need a ``develop``
+branch, hence we branch from and merg to ``master``.
+If a situation comes up where we will need to maintain different
+versions, we will branch from the respective tags as needed.
 
 The usable ``VERSION`` number will be constructed according to semantic
 versioning rules (see http://semver.org/), ``MAJOR.MINOR.PATCH``.
 In principle, if you use :mod:`TurTLE` and you've created children of the
 :class:`DNS <TurTLE.DNS>` class, you should not need to rewrite your code unless
 the ``MAJOR`` version changes.
+The package version is maintained through ``git`` tags.
 
-There are 2 main branches, ``master`` and ``develop``.
 ``CMake`` will essentially call ``git`` to read in the ``VERSION``: it will get the
 latest available tag.
-If the active branch name contains either of the strings ``develop``,
-``feature`` or ``bugfix``, then the full output of ``git describe --tags``
-will be used;
-otherwise, only the string before the dash (if a dash exists) will be
-used.
+The full output of ``git describe --tags`` is placed in
+``TURTLE_VERSION_LONG`` and the stripped down ``MAJOR.MINOR.PATCH`` is
+placed in ``TURTLE_VERSION``, and made available to CMake and the C++
+code itself.
 
 At the moment the following rules seem adequate.
 Once I get feedback from someone who actually knows how to handle bigger
 projects, these may change.
 
-1. New features are worked on in branches forked from ``develop``, with
+1. New features are worked on in branches forked from ``master``, with
    the branch name of the form ``feature/new``.
-   Feature branches are merged back into ``develop`` only after all tests
+   Feature branches are merged back into ``master`` only after all tests
    pass.
-2. Whenever the ``develop`` branch is merged into ``master``, the last
-   commit on the ``develop`` branch is tagged with ``MAJOR.MINOR``.
-3. Whenever a bug is discovered in version X.Y, a new branch called ``vX.Y``
-   is forked from the corresponding ``master`` merge point.
-   A new bugfix branch is forked from ``vX.Y``, the bug is fixed.
-   The last commit in the bugfix branch is tagged X.Y.1.
-   This bugfix branch is merged into all affected branches (this includes
-   ``vX.Y``).
-   After merging, the respective merge points into branches other than
-   ``develop``, ``bugfix`` or ``feature`` are tagged accordingly;
-   there's no need to tag ``develop`` etc since those contain the git
-   commit in the version anyway.
-4. Whenever a bug is discovered in version X.Y.Z, a bugfix branch is
-   forked from ``vX.Y``, and then rule 3 is adapted accordingly.
+   Typically the ``MINOR`` value will be increased at these merges.
+2. Whenever a bug is discovered, a new branch called ``bugfix/something``
+   is created (preferably forked from the earliest commit where the bug is
+   apparent).
+   When merged, the ``PATCH`` value is increased.
 
 Please also read "code review" section below.