Release Process

There are a number of steps to creating a new release. Including updating the documentation, tagging a release on GitHub (complete with release notes), and updating distributed packaging systems.

Release Process

1. Verify the experimental status of all tools. Any tool which should be moved out of experimental status can follow the guidance for moving a tool out of experimental (below).
2. Update the in-source documentation
   1. The version number must be updated in doc/rst/conf.py and mpifileutils.spec.
   2. The man pages must be regenerated, moved to man/, and committed back to the repo. Guidelines can be found in the doc/README.md file.
3. Update dist/builddist to account for new version and corresponding versions of dependencies. Note that there is a chicken-and-egg problem in that, ideally, this should refer to the git tag of the new release, which doesn’t exist yet. One can build using the latest development branch and then substitute the intended version tag after testing the build.
4. Tag the release on GitHub. Details on writing release notes can be found below.
5. Update the spack package
6. Update the default version on readthedocs:
   • Once in the mpifileutils project, go to “Versions” and edit an inactive version. Check “active” and save.
   • Then go to “Admin”, select “Versions” from the sidebar, and select the new release version from the pull-down. Hit “Save” at the bottom.

Release Notes Format

The release notes should be grouped by libmfu, then tool (alphabetically), and finally bug fixes.

Sample release notes from version 0.9:

We’ve officially converted to CMake! Instructions for building are here: https://mpifileutils.readthedocs.io/en/v0.9/build.html

New Features:

• dcmp: include nanoseconds when comparing timestamps
• dcmp: new --lite option to compare files based on file type, file size, and modification time rather than file content
• drm: new --aggressive option to delete files while walking
• dsync: default behavior no longer deletes files at the destination, deleting now requires new --delete option
• dsync: optionally copies in batches with --batch-files option as form of self-checkpointing long running dsync jobs
• drm: fix segfault when deleting a large number of files
• libmfu: avoid problematic MPI I/O external32 for more consistent file format
• libmfu: support for GPFS ACLs

New Tools:

• dfind: filters file list based on different criteria
• dreln: update symlinks whose targets use absolute paths, useful after dsync

Moving a Tool out of Experimental

1. Update the src/CMakeLists.txt file
2. Update various documentation references:
   • Don’t build the man page in doc/rst/conf.py
   • Don’t reference the man page in doc/rst/index.rst
   • Move the mention in the tools index doc/rst/tools.rst
   • Remove any generated man pages sitting in man/
   • Update the man page installation in man/CMakeLists.txt
3. Update the developers tools listing