Release Process

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:

• https://pypi.org/project/ni_measurement_plugin_sdk/#history
• https://pypi.org/project/ni_measurement_plugin_sdk_service/#history
• https://pypi.org/project/ni_measurement_plugin_sdk_generator/#history
• https://ni.github.io/measurement-plugin-python/

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 -x <commit-id>. If there are conflicts, resolve them and re-test.
  • -x includes (cherry picked from commit <commit-id>) in the commit description.
• Push the dev branch to GitHub and create a PR.
  • Prefix the title with [releases/N.N] where N.N is the release branch version.
  • Include a link to the original PR in the description.

Example Versioning

Each example project has its own pyproject.toml that references ni-measurement-plugin-sdk-service. Normally, these should depend on a released version of ni-measurement-plugin-sdk-service (downloaded from PyPI):

[tool.poetry.dependencies]
ni-measurement-plugin-sdk-service = {version = "^1.2.0"}

When updating examples to use unreleased features, it is necessary to temporarily depend on a pre-release version of ni-measurement-plugin-sdk-service (downloaded from PyPI). To do this, add allow-prereleases:

[tool.poetry.dependencies]
ni-measurement-plugin-sdk-service = {version = "^1.3.0-dev2", allow-prereleases = true}

It may also be necessarily to temporarily depend on the local copy of ni-measurement-plugin-sdk-service, until the next pre-release is built. To do this, uncomment the ni-measurement-plugin-sdk-service dependency in the dev dependency group:

[tool.poetry.dependencies]
ni-measurement-plugin-sdk-service = {version = "^1.3.0-dev2", allow-prereleases = true}

[tool.poetry.group.dev.dependencies]
# Uncomment to use prerelease dependencies.
# ni-measurement-plugin-sdk-service = {path = "../..", develop = true}

In the future, we may be able to eliminate this complexity if Poetry adds support for workspaces and sub-projects or we adopt a Poetry workspace plugin.

Publishing an Official Release (e.g. 1.x.0)

Pre-publishing steps:

• In releases/1.x, update the ni-measurement-plugin-sdk-service and ni-measurement-plugin-sdk-generator pyproject.toml files to specify version = 1.x.0, in order to work around https://github.com/ni/measurement-plugin-python/issues/162
• In releases/1.x, update the example pyproject.toml dependencies:
  • Ensure that all examples depend on a released version such as "^1.x.0" (not "^1.x.0-dev3").
  • Ensure that allow-prereleases has been removed from all examples.
  • Ensure that the file = "../.." dependencies in the dev dependency group have been commented out.
• In the releases/1.x settings, temporarily remove "Check examples" from Require status checks to pass before merging. This is necessary because the example projects now depend on a version of ni-measurement-plugin-sdk-service that has not been published.

Post-publishing steps:

• In main, update the example pyproject.toml dependencies. Since version 1.x.0 has been published, this should not make the "Check examples" workflow fail.
• In main, update the README.md files in the root directory and the examples directory to refer to the newly released version and the corresponding version of InstrumentStudio. See #587 for an example.
• In the releases/1.x settings, restore "Check examples" in Require status checks to pass before merging.