archon/.github/RELEASE_NOTES_SETUP.md

AI-Generated Release Notes Setup

This repository uses Claude AI to automatically generate comprehensive release notes when you create a new release.

How It Works

The workflow triggers when:

• You push a new tag (e.g., v1.0.0)
• You create a GitHub release
• You manually trigger it via workflow dispatch

Claude AI analyzes:

• Commit messages since the last release
• Merged pull requests
• File changes by component (frontend, backend, docs)
• Contributors

Then generates structured release notes with:

• Overview and key changes
• Feature additions, improvements, and bug fixes
• Technical changes by component
• Statistics and contributor acknowledgments
• Breaking changes (important for beta!)

Testing Locally First (Recommended!)

Before setting up the GitHub Action, you can test the release notes generation locally:

Prerequisites

# Install required tools (if not already installed)
sudo apt install jq curl  # Linux
# or
brew install jq curl      # macOS

# Install GitHub CLI (optional, for PR detection)
# See: https://github.com/cli/cli#installation

Run Local Test

# 1. Export your Anthropic API key
export ANTHROPIC_API_KEY="sk-ant-api03-..."

# 2. Run the test script

# Compare origin/stable vs main branches (default - shows unreleased changes)
./.github/test-release-notes.sh

# Or specify branches explicitly (automatically handles remote branches)
./.github/test-release-notes.sh stable main        # Will use origin/stable if no local stable
./.github/test-release-notes.sh origin/stable main # Explicit remote branch

# Or use range syntax
./.github/test-release-notes.sh stable..main

# Or compare tags for a release
./.github/test-release-notes.sh v1.0.0 v2.0.0

# Or test a single tag (compares with previous tag)
./.github/test-release-notes.sh v0.1.0

What the Local Test Does

1. Gathers git data: Commits, file changes, and PRs (if gh CLI available)
2. Calls Claude API: Generates release notes using the same prompt as the workflow
3. Saves output: Creates release-notes-<tag>.md in current directory
4. Shows preview: Displays the generated notes in your terminal

Example Output

$ ./.github/test-release-notes.sh v0.2.0

🤖 Local Release Notes Generator Test
==========================================

Current tag: v0.2.0
Previous tag: v0.1.0

📝 Gathering commits...
Found 42 commits

📊 Analyzing file changes...
Files summary: 28 files changed, 1547 insertions(+), 423 deletions(-)

🔀 Looking for merged PRs...
Found 8 merged PRs

🤖 Generating release notes with Claude...
✅ Release notes generated successfully!

📄 Output saved to: release-notes-v0.2.0.md

==========================================
Preview:
==========================================
[Generated release notes appear here]
==========================================
✅ Done!

Testing Different Scenarios

# 🔥 MOST COMMON: See what's new in main vs stable (unreleased changes)
./.github/test-release-notes.sh
# Output: release-notes-origin-stable..main.md

# Or with explicit arguments
./.github/test-release-notes.sh stable main
# Output: release-notes-origin-stable..main.md (auto-resolves to origin/stable)

# Test your first release (compares with initial commit)
./.github/test-release-notes.sh v0.1.0

# Test a release between two specific tags
./.github/test-release-notes.sh v1.0.0 v2.0.0

# Test what would be in next release (current branch vs stable)
git checkout main
./.github/test-release-notes.sh stable main

Typical Workflow: Stable vs Main

For projects with separate stable (production) and main (development) branches:

# 1. See what's ready to release (compare branches)
export ANTHROPIC_API_KEY="sk-ant-..."
./.github/test-release-notes.sh stable main
# Or explicitly use remote branch: ./.github/test-release-notes.sh origin/stable main

# 2. Review the generated notes
cat release-notes-origin-stable..main.md

# 3. When ready to release, fetch latest and merge main to stable
git fetch origin
git checkout -b stable origin/stable  # Create local tracking branch if needed
git merge main
git push origin stable

# 4. Create a release tag
git tag v1.0.0
git push origin v1.0.0

# 5. The GitHub Action will automatically generate release notes
# (You can also manually create the release with the generated notes)
gh release create v1.0.0 --title "Release v1.0.0" --notes-file release-notes-origin-stable..main.md

Setup Instructions

1. Get Claude Code OAuth Token

The GitHub Action uses Claude Code OAuth token (same as the claude-review workflow):

1. Go to Claude Code OAuth Setup
2. Follow the instructions to get your OAuth token
3. Copy the token

2. Add GitHub Secret

1. Go to your repository's Settings
2. Navigate to Secrets and variables → Actions
3. Click New repository secret
4. Name: CLAUDE_CODE_OAUTH_TOKEN
5. Value: Paste your Claude Code OAuth token
6. Click Add secret

Note: If you already have CLAUDE_CODE_OAUTH_TOKEN set up for claude-review workflow, you're all set! The same token is used for both workflows.

3. (Optional) Get Anthropic API Key for Local Testing

For local testing, you'll need an API key:

1. Go to Anthropic Console
2. Create a new API key
3. Copy the key (starts with sk-ant-...)
4. Export it: export ANTHROPIC_API_KEY="sk-ant-..."

Note: The GitHub Action uses OAuth token, but local testing uses API key for simplicity.

4. Test the Workflow

Option A: Create a Release via GitHub UI

1. Go to Releases in your repository
2. Click Draft a new release
3. Choose or create a tag (e.g., v0.1.0)
4. Click Publish release
5. The workflow will automatically run and update the release notes

Option B: Push a Tag via Git

# Create and push a new tag
git tag v0.1.0
git push origin v0.1.0

# The workflow will automatically create a release with AI-generated notes

Option C: Manual Trigger

