Skip to content

Software Release Procedure

Jump to bottom
Bryan Hilbert edited this page Dec 5, 2024 · 11 revisions

The Mirage team performs a software release when significant new changes to the code base have been made. We employ the following procedure for creating a new release:

1. Create a new branch for changes related to the version release procedure
2. Update the release notes
3. Tag the commit with the new version number
4. Open, review, and merge pull request with the release procedure changes
5. Push the new tags to github
6. Create a new tag/release on GitHub/GitLab
7. Upload new version of software to PyPI

Detailed instructions for performing a release are given below:

  1. Create a new branch for changes related to the version release procedure

Make sure that your local version of the master branch is up-to-date. A new branch with the naming convention versionx.y.z should be opened off of master, where versionx.y.z is the version number of the release (e.g. version2.2.0). This branch should be used for the changes described below. Note that a branch name of "version2.2.0" is preferred over "v2.2.0" because it must have a different name than the git tag added in step 3.

  1. Update the release notes

In CHANGES.rst, write a concise but detailed description of all of the notable changes that have occurred since the last release. One way to acquire this information is to scroll through the commit history of the project, and look for commits in which a pull request was merged.

  1. Tag the commit with the new version number

Once you have committed the updates to CHANGES.rst, add a tag to the commit using (e.g.): git tag -a v2.2.0 -m "Version 2.2.0"

  1. Open, review, and merge pull requests with the release procedure changes

Once you've committed the changes from (3) in your branch, push your branch to GitHub to the upstream remote. Then open two pull requests: one that points to the production branch (i.e. stable), and one that points to master. Assign reviewers. Either you or the reviewer should eventually merge these pull requests.

  1. Push the tags to origin/upstream. e.g. git push origin v2.2.0

  2. Create a new tag/release on GitHub

Once the pull request into the production branch from (4) has been merged, click on the releases button on the main page of the repository, then hit the "Draft a new release" button. The "Tag version" should be the version number of the release, the "Target" should be the production branch, the "Release title" should (also) be the version number of the release, and the "Description" should match that of the changelog entry in (4). Once all of that information is added, hit the big green "Publish" release button.

  1. Upload new version of software to PyPI

To upload the new tagged version of the software to PyPI, run the following while still in the new branch (not the updated production branch):

  • python setup.py sdist bdist_wheel

Upload using twine and a Pypi API token.

Set your username to token Set your password to the token value, including the pypi- prefix For example, if you are using Twine to upload your projects to PyPI, set up your $HOME/.pypirc file like this:

[pypi] username = token password = pypi-toke_code_here

Once the ~.pypirc file is created, you can do:

  • twine upload --skip-existing dist/*

If that doesn't work, you can follow the instructions above about setting username to token and password to the token value.

Clone this wiki locally