[[PageOutline]]
This page is an ongoing effort to document current release process, gather important discussions points from the dev mailing list and progress toward a fully fledged release procedure with as much automation as possible.

= Infrastructure notes =
Since we are using git for version control there are a few caveats that have to be considered in defining the release process:
 * git is distributed and [http://www.ericsink.com/entries/dvcs_dag_1.html does not keep a linear history] like centralised VCS; 
 * pretty much [http://ricroberts.com/articles/getting-to-grips-with-git-part-2-branches-and-tags everything is considered a branch];
 * there is a [http://nvie.com/posts/a-successful-git-branching-model/ successful git branching model] out there that we can draw upon.
 * Worth reading for maintenance [https://code.google.com/p/git-core/source/browse/Documentation/howto/revert-a-faulty-merge.txt revert a faulty merge]

= Versioning scheme =
Versions are numbered according to [http://semver.org semantic versioning] (we may reference the fields X.Y.Z as M.m.p to better indicate Major, minor and patch numbering), starting with 8.4.0. Tentative interface definition is defined by the standards supported in the [wiki:Features features matrix] and the command line tools parameters.

= Branching model =

A single main repository is maintained (as we already have).

The repository contains three types of ''branches'' on it:
 * '''master''' (single instance) -- the currently available branch, which will be the main development branch;
 * '''release''' (multiple instances) -- When starting release process (consolidation of beta, rc, and other testing releases), a ''release'' branch is created with name '''release_M.m'''. These branches will allow maintenance of past releases, while development continues in the master branch.
  * Where M=Major version; m=minor version; All patch versions will belong to the same "minor" branch
   * Note: consider broader detail such as per-major version release line (fewer branches) or cleaning up branches for un-maintained versions
 * '''feature''' (multiple instances) -- Indicating a branch where a new feature is developed. This is kept in a branch separate from the others, as developing new features results in unstable code.
  * Feature branches are named '''feature-!FeatureName''', e.g. `feature-MultiPointSupport`

As an example consider release 8.4.0 and following bugfixes and regression patches:
{{{
   release_8.4 (branch)
  /tag v8.4.0 ------ P ---- P* -- P---------->  tag v8.4.1 ------- P* ---- P ------->  tag v8.4.2
 /                    \            \
master (branch)        \            \
-- F -- F ------ F  --- P -----------P-- (until time comes for a new release (either 8.5 or 9.0)
  
P = bugfix/regression  ; P* = bugfix not applicable to master (due to new features) ; F = new feature development
}}}

A local branch can be checked out and with recent versions of git also a remote one with the same name:
{{{
#!sh
git checkout release_M.m

#should give you output similar to:
Branch release_M.m set up to track remote branch release_M.m from origin.
Switched to a new branch 'release_M.m'`
}}}

Note that branches on the main repository are remote branches that, if not automatically tracked on checkout as above, might need a specific [http://stackoverflow.com/questions/67699/how-do-i-clone-all-remote-branches-with-git checkout procedure] to be worked with.

NOTE: Is there a way to "export" a tag directly from a remote git repo? This will save users from getting all the clone to just test a beta or rc. We provide source tarballs for that meanwhile.

Every release, both testing (cleaned up afterwards) and final, is marked by a ''tag'' according to the pattern '''vM.m.p''' (we are keeping the "v" prefix for historical reasons) in the repo, which can be checked out with
{{{
#!sh
git checkout vM.m.p
}}}

Single branches may also be cloned, in case the full repo is not needed:
{{{
#!sh
# clone only the `release_8.4' branch, locally
git clone -b release_8.4 git://kahlua.eecs.jacobs-university.de/rasdaman.git

# [...] Checking out a newly created branch, e.g. `featureX':
git branch -rv 
    origin/master               96e9534 Fixed array constant for rgb (Ticket 157)
    origin/release_8.4          5eacb06 Fix netcdf import when only one variable is imported
    origin/featureX             1234567 Start implementation of feature X.
git checkout -b featureX origin/featureX
}}}

For help on handling ''git'', see ProvideFix page.

= Initial process =

Releases can only be made if the [http://rasdaman.eecs.jacobs-university.de/trac/rasdaman/build build status] is successful for the latest (or chosen one for release preparation) commit.

== 1. Create branch and tag according to the aforementioned naming scheme - ''Requires write access to the repo'' ==
{{{
#!sh
VERSION="v$MAJOR.$MINOR.0"
RELEASE="release_$MAJOR.$MINOR"

git pull
git fetch

git tag $VERSION
git push origin $VERSION

git branch $RELEASE
git push origin $RELEASE
}}}

== 2. Create source tarball ==

{{{
#!sh
# from local clone
git archive  --output=rasdaman-v8.4.0.tgz v8.4.0
}}}
{{{
#!sh
# directly from repo ''currently not working''
git archive --remote=git://kahlua.eecs.jacobs-university.de/rasdaman.git --output=rasdaman-v8.4.0.tgz v8.4.0
}}}

== 3. Build RPM and test it on local system ==


== 4. These to be done as close together as possible ==
 * Update all links to download and RPM repo then
 * Announce release
   * to -dev and -users lists if release candidate / patch
   * also to -announce (to be established) in case of final release


= Open issues =

== Testing time ==
We should establish some time frame to advance in the release process: now we wait one week before advancing -rc if bugfixes come in.