1. Go to Actions tab
2. Select "AI-Generated Release Notes" workflow
3. Click Run workflow
4. Enter the tag name (e.g., v0.1.0)
5. Click Run workflow

Usage Examples

Creating Your First Release

# Tag your current state
git tag v0.1.0-beta

# Push the tag
git push origin v0.1.0-beta

# Check Actions tab - release notes will be generated automatically

Creating Subsequent Releases

# Make your changes and commits
git add .
git commit -m "feat: Add AI-powered search feature"
git push

# When ready to release
git tag v0.2.0-beta
git push origin v0.2.0-beta

# Release notes will compare v0.2.0-beta with v0.1.0-beta

What Gets Generated

The AI generates release notes in this structure:

# 🚀 Release v0.2.0

## 📝 Overview
[Summary of the release]

## ✨ What's New

### Major Features
- [New features]

### Improvements
- [Enhancements]

### Bug Fixes
- [Fixes]

## 🔧 Technical Changes

### Backend (Python/FastAPI)
- [Backend changes]

### Frontend (React/TypeScript)
- [Frontend changes]

### Infrastructure
- [Infrastructure updates]

## 📊 Statistics
- Commits: X
- Pull Requests: Y
- Files Changed: Z
- Contributors: N

## 🙏 Contributors
[List of contributors]

## ⚠️ Breaking Changes
[Any breaking changes]

## 🔗 Links
- Full Changelog: [link]

Customization

Modify the Prompt

Edit .github/workflows/release-notes.yml and change the prompt in the "Generate release notes with Claude" step to adjust:

• Tone and style
• Structure
• Focus areas
• Level of detail

Change Claude Model

In the workflow file, you can change the model:

"model": "claude-sonnet-4-20250514"  # Latest Sonnet
# or
"model": "claude-3-7-sonnet-20250219"  # Sonnet 3.7
# or
"model": "claude-opus-4-20250514"  # Opus 4 (more detailed)

Adjust Token Limit

Increase max_tokens for longer release notes:

"max_tokens": 4096  # Default
# or
"max_tokens": 8192  # For more detailed notes

Troubleshooting

Workflow Fails with "ANTHROPIC_API_KEY not found"

• Ensure you've added the secret in repository settings
• Secret name must be exactly ANTHROPIC_API_KEY
• Secret must be a valid Anthropic API key

Empty or Incomplete Release Notes

• Check if commits exist between tags
• Verify git history is complete (workflow uses fetch-depth: 0)
• Check Actions logs for API errors

API Rate Limits

• Anthropic has generous rate limits for API keys
• For very frequent releases, consider caching or batching

Authentication: GitHub Action vs Local Testing

GitHub Action (Claude Code OAuth)

• Uses CLAUDE_CODE_OAUTH_TOKEN secret
• Same authentication as claude-review workflow
• Integrated with GitHub through Claude Code Action
• No direct API costs (usage included with Claude Code)

Local Testing (API Key)

• Uses ANTHROPIC_API_KEY environment variable
• Direct API calls to Claude
• Simpler for local testing and debugging
• Cost: ~$0.003 per release (less than a penny)

Why Two Methods?

• GitHub Action: Uses Claude Code Action for better GitHub integration and consistency with other workflows
• Local Testing: Uses direct API for simplicity and faster iteration during development

Cost Estimation

Local Testing (API Key)

Claude API pricing (as of 2025):

• Sonnet 4: ~$0.003 per release (assuming ~4K tokens)
• Each release generation costs less than a penny
• For a project with monthly releases: ~$0.036/year

GitHub Action (OAuth Token)

• No additional costs beyond your Claude Code subscription
• Usage included in Claude Code plan

Best Practices

Write Good Commit Messages

The AI works better with clear commits:

# ✅ Good
git commit -m "feat: Add vector search with pgvector"
git commit -m "fix: Resolve race condition in crawling service"
git commit -m "docs: Update API documentation"

# ❌ Less helpful
git commit -m "updates"
git commit -m "fix stuff"
git commit -m "wip"

Use Conventional Commits

The workflow benefits from conventional commit format:

• feat: - New features
• fix: - Bug fixes
• docs: - Documentation
• refactor: - Code refactoring
• test: - Tests
• chore: - Maintenance

Tag Semantically

Use semantic versioning:

• v1.0.0 - Major release
• v1.1.0 - Minor release (new features)
• v1.1.1 - Patch release (bug fixes)
• v0.1.0-beta - Beta releases

Manual Editing

You can always edit the generated release notes:

1. Go to the release page
2. Click Edit release
3. Modify the notes as needed
4. Click Update release

Workflow Outputs

The workflow provides:

• Updated GitHub release with AI-generated notes
• Artifact with release notes (kept for 90 days)
• Comments on related PRs linking to the release
• Summary in Actions tab

Advanced: Using with Pre-releases

# Create a pre-release
git tag v0.2.0-rc.1
git push origin v0.2.0-rc.1

# Mark as pre-release in GitHub UI or via gh CLI
gh release create v0.2.0-rc.1 --prerelease

Integration with Other Tools

Notify Slack/Discord

Add a notification step after release creation:

- name: Notify team
  run: |
    curl -X POST YOUR_WEBHOOK_URL \
      -H 'Content-Type: application/json' \
      -d '{"text":"Release ${{ steps.get_tag.outputs.tag }} published!"}'

Update Changelog File

Append to CHANGELOG.md:

- name: Update changelog
  run: |
    cat release_notes.md >> CHANGELOG.md
    git add CHANGELOG.md
    git commit -m "docs: Update changelog for ${{ steps.get_tag.outputs.tag }}"
    git push

Support

If you encounter issues:

1. Check the workflow logs in Actions tab
2. Verify your API key is valid
3. Ensure git history is available
4. Open an issue with workflow logs attached