RSMTool Release Process

This process is only meant for the project administrators, not users and developers.

1. Recreate the development environment so all unpinned packages are updated to their latest versions. See instructions for this here.

2. Make sure any and all tests are passing in main. Make sure you have also run tests locally in strict mode (STRICT=1 nose2 -s tests) to catch any warnings in the HTML report that can be fixed before the release.

3. Run the tests/update_files.py script with the appropriate arguments to make sure that all test data in the new release have correct experiment ids and filenames. If any (non-model) files need to be changed this should be investigated before the branch is released. Please see more details about running this here.

   Note

   Several files have been excluded from the repository due to their non-deterministic nature so please do not add them back to the repository. The following files are currently excluded:

   • Fairness test files for lr-eval-system-score-constant test

   • Predictions and all evaluation files for linearsvr test.

   Note that the full set of outputs from these test files are also used as input for rsmcompare and rsmsummarize tests. These input files need to be updated following the process under Example 2 in Writing new functional tests. You can also see this pull request for more information.

4. Create a release branch release/XX on GitHub.

5. In the release branch:

   • Update the version number in version.py.

   • Make sure that requirements.txt only has the actual dependencies that are needed to run RSMTool. Any dependencies needed only for development/testing (e.g., sphinx, nose2 etc.) should be moved to requirements.dev. This means that requirements.txt must be a strict subset of requirements.dev.

   • Make sure the versions in doc/requirements.txt are up to date with requirements.txt and only contains the dependencies needed to build the documentation.

   • Make sure .readthedocs.yml is still accurate.

   • Update the conda recipe.

   • Update the documentation with any new features or details about changes.

   • Run make linkcheck on the documentation (i.e. from the doc/ folder) and fix any redirected/broken links.

   • Update the README and this release documentation, if necessary. Make sure to update the documentation badge in the README to use the latest release tag. That documentation version will be created in the steps below.

6. Build the PyPI source and wheel distributions using python setup.py sdist build and python setup.py bdist_wheel build respectively. Note that you should delete the build directory after running the sdist command and before running the bdist_wheel command.

7. Upload the source and wheel distributions to TestPyPI using twine upload --repository testpypi dist/*. You will need to have the twine package installed and set up your $HOME/.pypirc correctly. See details here. You will need to have the appropriate permissions for the ets organization on TestPyPI.

8. Install the TestPyPI package as follows:

   pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple rsmtool
   

9. Then run some tests from a RSMTool working copy. If the TestPyPI package works, then move on to the next step. If it doesn’t, figure out why and rebuild and re-upload the package.

10. Build the new conda package by running the following command in the conda-recipe directory (note that this assumes that you have cloned RSMTool in a directory named rsmtool). You should delete the build directory before running the command below. Note that you may need to comment out lines in your $HOME/.condarc file if you are using ETS Artifactory and you get conflicts:

    conda build -c conda-forge .
    

11. This will create a noarch package with the path to the package printed out to the screen.

12. Upload the package file to anaconda.org using anaconda upload --user ets <path_to_file>. You will need to have the appropriate permissions for the ets organization.

13. Create pull requests on the rsmtool-conda-tester and rsmtool-pip-tester repositories to test the conda and TestPyPI packages on Linux and Windows.

14. Draft a release on GitHub while the Linux and Windows package tester builds are running.

15. Once both builds have passed, make a pull request with the release branch to be merged into main and request code review.

16. Once the build for the PR passes and the reviewers approve, merge the release branch into main.

17. Upload the already-built source and wheel packages to PyPI using twine upload dist/*. You will need to have the twine package installed and set up your $HOME/.pypirc correctly. You will need to have the appropriate permissions for the ets organization on PyPI.

18. Make sure that the ReadTheDocs build for main passes by examining the badge at this URL - this should say “passing” in green.

19. Tag the latest commit in main with the appropriate release tag.

20. Create a new release in Github based on this new tag and auto-generate the release notes. Edit the auto-generated release notes based on the format from the previous releases.

21. Publish the release on GitHub.

22. Go to ReadTheDocs and re-run the build for the main branch. This will pull in the new tag. Once the new tag is visible in ReadTheDocs, create a new documentation version based on this tag and make it the default version.