Difference between revisions of "Creating a Release"

From Mpich
Jump to: navigation, search
(Create a final tarball for the release using the release.pl script)
(Mark the milestone complete on TRAC)
Line 109: Line 109:
* Update links at https://www.mpich.org/documentation/manpages/
* Update links at https://www.mpich.org/documentation/manpages/
=== Mark the milestone complete on TRAC ===
=== Mark the milestone complete on GitHub ===
* If there are any pending tickets, move them to the next release.
* If there are any pending issues, move them to the next release.
=== Update any package managers we're responsible for ===
=== Update any package managers we're responsible for ===

Revision as of 16:38, 19 December 2019

Creating the release has the following steps:

Check the Release Status

See the page https://github.com/pmodels/mpich/milestones for the relevant release to ensure that all pending bugs have been fixed.

Ensure that all testing has been performed

This includes both the results of the nightly tests and the special tests that are used to check that common configuration options continue to work and that the coding standards have been followed.

TODO: There was a comprehensive checklist of the prerequisites for a release. That needs to be placed here. Recent releases have not checked this list. What follows is a partial list

Check all tests. This includes

  1. The four major test suites (MPICH, C++, Intel, MPICH2)
  2. The special tests (See [[1]] ); these are important for testing that various options and compiler choices work
  3. The "random" tests in the nightly test should not indicate any problems; these are used to test correct handling of the configure options
  4. Ensure that the Debugger interface works; (configure mpich with --enable-debuginfo; make src/mpi/debugger/tvtest) can be used as a start; a check with totalview should also be performed (e.g.: "totalview mpiexec -a -n 4 src/mpi/debugger/tvtest" and make sure that message queue status works fine)
  5. Ensure that make dist works for the MPI testsuite. That is, make sure cd test/mpi ; make dist produces a tar file that can be unpacked and the test suite built against an installed MPI (not necessarily MPICH, but that is usually sufficient for this test).
  6. Ensure that there are no performance artifacts, both for point-to-point and collective operations.

Update all necessary files and commit them to the trunk

  • Update the version numbers (including current:revision:age ABI) in maint/version.m4. Note: don't update the release date, as it will be automatically replaced during tarball generation.
  • Update the CHANGES file. You can find the commits that went in by going through the git log information.
    • Before committing CHANGES, it is recommended to send CHANGES, at least, to [email protected] in order to make sure everything is clear.
  • Update the RELEASE_NOTES file. This requires input from everyone, and generally requires asking each person (in person) if the current restrictions still apply, and if any new ones should be added.
  • Update the README.vin if necessary.

Create a final tarball for the release using the release.pl script

  • Before using release.pl, make sure these tools are ready: latex, doctext and txt2man (from freecode)
    • txt2man can be installed using package manager. For example,
   apt-get install txt2man (on Ubuntu)
   brew install txt2man (on Mac)
  • Get the release.pl script in maint from the trunk and run it as
 ./release.pl --branch=[git_branch_to_use]  --version=[version] --git-repo=[path_to_git_repository]


 ./release.pl --branch=master --version=3.1.2 --git-repo=https://github.com/pmodels/mpich


  • The release.pl requires specific autotools to run. Even with a newer version, you may not be able to run the script. The script did it on purpose to test it maintain the correctness of ABI. You will need the exact version of autotools to build and release the tarball.
  • While we use tags are in the format "vX.Y.Z", the version format should not have the leading "v", so it should be "X.Y.Z".

Create a release tag

(NOTE: below are the notes from when we managed our source in SVN and the project was still called "MPICH2", though they never 100% accurately reflected reality. Since the switch to Git, we haven't been following this model quite as closely. Also, some of the instructions below don't make as much sense in Git. These instructions are helpful history, but not how we do things now.)

  • A branch is only created once for a complete release cycle, i.e., 1.0.7rc1, 1.0.7rc2, 1.0.7, 1.0.7p1, etc., will have just one branch. At what point a release branch is to be created is not decided yet (e.g., alpha releases, beta releases, RCs, full release), but we currently do that at the time of the RC release. This essentially means an svn-copy of the trunk to the branches/release directory.
  • If this is the first RC for this release cycle, create a branch. Branches are named as mpich-X.Z.Y, where X, Y, Z are the major, minor and revision version numbers.
  • If this is not the first RC, merge all required changes from the trunk to the release branch.
  • A tag is created for every release from the branch. Tag is essentially an svn-copy of the branch to the tags/release directory. Tags are named as mpich-X.Y.Z[ext], where [ext] is a1/a2/.. (for alpha releases), rc1/rc2/.. (for RC releases), etc.

