# 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