Release instructions

This page contains the information that you need in order to make a release of the python-control package. The page is under construction.

Test release candidate

We assume that the release candidate is in the main branch, with all pull requests associated with the release merged.

1. Verify that all unit tests execute properly (GitHub Actions + local)
   • Linux: check build status at https://github.com/python-control/python-control/actions
     • look at conda-based test with and without slycot to make sure there are no unexpected warnings
     • run os-blas-test-matrix workflow to make sure everything works on various platforms
   • Local (optional): check that tests pass on local machine using pytest for Python 3.x, with and without Slycot.
     • pytest: should have no errors or warnings
     • PYTHON_CONTROL_ARRAY_AND_MATRIX=1 pytest: should have no errors or warnings
     • cd examples; PYTHONPATH=.. ./run_examples.sh: should exit with 'All examples ran successfully'
     • PYTHONPATH=.. ./run_notebooks.py: should exit with 'All examples ran successfully'
   • Verify that all checks pass for all variants
2. Verify that documentation builds properly (ReadTheDocs)
   • Check build status at https://readthedocs.org/projects/python-control/builds/
     • Look at entry for html to make sure there are no warnings that need to be fixed
   • Inspect documentation for latest release to verify that it looks OK
     • Note: current version of readthedocs is not rendering bullet lists correctly (fixed in PR #817)

Tag release

1. Create an annotated tag in git (in main branch in GitHub repository):
   • git tag -a x.y.z -m "python-control version x.y.z"
   • git push --tags
   • Note: don't use the GitHub release mechanism at this stage (you need an annotated tag, which requires this step)
2. (optional) Mark all pull requests contained in the release with the milestone associated with the release

Deploy release

1. github: On the project’s GitHub page, click the releases tab and then press the “Draft a new release” button to create a release from the appropriate tag.
   • Note: github may do this automatically when it sees the tag get posted
   • Use "Auto-generate release notes" to generate draft release notes; edit for style and consistency
2. pypi
   • Create the source distribution and upload to PyPI:
     • git clean -xfd
     • Generate the version file: python -m setuptools_scm
     • Generate the souce distribution: python -m build
     • upload to PyPi using twine: twine upload dist/*
       • Note that you may need to modify this to use an API token: https://pypi.org/help/#apitoken
     • log in to PyPi.org as admin and grab the sha256 hash from the download page for later use
3. conda-forge: Send a PR with the new version number and sha256 hash of the source release to https://github.com/conda-forge/control-feedstock.
   • Fork control-feedstock to your account and make changes in your fork
     • If you already have the forked code, then 'git pull upstream main'
   • Update recipe/meta.yml: change the version number, sha256 hash, and reset the build number to 0
   • If there have been changes to the conda build process, you may need to do more extensive edits to meta.yaml
   • Push changes back to your github account and generate a pull request.
   • Once checks are complete (and successful), merge pull request
4. readthedocs: Log in to the python-control project page and go to the Admin tab and choose Versions from the sidebar. Make sure the release version is "active" and "public" and that it builds properly (new build will trigger when release version is marked as active). One the build is complete, set the the default version (Admin -> Advanced Projects Setting) to be the version just released and remove "active" setting from older versions.
   • If math images don't render properly, try this:
     • Set up a redirect from /en/<ver>/generated/_images/$rest to /en/<ver>/_images/ to fix a bug in the way math images are handled.
     • Currently maintaining the last version (0.x), last major release (0.x.y), and last minor releases (0.x.y.z)
     • Confirm that source code links work and send you to the right version of the code
5. Update release notes page:
   • Move release description from Current release to Past releases
   • Move release documentation for specified release from Upcoming releases to Current release
   • Copy release notes from GitHub releases page
   • If Upcoming releases is empty, create a new entry titled python-control TBD
6. Verify ability to install slycot and control via pip and conda on your local machine (just to make sure everything "took")
   • It can sometimes take a while (minutes to hours) for the control package to show up on conda-forge
7. python-control-announce: Send release announcements to python-control-announce@sourceforge.com