This is how we manage release tags and branches under git:

  • tag the release version in your local git repository:
  git tag -a -m "tagging 'vX.Y.Z'" vX.Y.Z [COMMIT_HASH] ([COMMIT_HASH] defaults to HEAD if omitted)
  • It is strongly recommended that you create the release tarball locally and completely test it before pushing the tag to the origin repository.
  make testing 
  • Once the candidate tarball has been thoroughly tested and inspected, push the tag to the mpich and hydra repositories:
  git push mpich tag vX.Y.Z 
  • Long term release branches are still discouraged at this time, though they can easily be created after the fact as long as the tag exists. One easy way to do this in git is: git push origin vX.Y.Z:refs/heads/maint-vX.Y.Z, which will create a new branch on the remote "origin" named "maint-vX.Y.Z" which starts at the same commit as the tag "vX.Y.Z". Local branches can easily be created to track this remote branch in the usual way: git branch maint-vX.Y.Z --track origin/maint-vX.Y.Z ; git checkout maint-vX.Y.Z (or the equivalent shorthand: git checkout maint-vX.Y.Z, as long as that branch name only exists in exactly one remote).

Update MPICH website

  • Create directory for tarballs
  cd /mcs/mpich/tarballs
  mkdir X.Y.Z
  • Copy MPICH and Hydra tarballs into new directory, e.g.,
  cp mpich-3.1.2.tar.gz /mcs/mpich/tarballs/3.1.2
  cp hydra-3.1.2.tar.gz /mcs/mpich/tarballs/3.1.2
  • For full release update documentation as well: README.txt, installguide.pdf, userguide.pdf (with mpich-[version]- prefix)
  mkdir ~/sandbox-3.1.2 && cd ~/sandbox-3.1.2
  tar zxvf /mcs/mpich/tarballs/3.1.2/mpich-3.1.2.tar.gz
  cp ./mpich-3.1.2/README  /mcs/mpich/tarballs/3.1.2/mpich-3.1.2-README.txt
  cp ./mpich-3.1.2/doc/installguide/install.pdf  /mcs/mpich/tarballs/3.1.2/mpich-3.1.2-installguide.pdf
  cp ./mpich-3.1.2/doc/userguide/user.pdf  /mcs/mpich/tarballs/3.1.2/mpich-3.1.2-userguide.pdf
  • Update the downloads svn repository
  cd /mcs/mpich/tarballs/
  svn add X.Y.Z
  svn commit
  chmod -R g+w X.Y.Z
  • Update website to reflect new release: downloads page, main page, and new page: https://www.mpich.org/wp-admin/
    • Create a new announcement post (in Left Box, News & Events).
    • Change the version number in "Settings -> MPICH Release (at bottom of the left)"
  • Also for full release - update the online Manpages. Change the "latest" symlink to point to the new version.
  cp -rf ~/sandbox-X.Y.Z/mpich-X.Y.Z/www /mcs/mpich/docs/vX.Y.Z
  cd /mcs/mpich/docs
  rm -f latest
  ln -sf vX.Y.Z latest
  chgrp -h mpi latest

Mark the milestone complete on GitHub

  • If there are any pending issues, move them to the next release.

Update any package managers we're responsible for

At the moment, this is just Homebrew. To do this, you need to:

  • Fork the original on github to get your own version
    • Yes, this has to be done on GitHub itself
  • Make a branch to make your changes to the MPICH
    • Doing this in master will only bring pain. Don't do it.
  • Make the changes to Library/Formula/mpich2.rb
    • At the moment, this formula is still named mpich2 and can't be changed.
    • There is however, an alias to mpich so people can just say that they want to install that.
  • Unless there have been any major changes to the way people should build MPICH, all this requires is changing the URL for the formula to whatever the new URL is.
    • If there have been new changes to the way people do the usual configure/make/make install setup, the rest of the script may need to change.
    • If there are new options that we should include in the package manager versions (don't read "add all new options here"), then they can be added.
  • Push your changes to your own fork on GitHub
  • Send a pull-request to the original mxcl repository

Send out the release announcement to [email protected] and party! Yay!