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.
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.
Changelog updates with
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
pip install -U github-activity
Get the latest version.
git checkout main,
git remote -v, and
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.
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.
Revise PR labels
PRs listed under
Other merged PRsdoesn’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.
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 ....
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#
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
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.
Open a pull request
Make a commit named like
Add changelog for 1.2.3and open a PR with it titled the same.
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
Version updates with
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.
pyproject.toml to update the project’s specific
files containing a version reference, such as
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
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.