search

BerkeleyLab / caffeine

A parallel runtime library for Fortran compilers
https://berkeleylab.github.io/caffeine/
Other
40 stars 7 forks source link

Start documenting a release procedure #85

Closed bonachea closed 6 months ago

bonachea commented 7 months ago

Generating production-quality software releases often involves a number of steps, which tend to grow longer and more complicated as the software evolves.

I suggest we start a "Release procedure" section in docs/README-maintainers.md (or alternatively a new file like docs/README-release.md), documenting a pre-flight checklist of any non-automated actions that need to be performed by the human Release Manager at each release. Creating and following such a release procedure can help to detect any number of easily preventable defects, before a release announcement potentially promotes such defects into a high-profile embarrassing mistake.

As example/inspiration, here is the current release procedure for GASNet-EX.

I don't expect Caffeine's release procedure to be as complicated as GASNet's (possibly ever), largely thanks to automation provided by GitHub integrations that streamline Caffeine releases. However there are still a number of important manual steps that should take place. Here's a few off the top-of-my-head as a starting point:

  1. Nominate a Release Manager with primary responsibility for ensuring each step in this procedure is followed
  2. Validate correctness testing has been performed across all supported systems and supported versions of external dependencies
  3. Update all instances of the copyright year embedded in: LICENSE.txt, fpm.toml
  4. Update all instances of the release package version number embedded in: fpm.toml, install.sh
  5. Update the author list embedded in: fpm.toml
  6. Review top-level README.md and other user-facing documentation for any necessary changes
  7. Produce the ChangeLog
    1. Create draft Release on GitHub
    2. Review/edit the automated ChangeLog
    3. Add/update list of supported features/platforms
    4. Add/update list of high-level changes since last release
    5. Add/update list of known defects/limitations
    6. spell-check and proofread
  8. Produce a release candidate tarball and compel several people to manually validate it on systems of interest
  9. ...
  10. Update the release procedure with any new steps or changes (this should be the final step)
ktras commented 6 months ago

Great idea and great start above on the policy. I recommend adding, something like "Ensure there are no open issues marked with complete-before-release"