docs: Add release documentation

This describes the current process for performing releases from the
aya workspace.

Signed-off-by: Dave Tucker <[email protected]>

RELEASE.md

@@ -0,0 +1,112 @@
+# 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