# SOP: Release Process

> Authoritative release SOP. Follow every step in order.
> AI agents MUST read this file before executing any release task.
>
> **Trigger**: When user says "release", "publish", "bump version", "tag", or "push to PyPI".

---

## Pre-Release Checklist

Before starting, confirm ALL of the following:

- [ ] All intended changes are committed to `main`
- [ ] Lint and tests pass
- [ ] Version is still at the OLD version (will be bumped in Step 1)

---

## Step 1 — Bump Version

Edit the version in your package manifest (e.g. `pyproject.toml`, `package.json`, etc.).

---

## Step 2 — Update status.md

Update `.agent/project/status.md`:
- `Current Phase`: reflect new release
- `Recently Completed`: add release entry

---

## Step 3 — Commit Everything

```bash
git add <changed files>
git commit -m "chore: bump version to vX.Y.Z"
```

---

## Step 4 — Push Branch

```bash
git push origin main
```

Verify push succeeded before proceeding to the tag step.

---

## Step 5 — Create and Push Tag

> **CRITICAL RULES:**
>
> 1. Use a consistent tag format for your project (e.g. `vX.Y.Z`).
>
> 2. The tag MUST point to HEAD **after** Step 4 is complete.
>    Always use explicit SHA, never rely on symbolic `HEAD`.
>
> 3. NEVER delete and re-push the same tag name.
>    CI will NOT re-trigger on a re-pushed tag.
>    If a tag needs fixing: bump to next patch version instead.
>
> 4. Push tag in a SEPARATE `git push` call from the branch push.

```bash
# PowerShell (Windows)
$SHA = git rev-parse HEAD
git tag -a "vX.Y.Z" "$SHA" -m "Release vX.Y.Z"
git push origin "vX.Y.Z"

# bash (Linux/macOS)
SHA=$(git rev-parse HEAD)
git tag -a "vX.Y.Z" "$SHA" -m "Release vX.Y.Z"
git push origin "vX.Y.Z"
```

---

## Step 6 — Verify CI Triggered

Check your CI provider within 2 minutes. A release workflow should appear.

**If CI does not appear within 2 minutes — DO NOT delete and re-push the tag.**
Instead, trigger the workflow manually via the CI web UI.

---

## Step 7 — Post-Release Verification

Verify the published artifact is accessible (PyPI, npm, Docker Hub, etc.).

---

## Known Pitfalls

| # | Pitfall | Rule |
|---|---------|------|
| 1 | Wrong tag format | Use consistent format, check CI trigger pattern |
| 2 | Delete and re-push same tag | Never — bump patch instead |
| 3 | Tag points to wrong commit | Use explicit SHA after `git push origin main` |
| 4 | Combined branch + tag push | Always separate `git push` calls |

---

*Customize this SOP with project-specific details (repo URLs, CI provider, package registry).*
