From acb1ddd2ecdc0c80d5255c452b02427fd94af377 Mon Sep 17 00:00:00 2001
From: Dave Tucker <dave@dtucker.co.uk>
Date: Wed, 9 Oct 2024 13:41:39 +0100
Subject: [PATCH] docs: Add release documentation

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

Signed-off-by: Dave Tucker <dave@dtucker.co.uk>
---
 RELEASE.md | 72 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 72 insertions(+)
 create mode 100644 RELEASE.md

diff --git a/RELEASE.md b/RELEASE.md
new file mode 100644
index 00000000..5e3b176c
--- /dev/null
+++ b/RELEASE.md
@@ -0,0 +1,72 @@
+# Releasing the aya project
+
+This document describes the process of releasing the aya project.
+
+## Release process
+
+### 0. Who can release?
+
+Only members of [aya-rs/owners][owners-team] have the permissions to:
+
+- Push packages to crates.io
+- Make the necessary changes in GitHub to create a release
+
+### 1. Create a release branch and run cargo smart-release
+
+This project uses [cargo-smart-release] to automate the release process. Start
+from the default branch, create a fresh release branch, and run the command
+below on that branch. As soon as the command succeeds it will publish each crate
+and push the branch plus tags to the remote automatically, so double-check that
+everything is ready before invoking
+it.
+
+> [!IMPORTANT]
+> The `--execute` flag is used to actually perform the release.
+> Remove it to do a dry-run first.
+
+```sh
+git checkout -b my-release-branch
+cargo smart-release \
+  aya \
+  aya-ebpf \
+  aya-log-ebpf \
+  aya-log \
+  --execute \
+  --signoff
+```
+
+### 2. Open a pull request
+
+Because the release branch gets pushed automatically on success, open a PR
+against the default branch and merge it once everything looks good. This keeps
+git history auditable even though crates.io already has the freshly published
+artifacts.
+
+> [!IMPORTANT]
+> Use a fast-forward merge to ensure the tags are reachable from the default
+> branch.
+
+## 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.
+
+### 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] is an example of such a commit.
+
+[cargo-smart-release]: https://github.com/Byron/cargo-smart-release
+[owners-team]: https://github.com/orgs/aya-rs/teams/owners
+[c3f0c7dc]: https://github.com/aya-rs/aya/commit/c3f0c7dc3fb285da091454426eeda0723389f0f1