diff --git a/doc/sphinx/devDoc/release.rst b/doc/sphinx/devDoc/release.rst index 1e39a35..6238e6f 100644 --- a/doc/sphinx/devDoc/release.rst +++ b/doc/sphinx/devDoc/release.rst @@ -1,6 +1,22 @@ Release Process =============== +General release process +----------------------- + +The versioning for IOR is encoded in the ``META`` file in the root of the +repository. The nomenclature is + +* 3.2.0 designates a proper release +* 3.2.0rc1 designates the first release candidate in preparation for the 3.2.0 + release +* 3.2.0+dev indicates development towards 3.2.0 prior to a feature freeze +* 3.2.0rc1+dev indicates development towards 3.2.0's first release candidate + after a feature freeze + +Building a release of IOR +------------------------- + To build a new version of IOR:: $ docker run -it ubuntu bash @@ -10,29 +26,96 @@ To build a new version of IOR:: $ cd ior $ ./travis-build.sh -To create a new release candidate from RC, +Feature freezing for a new release +---------------------------------- -1. Disable the ``check-news`` option in ``AM_INIT_AUTOMAKE`` inside configure.ac -2. Append "rcX" to the ``Version:`` field in META where X is the release - candidate number -3. Build a release package as described above - -To create a new minor release of IOR, - -1. Build the rc branch as described above -2. Create a release on GitHub which creates the appropriate tag -3. Upload the source distributions generated by travis-build.sh - -To create a micro branch of IOR (e.g., if a release needs a hotfix), - -1. Check out the relevant release tagged in the rc branch (e.g., ``3.2.0``) -2. Create a branch with the major.minor name (e.g., ``3.2``) from that tag -3. Update the ``Version:`` in META -4. Apply hotfix(es) to that major.minor branch -5. Create the major.minor.micro release on GitHub - -To initiate a feature freeze, - -1. Merge the master branch into the rc branch +1. Branch `major.minor` from the commit at which the feature freeze should take + effect. +2. Append the "rc1+dev" designator to the Version field in the META file +3. Commit and push this new branch 2. Update the ``Version:`` field in META `of the master branch` to be the `next` - release version, not the one whose features have just been frozen + release version, not the one whose features have just been frozen. + +For example, to feature-freeze for version 3.2:: + + $ git checkout 11469ac + $ git checkout -B 3.2 + $ # update the ``Version:`` field in ``META`` to 3.2.0rc1+dev + $ git add META + $ git commit -m "Update version for feature freeze" + $ git push upstream 3.2 + $ git checkout master + $ # update the ``Version:`` field in ``META`` to 3.3.0+dev + $ git add META + $ git commit -m "Update version number" + $ git push upstream master + +Creating a new release candidate +-------------------------------- + +1. Check out the appropriate commit from the `major.minor` branch +2. Disable the ``check-news`` option in ``AM_INIT_AUTOMAKE`` inside configure.ac +3. Remove the "+dev" designator from the Version field in META +4. Build a release package as described above +5. Revert the change from #2 (it was just required to build a non-release tarball) +5. Tag and commit the updated META so one can easily recompile this rc from git +6. Update the "rcX" number and add "+dev" back to the ``Version:`` field in + META. This will allow anyone playing with the tip of this branch to see that + this the state is in preparation of the next rc, but is unreleased because of + +dev. +7. Commit + +For example to release 3.2.0rc1:: + + $ git checkout 3.2 + $ # edit configure.ac and remove the check-news option + $ # remove +dev from the Version field in META (Version: 3.2.0rc1) + $ # build + $ git checkout configure.ac + $ git add META + $ git commit -m "Release candidate for 3.2.0rc1" + $ git tag 3.2.0rc1 + $ # uptick rc number and re-add +dev to META (Version: 3.2.0rc2+dev) + $ git add META # should contain Version: 3.2.0rc2+dev + $ git commit -m "Uptick version after release" + $ git push --tags + +Applying patches to a new microrelease +-------------------------------------- + +If a released version 3.2.0 has bugs, cherry-pick the fixes from master into the +3.2 branch:: + + $ git checkout 3.2 + $ git cherry-pick cb40c99 + $ git cherry-pick aafdf89 + $ git push upstream 3.2 + +Once you've accumulated enough bugs, move on to issuing a new release below. + +Creating a new release +---------------------- + +1. Check out the relevant `major.minor` branch +2. Remove any "rcX" and "+dev" from the Version field in META +3. Update NEWS with the release notes +4. Build a release package as described above +5. Tag and commit the updated NEWS and META so one can easily recompile this + release from git +6. Update the Version field to the next rc version and re-add "+dev" +7. Commit +8. Create the major.minor.micro release on GitHub from the associated tag + +For example to release 3.2.0:: + + $ git checkout 3.2 + $ vim META # 3.2.0rc2+dev -> 3.2.0 + $ vim NEWS # add release notes from ``git log --oneline 3.2.0rc1..`` + $ # build + $ git add NEWS META + $ git commit -m "Release v3.2.0" + $ git tag 3.2.0 + $ vim META # 3.2.0 -> 3.2.1rc1+dev + $ git add META + $ git commit -m "Uptick version after release" + $ git push --tags