5. Release Procedure

5.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 4.

  • 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

  • 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

  • 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

5.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. This will trigger the test_py_sdist GitHub action, which builds the source distribution with the correct version identifier and tests it.

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

  6. Create a draft release with the correct tag vX.Y.Z and indicate if the release included changes to the C++ command line tools, the Python package, or both.

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

  8. Change the state of the release to publish.

5.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.

5.2.2. 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

5.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.