diff --git a/RELEASE.md b/RELEASE.md new file mode 100644 index 000000000..426807343 --- /dev/null +++ b/RELEASE.md @@ -0,0 +1,110 @@ +# Releasing the aya project + +This document describes the process of releasing the aya project. + +## Release process + +### 0. Who can release? + +Only members of the aya-rs GitHub organization in the `owners` team have the +permissions to: + +- Push packages to crates.io +- Make the necessary changes in GitHub to create a release + +### 1. cargo smart-release + +This project uses [cargo-smart-release](cargo-smart-release) to automate the +release process. The following commands *should* be sufficient to release the +project: + +> [!IMPORTANT] +> The `--execute` flag is used to actually perform the release. +> Remove it to do a dry-run first. +> +> The `--no-push` flag is used to prevent pushing the release commit and tags +> to the remote repository. This is required because we have branch protection +> set up to prevent commits to the main branch that are not made through a pull +> request. You have 2 options: either temporarily disable the branch protection +> or open a pull request with the changes made by the release. +> +> The `--no-changelog-github-release` flag is used to prevent creating a GitHub +> release with the changelog. This is required since it will fail to find the +> tags unless they've been pushed. + +```sh +cargo smart-release aya --execute --no-push --no-changelog-github-release +cargo smart-release aya-ebpf --execute --no-push --no-changelog-github-release +cargo smart-release aya-log-ebpf --execute --no-push --no-changelog-github-release +cargo smart-release aya-log --execute --no-push --no-changelog-github-release +``` + +> [!NOTE] +> cargo smart-release doesn't sign the commit with the `--signoff` flag. +> We recommend manually signing the commit(s) before pushing it. +> +> See: [this issue](https://github.com/Byron/cargo-smart-release/issues/31) +> tracking the feature request. + +### 2. Push the commits and tags + +This assumes you opted to disable branch protection: + +```sh +git push origin main +git push origin tag aya-vX.Y.Z +git push origin tag aya-ebpf-vX.Y.Z +# etc... +``` + +> [!WARNING] +> Remember to re-enable branch protection after pushing the commits/tags. + +Opening PRs for the changes made by the release would be a good enhancement +in future releases. However, we also need to create the tags via GitHub action +also - due to branch protection. + +### 3. Create a GitHub release + +Create a GitHub release for each crate with the changelog entries for the new +version. The changelog entries are in the `CHANGELOG.md` file in each crate's +root directory. + +The easiest way to do this is via the `gh` CLI: + +```sh +NOTES="$(awk -v v="X.Y.Z" ' + BEGIN {RS=""; FS="\n"} + $0 ~ "## " v { + print $0 + s=1 + next + } + s && /^## / { + exit + } + s { + print $0 + print "" + } +' aya/CHANGELOG.md)" +gh release create aya-vX.Y.Z --title "aya vX.Y.Z" --notes "$NOTES" +``` + +## Release Debugging + +Sometimes the release process can fail. +Here are some common issues and how to fix them: + +### `cargo smart-release` doesn't compute the correct version + +You can manually specify the version to release by passing the `--bump` flag +and specifying either `major`, `minor`, or `patch`. This *should* be computed +from the commits in the changelog, but sometimes it doesn't work as expected. + +### can't release aya-ebpf because of cyclic dependencies + +This is a known issue described in [#1050](https://github.com/aya-rs/aya/issues/1050). +The fix is to remove the `dev-dependencies` from `aya-ebpf-macros`, +re-run the failed `cargo publish` command from the output of +`cargo smart-release`.