/release-takopi-matrix - Release Workflow

Release a new version of takopi-matrix to PyPI.

When to Use

• "Release version X.Y.Z"
• "Publish to PyPI"
• "Cut a release"

Repository Notes

• Branch protection: Main branch requires PRs (no direct push)
• Merge method: Rebase only (no merge commits, no squash)
• Tag workflow: Create tag AFTER PR merge to point to correct commit

Pre-flight Checks

Before releasing, verify:

# Run tests
uv run pytest

# Build package
uv build

# Verify version files match
grep "version" pyproject.toml
grep "__version__" src/takopi_matrix/__init__.py

Workflow

1. Generate Changelog

Get commits since the last release tag:

# Find last version tag
git describe --tags --abbrev=0

# Get commits since last tag (or all commits if first release)
git log $(git describe --tags --abbrev=0 2>/dev/null || echo --all)..HEAD --oneline

Create/update CHANGELOG.md with the new version entry:

# changelog

## vX.Y.Z (YYYY-MM-DD)

### changes
- Feature description

### fixes
- Bug fix description

### docs
- Documentation update

Changelog Format:

• Lowercase headers
• Date format: YYYY-MM-DD
• Categories: changes, fixes, docs, breaking
• Link to PRs/commits where helpful
• Newest versions at top

2. Version Bump

Update version in both files:

• pyproject.toml: version = "X.Y.Z"
• src/takopi_matrix/init.py: version = "X.Y.Z"

3. Create Commit & Release Branch

This repo has branch protection - cannot push directly to main.

# Stash any local changes first
git stash

# Create release branch
git checkout -b release/vX.Y.Z

# Commit version files
git add CHANGELOG.md pyproject.toml src/takopi_matrix/__init__.py uv.lock
git commit -m "Release vX.Y.Z"

# Push branch
git push -u origin release/vX.Y.Z

4. Create PR & Merge

# Create PR
gh pr create --title "Release vX.Y.Z" --body "Release vX.Y.Z"

# Merge with rebase (repo only allows rebase, not merge or squash)
gh pr merge --rebase --delete-branch

5. Tag the Release

Important: Create tag AFTER the PR is merged, on the correct commit.

# Sync local main with merged PR
git checkout main
git fetch origin
git reset --hard origin/main

# Create and push tag (now points to correct commit)
git tag vX.Y.Z
git push origin vX.Y.Z

6. Verify

• Check GitHub Actions: https://github.com/Zorro909/takopi-matrix/actions
• Check PyPI: https://pypi.org/project/takopi-matrix/

Example

User: /release-takopi-matrix 0.2.0

Claude: Preparing release v0.2.0...

Pre-flight checks:
✅ Tests: 193/193 passing
✅ Build: wheel + sdist created

📋 Commits since v0.1.1:
- abc1234 Add room-specific engine routing
- def5678 Fix Pydantic v2 config handling

📝 Generating changelog entry...
✅ CHANGELOG.md updated
✅ pyproject.toml: 0.1.1 → 0.2.0
✅ __init__.py: 0.1.1 → 0.2.0

Creating release branch and PR...
✅ Branch: release/v0.2.0
✅ PR #7 created: https://github.com/Zorro909/takopi-matrix/pull/7
✅ PR merged (rebase)

Tagging release...
✅ Tag v0.2.0 pushed

🚀 Release workflow triggered:
- Actions: https://github.com/Zorro909/takopi-matrix/actions
- PyPI: https://pypi.org/project/takopi-matrix/0.2.0/

Changelog Categories

Semantic Versioning

• MAJOR (1.0.0): Breaking API changes
• MINOR (0.2.0): New features, backwards compatible
• PATCH (0.1.1): Bug fixes, backwards compatible

Rollback

If something goes wrong:

# Delete remote tag
git push origin --delete vX.Y.Z

# Delete local tag
git tag -d vX.Y.Z

# Revert commit
git revert HEAD

PyPI packages cannot be re-uploaded with the same version. Bump to a new patch version if needed.