Making releases#

To make a new release, we should be able to follow the project’s RELEASE.md file. Since these files can get outdated, its good to refer to this document and our template project’s RELEASE.md file from time to time to keep it updated.

Release ambitions#

  • To document and automate the release process well enough for repository maintainers to have the agency to make regular releases.

  • To follow a versioning scheme such as SemVer 2, where we update the MAJOR.MINOR.PATCH versions according to the versioning scheme.

  • To maintain changelogs, and update them for each release.

  • To keep release practices across projects updated by upstreaming release practice improvements from individual projects to the template project’s files and the team-compass project’s documentation, and to to downstream updates from there to other projects.

Release practices#

Changelog updates with github-activity#

We look to have our changelogs summarize most pull requests that has been merged, we use github-activity to help us with this.

Create PR list with github-activity#

  1. pip install -U github-activity

    Get the latest version.

  2. git checkout main, git pull, git remote -v, and git log

    Ensure you will work against the latest changelog file and that github-activity will be able to inspect the latest git tags locally.

    The remote and log commands are to help you check you didn’t just update against a remote fork.

  3. github-activity --heading-level=3

    First acquire a preliminary list of pull requests, then revise labels and titles of pull requests, then acquire a final list of pull requests to update the changelog with.

    1. Revise PR labels

      PRs listed under Other merged PRs doesn’t have a label to make it listed in another category. If you think they should be, visit the PR and add a suitable label to it.

    2. Revise PR titles

      PR titles should describe the change made for readers of a changelog. Check if there is a PR title that is worth updating.

      As an example, in the jupyterhub/oauthenticator projects its relevant for users to know if a change affected a specific authenticator class they use. Due to that, we’ve tried to let that be captured in the title, such as [GitHub] Fix ....

    3. Revise final list

      Some pull requests could be seen as irrelevant to list, for example we could opt to omit automatic updates to the versions of pre-commit hooks or github actions.

Create a changelog entry#

  1. Come up with the new version number

    Assuming we are using SemVer 2 as a versioning scheme, we should:

    • increment the major version if a breaking change has been made

    • increment the minor version if a new features has been added

    • increment the patch version if a bug has been fixed

  2. Update the changelog file

    • Add the previously generated PR list.

    • Align formatting with previous releases.

    • Add a preliminary release date.

    • At least for major releases, lead with a manually written summary.

  3. Open a pull request

    Make a commit named like Add changelog for 1.2.3 and open a PR with it titled the same.

  4. Ready for release

    With a changelog PR approved, you can self-merge it and make a release according to the project’s RELEASE.md file. Before merging, update the preliminary release date if needed, or add a commit doing it before using tbump.

Version updates with tbump#

Our RELEASE.md files often describes how to use tbump to update version strings in files such as _version.py in a commit, tag the commit, and push it.

Projects configure tbump via pyproject.toml to update the project’s specific files containing a version reference, such as _version.py, setup.py, and package.json.

The template project’s pyproject.toml file provides an example on how to configure tbump, and the template project’s RELEASE.md file provides an on how to use it.

Publishing to PyPI#

Publishing a release to PyPI should be automatic as soon as a git tag is pushed. A git tag is typically pushed by the use of tbump according to a RELEASE.md file, and the automation to publish to PyPI is typically done by a GitHub workflow named release.yaml.

The template project’s .github/workflows/release.yaml file and the template project’s RELEASE.md file can be inspected for more details about this.

Publishing to conda-forge#

Publishing a release to conda-forge should be managed by a dedicated feedstock GitHub repository, and the RELEASE.md file should link to it for reference as done in the template project’s RELEASE.md file.