Merge pull request #280 from richardkchapman/documentation

Add VERSION file describing our version name policy
Reviewed-by: Gavin Halliday <ghalliday@hpccsystems.com>

CONTRIBUTORS

@@ -53,7 +53,7 @@ topic branches from.
 
 To create a topic branch, use git checkout with the -b argument:
 
-    git checkout -b fix-broken-thing
+    git checkout -b fix-broken-thing master
     Switched to a new branch 'fix-broken-thing'
 
 Branch names should be kept reasonable short but long enough to describe what they are
@@ -86,16 +86,21 @@ Note that additional changes can be made to the branch after you have generated
 request - for example in order to address issues raised by a reviewer. There is no need
 to close a request and open a new one in such circumstances.
 
+If your topic branch is implementing a new feature, it should be based from the master
+branch on the unstream repository. If it is fixing a bug that cannot wait for the next
+feature release, it should be based from the merge-base of the master and current stable
+branches.
+
 Pull upstream changes into your fork regularly
 ==============================================
 
-If a branch is in development for a while, you should regularly merge in the upstream
-master, rather than waiting until you are ready to issue the pull-request before
-discovering that other changes clash with yours, or render your change moot. If a branch
-has diverged too far from the master that it cannot be easily or safely merged, it is
-likely to be rejected by the maintainers.
+If a new feature in a branch is in development for a while, you should regularly merge
+in the upstream master, rather than waiting until you are ready to issue the pull-request
+before discovering that other changes clash with yours, or render your change moot. If a
+branch has diverged too far from the master that it cannot be easily or safely merged, it
+is likely to be rejected by the maintainers.
 
-To pull in upstream changes::
+To pull in upstream changes:
 
     git remote add upstream git://github.com/hpcc-systems/HPCC-Platform.git
     git fetch upstream

VERSIONS

@@ -0,0 +1,55 @@
+Branch and version strategy
+===========================
+
+Versions
+========
+
+Version numbers take the form MAJOR.MINOR.POINT_SEQUENCE
+
+The MAJOR version will change only with a significant architectural change.
+The MINOR version number changes when new features are introduced.
+The POINT version number changes when bugs are fixed.
+The SEQUENCE number is changed when a new candidate package is created during
+closedown testing.
+
+Versions that have been closed down, tested, and passed as suitable for general
+release are given even MINOR and POINT numbers. Odd numbers are reserved for
+builds for testing purposes only.
+
+In addition to the version number there is a MATURITY string that may be found
+in the version string. The maturities in use are:
+
+<none>   - a stable build
+rc       - a release candidate.
+trunk    - a system built from the master branch (the 'bleeding edge')
+*_debug  - Any of the above suffixed by _debug if built with debug enabled
+
+Branches
+========
+
+The master branch contains the latest accepted code. Code in the master branch
+should normally be fully functional, but may not yet have gone through rigorous
+testing or be considered production-ready. If you want to build a system in order
+to experiment with extending the code, or to test new features that have not yet
+been included in a stable build, then you should build the master branch.
+
+The stable branch points to the current version of the system that has been
+through the full closedown testing cycle and is considered production-ready. If
+you want to build a local version of a stable build - perhaps to install on a
+distro for which a pre-packaged binary is not available, then you should build
+the stable branch. Note that stable is rebased when a new MAJOR or MINOR version
+number release is published.
+
+Branches with names starting candidate- contain code that is being prepared for
+release as a stable version. Fixes for bugs discovered during closedown testing
+will be merged into the current candidate- branch.
+
+Tags
+====
+
+Tags corresponding to the release versions will be applied to points on the
+candidate- branch where binary releases have been built and published.
+
+A tag with the name split-X.Y will refer to the point at which the branch for
+candidate-X.Y split off from master. This is normally the point where bug fixes
+intended for release in the X.Y series should be based.

sourcedoc.xml

@@ -278,8 +278,9 @@
                     point in the future.
                 </para>
                 <para>
-                    The { that starts a new scope and the corresponding } to close it are placed on a 
-                    new line by themselves, and are not indented.
+                    The { that starts a new scope and the corresponding } to close it are placed on a
+                    new line by themselves, and are not indented. This is sometimes known as the Allman
+                    or ANSI style.
                 </para>
             </sect2>
             <sect2>