Skip to content

Release Process

Jump to bottom
Brad Keryan edited this page Sep 25, 2023 · 15 revisions

Branching

Active development for the next release occurs on the main branch.

During finalization, we create a release branch (e.g. releases/1.2) in order to control which changes target the imminent release vs. the next release after that. Changes that are intended for both the imminent release and subsequent releases should be made in the main branch and cherry-picked into the release branch. Changes that only apply to the imminent release (such as version numbers) may be made directly in the release branch.

Versioning

  • This project uses semantic versioning. Compatibility breakage should be rare and should be accompanied by incrementing the major version.
    • This does not apply to examples or code that ships with the examples (e.g. _helpers.py, _nidcpower_helpers.py, teststand_fixture.py).
  • After creating a new release branch, update pyproject.toml in the main branch to have the next pre-release version number. For example, after creating releases/1.2, update pyproject.toml to specify version = "1.3.0-dev0". This reduces confusion about which branch is which.
  • It is not necessary to manually update the version in pyproject.toml before publishing each pre-release or release. The publish workflow does this automatically.
  • Manually update the -devN version when adding a new feature, so that you can update the examples that use the new feature to depend on this version.

Tagging

Git tags for pre-releases are version numbers in the form 1.2.3-dev4.

Git tags for releases are version numbers in the form 1.2 or 1.2.3.

This repo does not prefix Git tags with the letter v.

Publishing

This GitHub repository has an automated workflow for publishing packages to PyPI and publishing documentation to GitHub Pages.

This automated workflow is initiated by manually creating a new release in the GitHub web UI:

  • On the releases page, click Draft a new release.
  • Choose a tag for the new release, based on the desired version number. The publish workflow will automatically update the version number in pyproject.toml based on the tag.
  • Choose the appropriate target branch for the new release:
    • Early pre-releases should be released from main.
    • Late pre-release and official releases should be released from a release branch such as releases/1.2.
  • If this is a pre-release, check Set as a pre-release. If this is an official release, uncheck Set as a pre-release and check Set as the latest release.
  • Click Generate release notes and edit the generated release notes for brevity and style.
  • Click Save draft. Consider sharing the link to the draft release with the other repo maintainers.
  • Once the versions and release notes are ready, click Publish release.

Once the automated workflow completes successfully, check that the new version is visible in these locations:

Cherry-Picking

To cherry-pick a change into a release branch:

  • Make sure the PR submitting the change to the main branch is completed.
  • Check out the target release branch and create a dev branch.
  • Run git log main and find the commit id for the merged PR (not your dev branch commit id).
  • Run git cherry-pick <commit-id>. If there are conflicts, resolve them and re-test.
  • Push the dev branch to GitHub and create a PR[.
    • Prefix the title with [releases/N.N]
    • Include a link to the original PR in the description.
Clone this wiki locally