Release procedures

It's time to release -- woo hoo!

Make sure that each of the following items are done before publishing a new tarball:

Make a perfect tarball

• For libfabric:
  • Update the version number in configure.ac to the final release version
    • All version numbers must be 3 digits: X.Y.Z (even if Z is 0).
  • Update the version numbers in include/rdma/fabric.h:
    • FI_VERSION_MAJOR should match the first digit of the version number in configure.ac
    • FI_VERSION_MINOR should match the second digit of the version number in configure.ac
  • Update the shared library version number(s) in Makefile.am per the GNU Libtool shared library version number rules
    • Pro tip: run git log --stat --no-merges > log.txt as the head of the master
    • Examine this file all the way back to the Git tag for the previous release; look for changes to files in src/, include/, and include/rdma to help determine if the c:r:a version values need to change
    • Pro tip: run git log <last_version_tag>..HEAD -- include/rdma
    • Will show all changes to the external header files since the last release. The last_version_tag should be similar to v1.3.0
  • Update all documentation files (especially including dates and version numbers), including:
    • Update the Provider Feature Matrix (PFM) for this release
    • Add a link to this version's PFM on the main PFM wiki page
    • NEWS.md, including link to "Provider Feature Matrix vX.X.X"
    • README.md
    • AUTHORS
    • man/fi_<providers>.7.md
    • Update the years in the copyright notices in COPYING
    • ...any other doc files that may not be included in this list
• For fabtests:
  • Update the version number in configure.ac to the final release version
  • Update all documentation files (especially including dates and version numbers):
    • README
    • README.md
    • AUTHORS
    • Update the years in the copyright notices in COPYING
    • ...any other doc files that may not be included in this list
• Make final libfabric-x.y.z.tar.gz and libfabric-x.y.z.bz2 tarballs
• Make final fabtests-x.y.z.tar.gz and fabtests-x.y.z.bz2 tarballs

Ensure that the tarball actually works

• Ensure libfabric make distcheck passes
• Build and install libfabric
  • Check that the version number and release date is correct in the installed man pages
• Ensure fabtests make distcheck passes
• Build and install fabtests (from a tarball and with the newly-installed libfabric)
• Ensure all providers pass all (relevant) tests

Test backwards compatibility

• Build and install previous version of libfabric (from a tarball)
• Build and install previous version of fabtests against previous version of libfabric (from a tarball)
• rm -rf the installation of the previous version of libfabric
• Set LD_LIBRARY_PATH to point to the installation of the new libfabric
• Re-run all fabtests and ensure that they still pass

Test packaging

• Ensure that building a libfabric source RPM works on a RHEL system
• Ensure that building the libfabric binary RPMs (libfabric and libfabric-devel) work on a RHEL system
• Install both RPMs on an RHEL system
• Test building and running fabtests against the RPM-installed libfabric
• Test building a libfabric-based program with the output from pkg-config with the RPM-installed libfabric.pc
• Uninstall libfabric-devel and ensure libfabric programs still run correctly

Do the release

• git tag -a vX.Y.Z on the libfabric master branch
• git tag -a vX.Y.Z on the fabtests master branch
• git push --tags --dry-run to libfabric. Remove --dry-run when you're convinced it is correct.
• git push --tags --dry-run to fabtests. Remove --dry-run when you're convinced it is correct.
• Make a libfabric release corresponding to the git tag on https://github.com/ofiwg/libfabric/releases
• Make a fabtests release corresponding to the git tag on https://github.com/ofiwg/fabtests/releases
• Update Homebrew formula in homebrew-core. Make sure to follow the CONTRIBUTING.md guide.
• Copy the man/*.[0-9].md files from exactly the same Git hash that was used to make the official tarball to the gh-pages branch of the libfabric Git repo
  • Put them in vX.Y.Z/man/
  • Also put an index.md file in that directory (copy one from the prior releases and edit it to reflect this version, and add/remove any man pages as relevant for this release)
• Update the main index.md page:
  • Add links to the new libfabric and fabtests release tarballs
  • Add link for the man pages for this release
• Close the relevant Github milestone in ofiwg/libfabric and ofiwg/fabtests
• Ensure that new Github milestones exist in ofiwg/libfabric and ofiwg/fabtests for the next release
• Send an email to the ofiwg mailing list announcing the release

After the release

• Update the libfabric and fabtests version numbers in configure.ac and include/rdma/fabric.h to be the next version, but with an a1 suffix (i.e., alpha version 1).
  • E.g., if you just released v1.3.0, update the version to be v1.4.0a1.
• Update crontab to put new nightly tarballs in the new version directory
  • E.g., in .../ofiwg/nightly_tarballs/v1.4.x/