README-release file for GASNet
https://gasnet.lbl.gov

The purpose of this document is to record the steps required for a public
release of GASNet.  This is NOT required reading for most developers.

See also:
 + README: GASNet usage documentation
 + README-devel: GASNet design information and coding standards
 + README-git: Rules developers are expected to follow when committing

GASNet Release Procedure
========================

* Start from a *clean* clone of the git repo.
  Either start from a NEW clone, or use one of "git clean" or "git stash -o"
  to remove untracked files.  Otherwise it's very easy for stray files to end
  up in the release.

* Under normal circumstances you will generating a release on the 'master'
  branch after use of a "release branch" to merge in all the new work from
  'develop' and update version numbers, etc.  This procedure begins with the
  creation of the "release branch" for a hypothetical 2040.8.0 release:
    $ git checkout -b release/2040.8.0 develop

* To allow collaboration on the release work, one may optionally "publish"
  the release branch on bitbucket:
    $ git push -u origin release/2040.8.0

* Increment the version number for each item or software module that has
  changed since the last public release:
  Package version number, in configure.in AND docs/GASNet-EX.txt:
    GASNET_RELEASE_VERSION_*
  - the major and minor versions are the nominal year and month of the package
  - For bug-fix release patches, update the patch number for each (ex: 2020.4.2).
  - For development, update the patch number whenever it's useful (new feature,
    big bugfix), and/or whenever we put out a new 'stable' release (or hand
    out a snapshot to a user). The patch-level should be even for beta versions
    marked as "stable" for users, or odd for general development.
  GASNet spec version numbers, in configure.in AND docs/GASNet-EX.txt:
    GASNET(EX)_SPEC_VERSION_MAJOR - increment on backwards compatibility break
    GASNET(EX)_SPEC_VERSION_MINOR - increment for new features that don't break
                                backwards compatibility, zero on MAJOR change
  GASNet tools spec version numbers, in configure.in AND docs/GASNet-EX.txt AND README-tools
    GASNETT_SPEC_VERSION_MAJOR - increment on backward compatibility break
    GASNETT_SPEC_VERSION_MINOR - increment for new features that don't break
                                 backwards compatibility, zero on MAJOR change
  other/gasnet_portable_platform.h - increment EVERY release (even without changes)
  Conduits: */gasnet_core_fwd.h, */gasnet_extended_fwd.h
  GASNet document spec version: docs/gasnet.texi

* On 'develop' advance the version numbers in configure.in (odd minor and patch
  numbers for development), and apply a corresponding annotated tag for use by
  the "git describe" command:
    $ git checkout develop
    [ edit GASNET_RELEASE_VERSION_* in configure.in, and commit it ]
    $ git tag -a -m "GASNet development version 2040.8.1" gex-2040.8.1 develop
    $ git push origin develop gex-2040.8.1
  This change is made immediately after creation of the release branch to ensure
  concurrent development commits on develop have appropriate git describe and
  version ids reflecting the fact they won't appear until the NEXT release.
  However this commit will also cause a conflict when the release branch is later
  merged that will need to be resolved. If no concurrent development is expected,
  this step can be postponed until after the release branch is merged.

* Review commit messages and write a summary of user-visible changes and 
  bug fixes since last public release - add to ChangeLog

* Update license.txt with any new authorship credits

* Commit all changes made in the previous steps

* ./Bootstrap the sources

* From a separate builddir, do a configure, then
    $ gmake all distcheck [GASNET_DOCS=PATH_TO_GASNET_DOCUMENTATION]
  the release candidate archive.  See below for info on the optional
  GASNET_DOCS setting.

* Unpack the archive and diff against the source tree to find missing files,
  especially documentation and auxiliary files.  Check that other/contrib
  contains any cross-configure scripts that are intended for distribution.
  The following command may be used to list any files which have been
  added to the Git repository since the previous release:
    $ git diff --name-status [previous-release-tag] | grep ^A

* Verify that ./unBootstrap removes all generated files:
  In the repository directory:
    $ ./unBootstrap
    $ git status --ignored
  If "git status" listed any "ignored files" then you need to update
  unBootstrap (and if it lists any "untracked files" then you didn't
  start with a clean repo).

* If the spec has not changed since the previous release, consider reusing
  the generated files from a past release.  That can be automated by adding
     GASNET_DOCS=PATH_TO_GASNET_DOCUMENTATION
  to the distcheck step, above.
  Otherwise, check the spec documents were generated correctly & clean up
  if necessary (regenerate the .ps on Linux).

* Test the release candidate on all directly supported systems and conduits,
  with both debug+stats+trace and ndebug configs, and all supported backend
  C compilers:
   Cray XC: aries (and mpi if time/allocation allows)
   Linux-Ethernet: mpi, udp, ofi
   Linux-InfiniBand: mpi, ibv
   Linux-OmniPath: ofi (plus mpi and ibv if time/allocation allows)
   Windows/Cygwin: smp+pthreads
   Mac OS X: smp+pthreads, smp+sysv
  SEGMENT_EVERYTHING should be tested on all conduits supporting it.
  In most cases these test will be conducted as part of Berkeley UPC's
  release testing (the "gasnet-tests" suite of the BUPC test harness).

* Install the release candidate and ensure that share/docs/gasnet contains
  all the intended documentation, including any files referenced by README.
  Any missing should be added to INSTALL_DOCS in the top-level Makefile.am
  Do NOT add developer-only documents (eg this file) to the distribution.

* Resolutions for any "issues" (bugs, missing docs, etc.) should be fixed
  on the release branch and re-tested as necessary.  These will be merged
  back to 'develop' at the end of this procedure.  However, if there is
  something critical, it can be cherry-picked to 'develop' without any
  problems (git is smart enough to deal with this at the later merge step).

