VERSIONS

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 include:

<none>    - a stable build
closedown - gathering bugfixes for a new POINT release
rc        - a release candidate.
beta      - a beta release
betarc    - a release candidate for a beta release
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. Individual release candidates will be tagged along these
branches.

When preparing a patch or a GitHub pull request, a new git branch should be created
based on the appropriate target - if the change is to go into the 5.2.2 build, then
base it on candidate-5.2.2, for example. All changes that are accepted into a candidate
branch are normally upmerged to any later unreleased candidate branches, and to master,
without requiring separate pull requests. Pull requests against master will go in the
next major release version.

Tags
====

Tags corresponding to the release versions will be applied to points on the
candidate- branch where binary releases have been built and published.

Rules for major, minor and point releases
=========================================

It should always be safe to upgrade a system to the latest point release with matching
major and minor version. If upgrading to a new major or minor version, users should always
use the latest available point release. It is important to observe the following rules:

1. Sequence number increases on a gold release are for build errors and regressions only.
   A new sequence release should be considered as rendering earlier sequence releases invalid
   and unsupported.
2. NEVER include new functionality in point releases - only bug fixes
3. If a bug fix introduces incompatibilities that might break existing ECL code, or
   require it to be recompiled, it should be held until the next minor release.
4. Any bug fix that is included in a gold release for a give major.minor version must
   also be available (if relevant) in a gold release of all later released major.minor versions.