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