# 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-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 --signoff --no-changelog-github-release cargo smart-release aya-ebpf --execute --signoff--no-changelog-github-release cargo smart-release aya-log-ebpf --execute --signoff --no-changelog-github-release cargo smart-release aya-log --execute --signoff--no-changelog-github-release ``` [cargo-smart-release]: https://github.com/Byron/cargo-smart-release ### 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][#150]. 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`. [#150]: https://github.com/aya-rs/aya/issues/1050 ### 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. [c3f0c7dc][c3f0c7dc] is an example of such a commit. [c3f0c7dc]: https://github.com/aya-rs/aya/commit/c3f0c7dc3fb285da091454426eeda0723389f0f1