-
Notifications
You must be signed in to change notification settings - Fork 298
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
This describes the current process for performing releases from the aya workspace. Signed-off-by: Dave Tucker <[email protected]>
- Loading branch information
1 parent
0e70838
commit 0d7873c
Showing
1 changed file
with
120 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,120 @@ | ||
| # 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`. | ||
|
|
||
| ### WOULD stop release after commit as the changelog entry is empty for crate | ||
|
|
||
| If you see the message ☝ in the output of `cargo smart-release`, it means that | ||
| the generated changelog entry for the crate is empty. This can happen if, for | ||
| example, the only change is a dependency update. In this case, you can manually | ||
| edit the changelog entry in the crate's `CHANGELOG.md` file to include a note | ||
| about the dependency update under the `## Unreleased` section. | ||
| Here is an [example](https://github.com/aya-rs/aya/commit/c3f0c7dc3fb285da091454426eeda0723389f0f1) | ||
| of such a commit. |