mdtest/doc/sphinx/devDoc/release.rst

157 lines
5.6 KiB
ReStructuredText

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, e.g., from the 3.2 release branch::
$ docker run -it ubuntu bash
$ apt-get update
$ apt-get install -y git automake autoconf make gcc mpich
$ git clone -b 3.2 https://github.com/hpc/ior
$ cd ior
$ ./travis-build.sh
Alternatively you can build an an arbitrary branch in Docker using a bind mount.
This will be wrapped into a build-release Dockerfile in the future::
$ docker run -it --mount type=bind,source=$PWD,target=/ior ubuntu
$ apt-get update
$ apt-get install -y git automake autoconf make gcc mpich
$ ./travis-build.sh
Feature freezing for a new release
----------------------------------
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, and
update the NEWS file to have this new version as the topmost heading
3. Commit and push this new branch
2. Update the ``Version:`` field in META `of the main branch` to be the `next`
release version, not the one whose features have just been frozen, and update
the NEWS file as you did in step 2.
For example, to feature-freeze for version 3.2::
$ git checkout 11469ac
$ git checkout -B 3.2
$ vim META # update the ``Version:`` field to 3.2.0rc1+dev
$ vim NEWS # update the topmost version number to 3.2.0rc1+dev
$ git add NEWS META
$ git commit -m "Update version for feature freeze"
$ git push upstream 3.2
$ git checkout main
$ vim META # update the ``Version:`` field to 3.3.0+dev
$ vim NEWS # update the topmost version number to 3.3.0+dev
$ git add NEWS META
$ git commit -m "Update version number"
$ git push upstream main
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 && git push --tags
Applying patches to a new microrelease
--------------------------------------
If a released version 3.2.0 has bugs, cherry-pick the fixes from main 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
----------------------
This is a two-phase process because we need to ensure that NEWS in main
contains a full history of releases, and we achieve this by always merging
changes from main into a release branch.
1. Check out main
2. Ensure that the latest release notes for this release are reflected in NEWS
3. Commit that to main
Then work on the release branch:
1. Check out the relevant `major.minor` branch
2. Remove any "rcX" and "+dev" from the Version field in META
3. Cherry-pick your NEWS update commit from main into this release branch.
Resolve conflicts and get rid of news that reflect future releases.
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 main
$ vim NEWS # add release notes from ``git log --oneline 3.2.0rc1..``
$ git commit
Let's say the above generated commit abc345e on main. Then::
$ git checkout 3.2
$ vim META # 3.2.0rc2+dev -> 3.2.0
$ git cherry-pick abc345e
$ vim NEWS # resolve conflicts, delete stuff for e.g., 3.4
$ # 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
# vim NEWS # add a placeholder for 3.2.1rc2+dev so automake is happy
$ git add NEWS META
$ git commit -m "Uptick version after release"
Then push your main and your release branch and also push tags::
$ git checkout main && git push && git push --tags
$ git checkout 3.2 && git push && git push --tags