From eece69f78ae4116c1799b8cd89625a24b52f8d9b Mon Sep 17 00:00:00 2001
From: osw282 <25309418+osw282@users.noreply.github.com>
Date: Thu, 12 Mar 2026 13:15:12 +0000
Subject: [PATCH 1/2] Release doc first draft

---
 RELEASE.md | 87 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 87 insertions(+)
 create mode 100644 RELEASE.md

diff --git a/RELEASE.md b/RELEASE.md
new file mode 100644
index 0000000..259a1cc
--- /dev/null
+++ b/RELEASE.md
@@ -0,0 +1,87 @@
+# Release Guide
+
+This document describes the process for creating a new release of `sre-agent`.
+
+## Prerequisites
+
+- You have push access to the repository.
+- All features and fixes intended for the release have been merged into `main`.
+- CI is passing on `main`.
+
+## Steps
+
+### 1. Create a release branch
+
+Branch off `main` using the `release/` prefix:
+
+```bash
+git checkout main
+git pull origin main
+git checkout -b release/vX.Y.Z
+```
+
+### 2. Bump the version
+
+Update the version in `pyproject.toml`:
+
+```toml
+version = "X.Y.Z"
+```
+
+Commit the version bump:
+
+```bash
+git add pyproject.toml
+git commit -m "Bump version to vX.Y.Z"
+```
+
+### 3. Open a pull request
+
+Push the release branch and open a PR against `main`:
+
+```bash
+git push -u origin release/vX.Y.Z
+```
+
+Ensure CI passes and get the required approvals.
+
+### 4. Merge and tag
+
+Once the PR is approved and merged, tag the release from `main`:
+
+```bash
+git checkout main
+git pull origin main
+git tag vX.Y.Z
+git push origin vX.Y.Z
+```
+
+### 5. Create a GitHub release
+
+Create a release on GitHub from the new tag:
+
+```bash
+gh release create vX.Y.Z --generate-notes --title "vX.Y.Z"
+```
+
+Review and edit the auto-generated notes as needed.
+
+## Versioning
+
+This project follows [Semantic Versioning](https://semver.org/):
+
+- **MAJOR** — incompatible API or behaviour changes
+- **MINOR** — new functionality, backwards-compatible
+- **PATCH** — backwards-compatible bug fixes
+
+## Hotfixes
+
+For urgent fixes against a release that is already published:
+
+```bash
+git checkout main
+git pull origin main
+git checkout -b hotfix/vX.Y.Z
+```
+
+Follow the same process: bump version, open a PR, merge, tag, and create a GitHub release.

From 9c77ec75e78b25f2fac9e6d1ebd549983a79b189 Mon Sep 17 00:00:00 2001
From: osw282 <25309418+osw282@users.noreply.github.com>
Date: Thu, 12 Mar 2026 13:23:53 +0000
Subject: [PATCH 2/2] Release workflow and release.md

---
 .github/workflows/publish.yml | 34 ++++++++++++++++++++++++++++++++++
 RELEASE.md                    | 13 +++++++++++--
 2 files changed, 45 insertions(+), 2 deletions(-)
 create mode 100644 .github/workflows/publish.yml

diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
new file mode 100644
index 0000000..017e28e
--- /dev/null
+++ b/.github/workflows/publish.yml
@@ -0,0 +1,34 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version-file: "pyproject.toml"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "0.10.9"
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        run: uv publish --trusted-publishing always
diff --git a/RELEASE.md b/RELEASE.md
index 259a1cc..0a25a86 100644
--- a/RELEASE.md
+++ b/RELEASE.md
@@ -47,7 +47,7 @@ Ensure CI passes and get the required approvals.
 
 ### 4. Merge and tag
 
-Once the PR is approved and merged, tag the release from `main`:
+Once the PR is approved, merge it into `main` via GitHub. Then tag the merge commit locally:
 
 ```bash
 git checkout main
@@ -56,7 +56,16 @@ git tag vX.Y.Z
 git push origin vX.Y.Z
 ```
 
-### 5. Create a GitHub release
+### 5. Publish to PyPI
+
+Publishing happens automatically via GitHub Actions when a `v*` tag is pushed
+(see `.github/workflows/publish.yml`). The workflow uses
+[Trusted Publishers](https://docs.pypi.org/trusted-publishers/) so no API tokens
+need to be stored as secrets.
+
+Verify the release is live at https://pypi.org/project/sre-agent/.
+
+### 6. Create a GitHub release
 
 Create a release on GitHub from the new tag: