Drift Release

---
name: drift-release
description: "Complete release workflow: Validate → Version → Changelog → Commit → Tag → Publish. Use after successful code changes to src/drift/. Single command: `python scripts/release_automation.py --full-release`"
---

# Drift Release Skill (python-semantic-release)

Releases are **fully automated** via `python-semantic-release` (PSR) in CI.

## Executive Summary

**Agents no longer need to run a manual release command.**

Workflow: `.github/workflows/release.yml` runs on every push to `main`.
PSR parses conventional commits and handles version bump, changelog, tag, GitHub Release, and PyPI publish.

---

## When to Use This Skill

✅ **Know this after:**
- Feature complete (`feat: ...` commit)
- Bug fixed (`fix: ...` commit)
- Breaking change (`BREAKING: ...` commit)
- All tests pass
- Code committed + pushed to main

The CI release workflow handles everything else automatically.

---

## What Agents Must Do

### Step 1: Use Conventional Commits

```
feat: add new detector for X       →  MINOR bump (0.X.0)
fix: false alarm in signal Y       →  PATCH bump (0.0.X)
BREAKING: remove deprecated API    →  MAJOR bump (X.0.0)
```

### Step 2: Run Tests Locally

```bash
make test-fast
```

### Step 3: Commit and Push

PSR in CI handles the rest after push to main.

---

## What PSR Does Automatically (in CI)

1. **Commits analyzed** — from last tag to HEAD
2. **Version calculated** — based on commit types (feat → minor, fix → patch, BREAKING → major)
3. **Files updated:**
   - `pyproject.toml` (version field)
   - `CHANGELOG.md` (new entry)
4. **Release commit created** — `chore: Release X.Y.Z`
5. **Git tag created** — `vX.Y.Z`
6. **GitHub Release created**
7. **Built and published to PyPI**

---

## Troubleshooting

| Problem | Solution |
|---------|----------|
| No release after push | Check commit messages use conventional prefixes (feat:, fix:, BREAKING:). Commits without these don't trigger releases. |
| Tests fail during release | Fix code first. PSR only runs when there are releasable commits. |
| Version looks wrong | Verify recent commit messages. PSR Priority: BREAKING > feat > fix. |
| PyPI publish fails | GitHub Release exists. Re-trigger with `publish.yml` workflow_dispatch. |
| CI unavailable | Local fallback: `python scripts/release_automation.py --full-release` |

---

## Important Details

- 🔐 **PyPI token:** `PYPI_RELEASE` secret in GitHub environment `pypi`
- 📊 **CHANGELOG:** Auto-generated by PSR from commit history
- 🏷️ **Tag format:** `vX.Y.Z` (e.g., v1.4.2)
- ⚙️ **Workflow:** `.github/workflows/release.yml`
- 📝 **Config:** `pyproject.toml` → `[tool.semantic_release]`
- 🔄 **Major tag:** `v1` auto-updated to latest patch (e.g., v1 → v1.4.3)

## DO NOT DO THIS

❌ Forget to release after code changes
❌ Skip tests to "speed up" the release
❌ Manually create git tags/commits for releases
❌ Edit version numbers outside of `pyproject.toml`
❌ Push without running the full release workflow

---

## Quick Reference

```bash
# Full release (recommended)
python scripts/release_automation.py --full-release

# Just calculate version
python scripts/release_automation.py --calc-version

# Just update changelog
python scripts/release_automation.py --update-changelog

# Skip tests (NOT recommended)
python scripts/release_automation.py --full-release --skip-tests
```

---

## Need Full Details?

Reference documentation: `.github/instructions/drift-release-automation.instructions.md`

For questions about releases → Check that file first.