6. Release Procedure

6.1. Pre-release actions

Seed the release process

  • Determine the new version identifier vX.Y.Z needed for the release in accordance with the contents of Section 5.

  • Create a new release “super” issue (i.e., a GitHub issue that simply contains a list of links to other GitHub issues).

    • Content could be seeded from previous release’s issue

    • All gatekeepers should converge on set of high-level tasks/goals for release

    • Create an issue for each approved task and add link to issue in the release “super” issue

    • As work proceeds, a link to each PR can be placed next to its associated issue’s link

  • Optionally, create a post-release issue to group together all new issues created during this prerelease/release work that won’t be dealt with during the release, but that should be dealt with shortly after the release to maintain inertia and capitalize on the recent work/experience.

    • This should be maintained up-to-date. Tasks that ultimately can be put off until later can be moved out of this issue. Issues that will no longer be dealt with as part of the review can be transferred from the release to post-release issue.

  • Notify BAND framework team that a new version will be released to determine what steps will need to be made, if any, within the framework once the release is finalized.

Once all tasks have been executed

  • Determine if new Meson version constraints should be made and implement these consistently in meson.build and pyproject.toml.

  • Check if a new version of the Eigen package is available through the Meson build system’s wrapdb facility and assess if the new version should be adopted and tested.

  • Review and update all metadata in setup.py

  • Review all external dependencies and their stated versions to see if they need updating and address on a feature branch

  • Modernize all repository actions in accord with changes to supported versions and updated GH action infrastructure

  • Review README including badges for necessary cleaning/updates

    • New references?

    • Update citation?

    • Check links

    • Confirm that main README is consistent with Python package README and landing page of Sphinx docs

    • Check contents of Python package README compatible with PyPI by executing twine check <sdist.tar.gz>.

  • Review all documentation associated with the repository including examples to determine if any updates still need to be made and address on a feature branch

    • Sphinx/RTD User and Developer Guides

  • Confirm continued adherence to all binding requirements (e.g., BAND SDK)

  • Set the version of the C++ command line tools in their Meson build system specification file to the correct version identifier determined earlier

  • Set the version of the R package in its DESCRIPTION file to the correct version identifier determined earlier. Set release date as well.

6.2. Release actions

When a particular commit on main is to be deemed a release,

  1. Confirm that all actions ran successfully on the proposed commit

  2. Perform any review of the action logs deemed necessary based on the changes included in the release

  3. Perform any review of the artifacts created by the actions deemed necessary based on the changes included in the release

  4. Tag the release commit with the name vX.Y.Z and push.

  5. Create and publish a release with the correct tag vX.Y.Z and indicate if the release included changes to the C++ command line tools, the Python package, the R package, or some combination of these. This will trigger the test_py_sdist GitHub action, which builds the source distribution with the correct version identifier and tests it.

  6. Confirm that the action passed with no errors or warnings. Review the action’s log.

  7. Carry out all necessary checks for the different software products (see below).

Todo

If issues are found that require a new commit, the tag can be reassigned to a new commit (extra effort to force update of tag in remote and for other developers to move tag in their clones as well?). After that, what needs to be done to reissue the release at the updated tag?

6.2.1. Command line tools

  1. Gatekeepers to follow installation guide to install and test the command line tools. This should include a review of the build logs and confirming correct logging of the new release version identifier.

6.2.2. R package

The following can likely be piggybacked onto the above command line tool testing.

  1. Gatekeepers to follow installation guide to install and test the R package in a clean environment

6.2.3. Python package

Note

Since PyPI does not permit the uploading of a revised version to overwrite a previous upload of that same version, these steps should likely be done only after having carried out the sanity checks for all other software products.

If the changes in the release do not include changes to the C++ command line tools or the Python package, then no actions are needed. In particular, we do not upload to PyPI the source distributions created with this new versioned release.

Otherwise,

  1. Download the source distribution artifact from the test_py_sdist action and confirm that filename contains the desired version identifier.

  2. Decompress the source distribution with tar xvfz and confirm correct, minimal contents including the presence of the LICENSE file.

    • One side effect of the use of setuptools-scm is that by default it includes in the distribution all files located within openbt_pypkg. However, many files and folders in that space do not need to be distributed (e.g., Flake8 configuration files and OpenBT command line tools installed during development in src/openbt/bin). This is what “minimal” means above. Files and folders that should not be included in the distribution are specified in MANIFEST.in.

    • Review the metadata to ensure correct and complete. This should include the correct specification of the new version identifier.

  3. Gatekeepers to follow installation guide to install and test the Python package in clean virtual environments via all provided mechanisms (aside from pip install) as well as by installing from the release’s source distribution.

  4. Create a clean virtual environment, update pip, and install twine.

  5. Use that venv to publish the downloaded source distribution to PyPI following the twine instructions. Note that to upload the distribution, you will need to know either your username and password or have an API token that you can generate on the PyPI website under your personal settings.

  6. Review the package’s webpage on PyPI.

  7. In a clean virtual environment, follow the installation guide for installing from pip and to test the installation

  8. Ask Taweret team to trigger actions, confirm that this newest version is being installed, and that all actions pass. Review Jupyter book rendering of trees-based notebooks.

6.3. Post-release actions

  • Carry out all necessary tasks to integrate the release within the BAND framework.

  • Update this document based on lessons learned.

  • Review all open issues and pull requests. Comment and close where possible. Clean-up the post-release issue in preparation for carrying out the work that it requests.