Release procedures

Update this procedure with any new providers. Copy/paste markdown as new issue for each new release, and update as necessary.

Make a perfect tarball

• For libfabric:
  • For new minor releases, make stable v1.Y.x branch
  • Cherry-pick relevant commits from master
  • Update the libfabric version number in configure.ac to the final release version
  • Update the version number in include/windows/config.h
  • Update the version numbers in include/rdma/fabric.h
    • FI_VERSION_MAJOR should match first number in configure.ac
    • FI_VERSION_MINOR should match second number in configure.ac
  • Update providers to support the version in fabric.h
    • Tip: search for .fi_version and FI_VERSION.
  • Update the shared library version number(s) in Makefile.am per the GNU Libtool shared library version number rules
    • Always check the libtool rules, but as general rules: Stable releases (v1.x.y - where y is updated) should never see API changes; stable release c:r:a versions should normally be updated to c:r+1:a. Minor releases (v1.x.0 - where x is updated) may see API additions or backwards compatible API changes. If there are no API changes, minor release c:r:a versions should be updated to c:r+10:a relative to the highest numbered stable release. The r+10 allows for up to 9 additional stable releases without resulting in a collision in the release numbers. If there are new APIs or backwards compatible changes, update c:r:a to c+1:0:a+1. Non-compatible API changes should strongly be avoided.
    • 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:
    • README.md
    • AUTHORS (via git log --pretty=format:'%aN <%aE>' | sort --ignore-case | uniq > AUTHORS)
    • Update the years in the copyright notices in COPYING
    • Provider Feature Matrix (PFM)
      • Add a link to this version's PFM on the main PFM wiki page
      • GNI provider
      • ND provider
      • mlx provider
      • PSM provider
      • PSM2 provider
      • RxD provider
      • RxM provider
      • Sockets provider
      • TCP provider
      • UDP provider
      • usNIC provider
      • verbs provider
    • NEWS.md
      • GNI provider
      • ND provider
      • mlx provider
      • PSM provider
      • PSM2 provider
      • RxDprovider
      • RxM provider
      • Sockets provider
      • TCP provider
      • UDP provider
      • usNIC provider
      • verbs provider
    • Man pages
      • man/fi_gni.7.md
      • man/fi_nd.7.md
      • man/fi_mlx.7.md
      • man/fi_psm.7.md
      • man/fi_psm2.7.md
      • man/fi_rxd.7.md
      • man/fi_rxm.7.md
      • man/fi_sockets.7.md
      • man/fi_tcp.7.md
      • man/fi_udp.7.md
      • man/fi_usnic.7.md
      • man/fi_verbs.7.md
    • ...any other doc files that may not be included in this list
• For fabtests:
  • Provide a release that matches the libfabric release number, even if there are no changes.
  • 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 (via git log --pretty=format:'%aN <%aE>' | sort --ignore-case | uniq > AUTHORS)
    • Update the years in the copyright notices in COPYING
    • ...any other doc files that may not be included in this list
• Update the libfabric release date in NEWS.md
• Update the fabtests version number in configure.ac to the final release version
• 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 (from a tarball)
  • Check that the version number and release date is correct in the installed man pages
• Build and install fabtests (from a tarball)
• Ensure fabtests make distcheck passes
• Ensure all providers pass all (relevant) tests
  • gni
  • nd
  • mlx
  • psm
  • psm2
  • rxm
  • sockets
  • udp
  • usnic
  • verbs
• 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
  • gni
  • nd
  • mlx
  • psm
  • psm2
  • rxm
  • sockets
  • udp
  • usnic
  • verbs

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
• 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
• Make a new milestone for the release after this one (e.g., v1.Y.x+1 or v1.Y+1.0)
• Re-target all open issues for an appropriate future milestone
• Ensure that new Github milestones exist in ofiwg/libfabric and ofiwg/fabtests for the next release
• Update the libfabric version number in configure.ac to <NEXT_VERSION>a1
• Update the fabtests version number in configure.ac to <NEXT_VERSION>a1
• Send an email to the ofiwg mailing list announcing the release

Update infrastructure

• As ofiwg-bot on flatbed.openfabrics.org
  • Make a new directory for tarballs under /var/www/html/downloads/ofiwg/nightly_tarballs
  • Adjust the current sym link in the same directory to point to the new directory
  • Make a new directory under /home/ofiwg-bot/cron/build-logs for build logs for this series
  • Adjust the current sym link in the same directory to point to the new directory