* Clone a *second* copy of the repository for the tools-only distribution:
    $ git clone --branch release/2040.8.0 \
            https://bitbucket.org/berkeleylab/gasnet gasnet-tools
    $ cd gasnet-tools
    $ ./Bootstrap -o
  make a separate build directory, configure and "gmake all distcheck"
  to build the tools-only tarball.
  The use of the URL for anonymous access to BitBucket is INTENTIONAL,
  so that you cannot accidentally commit the re-writes done by the
  "-o" option to ./Bootstrap.

* Iterate the appropriate steps above until you have final release
  tarballs for both GASNet and GASNet_Tools

* Before merging the release branch be sure you have up-to-date clones of both
  'master' and 'develop'.  While it is unlikely that 'master' has changed since
  you began, concurrent development on 'develop' should be considered normal.
  Since you haven't committed anything to either branch in your local repo,
  the following should be safe:
    $ git checkout develop
    $ git pull --ff-only
    $ git checkout master
    $ git pull --ff-only

* Advanced warning #1:
  If there were any "hot fixes" on 'master' since the previous release
  then you will may need to resolve conflicts in the "git ... finish ..." or
  "git merge ..." step below.  If you are motivated to accept any conflict
  resolution other than "-X theirs" (meaning: "use the release branch in the
  case of all conflicts") then you should abort the merge and resolve the
  conflict through changes to the release branch (and generate new tarballs).

[TODO: need explicit commands for reverse-the-revert below]
* Advanced warning #2:
  In the event that any feature on 'develop' was reverted on the release branch
  (e.g. due to test failures) but you wish to retain the feature on 'develop',
  you will need to take extra steps to deal with this.  The preferred sequence 
  would be create/rebase the release branch prior to the introduction of the
  problematic feature. If this is not possible, then fix things up on the release 
  branch before it is merged to 'master', and consider skipping the release
  branch merge to develop. Individual unrelated improvements on the release
  branch can instead be cherry-picked to develop.

* Now merge the release branch to 'master' (where the general public will
  expect to find sources intended for general consumption), tag the release,
  merge back to 'develop' as well, and delete the transient release branch.
    $ git checkout master
    $ git merge --edit --no-ff release/2040.8.0
    $ git tag -a gex-2040.8.0 -m "GASNet release 2040.8.0" master
    $ git checkout develop
    $ git merge --edit --no-ff release/2040.8.0
    $ git branch -d release/2040.8.0

* Check the tag landed in the correct place as follows:
    $ git show gex-2040.8.0
  The output should show the commit message for the *merge*.  If it shows any
  of the earlier commits, move it using "--force":
    $ git tag --force -a gex-2040.8.0 -m "GASNet release 2040.8.0" master
  OR, just "--force" it without checking - this is perfectly safe.

* Check carefully that everything is exactly as you wish before you push:
    $ git push origin master gex-2040.8.0
  This is the only step of this entire procedure that cannot be undone.

* If you chose to "publish" the release branch on bitbucket, then use the
  following command to delete the (now unused) release branch:
    $ git push --delete origin release/2040.8.0

* Generate ("gmake dist") the GASNet and GASNet_Tools tarballs one more
  time from a checkout of the tagged commit to embed the proper git version
  info.  This must be done before any more annotated tags are generated
  in the following steps, to ensure the git-describe output uses the new
  release tag.

* If the GASNet or tools spec versions have changed, they get tags too:
    $ git tag gex-spec-2.1 master
    $ git push origin gex-spec-2.1
  and/or
    $ git tag gasnet-tools-spec-1.32 master
    $ git push origin gasnet-tools-spec-1.32

* If this GASNet release has a paired Berkeley UPC release, then one should
  apply a tag to mark the correlation:
    $ git tag berkeley-upc-2040.8.0 master
    $ git push origin berkeley-upc-2040.8.0
  We avoid using an annotated tag here so that "git describe" won't use it.

* In Bugzilla (before publishing the release):
  + Add the version number of this release
  + Add a milestone for the next release

* In gasnet-web CVS repository:
  + Add both tarballs and specs (GASNet and GASNet_Tools) to CVS
  + Update index.html for the new release
    Minimum update is new versions, sizes and MD5s for the tarballs
  + Add new version to .cvsignore

* On the gasnet.lbl.gov server:
  + "cvs up" to get the new tarballs and index.html
  + "tar xfz ..." to extract the new GASNet release (not Tools)
  + Move the "dist-ex" symbolic link:
    $ ln -sfn GASNet-2040.8.0 dist-ex

* Update release mirrors:
  + https://bitbucket.org/berkeleylab/gasnet/downloads/
  + https://sourceforge.net/projects/gasnet/files/
  + mantis:/data/www/html/snapshot
  + ftg4 + class-web VMs: /var/www/html/EX (spec, symlink and tarball)

* Email a release notice with the most recent ChangeLog entry, using
  the following headers:
  To: gasnet-announce@lbl.gov, gasnet-users@lbl.gov
  Reply-To: gasnet-devel@lbl.gov
  Subject: GASNet Release A.B.C

* In Bugzilla CLOSE the bugs resolved in this release, following the 
  protocol described in the BUPC's release procedure.

* Revise this document with any additions, corrections or changes

--------------------------------------------------------------------------
  The canonical version of this document is located here:
    https://bitbucket.org/berkeleylab/gasnet/src/develop/README-release

  For more information, please email: gasnet-devel@lbl.gov
  or visit the GASNet home page at:   https://gasnet.lbl.gov
--------------------------------------------------------------------------
