Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Add release instructions to DEVELOPMENT.md #1070

Merged
merged 5 commits into from
May 21, 2024
Merged

docs: Add release instructions to DEVELOPMENT.md #1070

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
fec2808
docs: Add release instructions to DEVELOPMENT.md
aborgna-q May 17, 2024
c6c7476
some rewording
aborgna-q May 17, 2024
5efc5c3
Merge branch 'main' into ab/release-guide
aborgna-q May 17, 2024
9959fd8
Apply suggestions from code review
aborgna-q May 20, 2024
eb5d7fc
Add link to CODEOWNERS when mentioning the release team
aborgna-q May 20, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 47 additions & 0 deletions DEVELOPMENT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -136,3 +136,50 @@ We accept the following contribution types:
- ci: CI related changes. These changes are not published in the changelog.
- chore: Updating build tasks, package manager configs, etc. These changes are not published in the changelog.
- revert: Reverting previous commits.

## :shipit: Releasing new versions

We use automation to bump the version number and generate changelog entries
based on the [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) labels. Release PRs are created automatically
for each package when new changes are merged into the `main` branch. Once the PR is
approved by someone in the [release team](.github/CODEOWNERS) and is merged, the new package
is published on PyPI or crates.io as appropriate.

The changelog can be manually edited before merging the release PR. Note however
that modifying the diff before other changes are merged will cause the
automation to close the release PR and create a new one to avoid conflicts.

### Rust crate release

Rust releases are managed by `release-plz`. This tool will automatically detect
breaking changes even when they are not marked as such in the commit message,
and bump the version accordingly.

To modify the version being released, update the `Cargo.toml`,
CHANGELOG.md, PR name, and PR description in the release PR with the desired version. You may also have to update the dates.
Rust pre-release versions should be formatted as `0.1.0-alpha.1` (or `-beta`, or `-rc`).

### Python package release

Python releases are managed by `release-please`. This tool always bumps the
minor version (or the pre-release version if the previous version was a
pre-release).

To override the version getting released, you must merge a PR to `main` containing
`Release-As: 0.1.0` in the description.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What happens if you have two python packages? How do you override per-package? I had a quick look but can't see.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Where did the version bump in #1040 come from? Did you push directly to the release branch? Perhaps we should stick with that method, I am concerned that github will be annoying about merging empty commits.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tried to look a bit into release-please's code, but this in not really clear.

  • The python release type. Auto-bumps the version according to the changes (e.g. patch release for fix:, minor/major release depending on breaking changes. This didn't quite work with the last (breaking) release, it seems it bumped 0.2.0a1 to0.2.1 as a breaking release. It's incorrect but harmless.

  • The docs about Release-as just say to put in on a commit. My guess from what I gather is that that affects commits with relevant changes to the repo (commits that do not modify the subproject are ignored), so we should add the flag to a relevant commit only.

Python pre-release versions should be formatted as `0.1.0a1` (or `b1`, `rc1`).

### Patch releases

Sometimes we need to release a patch version to fix a critical bug, but we don't want
to include all the changes that have been merged into the main branch. In this case,
you can create a new branch from the latest release tag and cherry-pick the commits
you want to include in the patch release.

You will need to modify the version and changelog manually in this case. Check
the existing release PRs for examples on how to do this. Once the branch is
ready, create a [github release](https://github.com/CQCL/hugr/releases/new).
The tag should follow the format used in the previous releases, e.g. `hugr-py-v0.1.1`.

For rust crates, you will need someone from the release team to manually
publish the new version to crates.io by running `cargo release`.