feat: add AI-powered changelog generation

[nsaronson]

Summary

Adds AI-powered changelog generation with rich PR context for customer-focused release notes.

Fixes SUP-51

Features

• Smart changelog formatter that categorizes commits by type (features, fixes, refactoring)
• Full PR body fetching for rich context (not just commit titles)
• Claude Sonnet 4.5 integration to generate customer-focused summaries
• GitHub Actions workflow for testing changelog generation before releases
• Enhanced release script with interactive prompts

Testing

Tested locally with release 1.48.0 data:

• ✅ PR descriptions fetched correctly
• ✅ AI summarization generates customer-focused narratives
• ✅ Output format is clean and professional
• ✅ GitHub Actions workflow validated

Usage

After merge, use with:

./scripts/publish-release.sh

Or test via GitHub Actions:

• Go to Actions tab → "Generate Changelog Preview"
• Fill in from/to tags
• Download the generated changelog artifact

Requires ANTHROPIC_API_KEY secret (already configured).

[github-actions]

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

[nsaronson]

I have read the CLA Document and I hereby sign the CLA

[sandromello]

✅ Build Completed with Success, Version=1243.0.0-ba142d9

[sandromello]

✅ Build Completed with Success, Version=1243.0.0-2806f6c

[nsaronson]

PR #1243: AI-Powered Changelog Generation

📋 Overview

This PR adds an AI-powered changelog generator that transforms raw git commits into customer-friendly release notes using Claude Sonnet 4.5. It provides two workflows: an automated GitHub Actions preview and an enhanced manual release script.

---

🏗️ Architecture

The system has three main components:

1. format-changelog.sh (Core Engine)

The heart of the system. It:

• Categorizes commits by type (features, fixes, refactors, etc.)
• Fetches full PR descriptions from GitHub
• Calls Claude API to generate customer-focused summaries
• Supports multiple Claude models with automatic fallback

2. changelog-preview.yml (GitHub Actions Workflow)

Provides on-demand changelog previewing:

• Manually triggered workflow
• Generates changelog between any two tags
• Uploads result as a downloadable artifact

3. publish-release.sh (Enhanced Release Script)

The existing release script now:

• Prompts user for AI summarization options
• Calls format-changelog.sh with chosen flags
• Opens editor for final review before publishing

---

📊 Flow Charts

Flow 1: GitHub Actions Preview

┌─────────────────────────────────────────────┐
│   User triggers workflow from Actions tab   │
│   Inputs: from_tag, to_tag, use_ai, etc.    │
└─────────────────┬───────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────┐
│       Setup: Checkout code + Install gh     │
└─────────────────┬───────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────┐
│   Extract commits between tags using git    │
│   git log TAG1..TAG2 → /tmp/commits.txt     │
└─────────────────┬───────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────┐
│         Call format-changelog.sh            │
│     (passes --fetch-prs and --ai-summary)   │
└─────────────────┬───────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────┐
│  Upload changelog as downloadable artifact  │
└─────────────────────────────────────────────┘

Flow 2: Manual Release Process

┌──────────────────────────────────────────┐
│  User runs ./scripts/publish-release.sh  │
└──────────────┬───────────────────────────┘
               │
               ▼
┌──────────────────────────────────────────┐
│  Interactive prompts:                    │
│  • Which version to release?             │
│  • Fetch PR descriptions? (y/n)          │
│  • Use AI summarization? (y/n)           │
│  • Which Claude model? (optional)        │
└──────────────┬───────────────────────────┘
               │
               ▼
┌──────────────────────────────────────────┐
│   Extract commits since last release     │
│   git log LATEST_TAG..HEAD               │
└──────────────┬───────────────────────────┘
               │
               ▼
┌──────────────────────────────────────────┐
│       Call format-changelog.sh           │
│   with user-selected flags               │
└──────────────┬───────────────────────────┘
               │
               ▼
┌──────────────────────────────────────────┐
│  Open in editor for manual review/edits  │
└──────────────┬───────────────────────────┘
               │
               ▼
┌──────────────────────────────────────────┐
│  Append asset links (Docker, Helm, etc.) │
└──────────────┬───────────────────────────┘
               │
               ▼
┌──────────────────────────────────────────┐
│  Final confirmation → Create GH release  │
└──────────────────────────────────────────┘

Flow 3: The format-changelog.sh Logic

┌────────────────────────────────────┐
│   Read commits from input file     │
└─────────────┬──────────────────────┘
              │
              ▼
┌────────────────────────────────────────────┐
│  Parse & categorize each commit by prefix: │
│  • feat: → Features                        │
│  • fix: → Bug Fixes                        │
│  • refactor: → Refactoring                 │
│  • chore: → Maintenance                    │
└─────────────┬──────────────────────────────┘
              │
              ▼
┌────────────────────────────────────────────┐
│      If --fetch-prs flag enabled:          │
│  Extract PR numbers from commits           │
│  Call gh pr view #123 for each PR          │
│  Cache PR title + body in temp files       │
└─────────────┬──────────────────────────────┘
              │
              ▼
┌────────────────────────────────────────────┐
│     If --ai-summary flag enabled:          │
│  For each category (Features, etc):        │
│  1. Build prompt with commits + PR bodies  │
│  2. Call Claude API with fallback models   │
│  3. Get customer-focused summary           │
└─────────────┬──────────────────────────────┘
              │
              ▼
┌────────────────────────────────────────────┐
│  Output formatted markdown:                │
│  # Changelog                               │
│  ## 🎉 Features                            │
│  [AI summary or raw list]                  │
│  ## 🐛 Bug Fixes                           │
│  [Raw list - no AI for bugs]               │
│  ## ♻️ Refactoring, etc.                   │
└────────────────────────────────────────────┘

---

🔑 Key Design Decisions

1. Two-tier output: Summary paragraph + detailed bullet list (AI only for features)
2. PR context enrichment: Fetches full PR descriptions, not just commit titles
3. Model fallback chain: Tries multiple Claude models if one fails (from latest to oldest)
4. Caching: PR data cached locally to avoid redundant GitHub API calls
5. Selective AI: Only features get AI summarization; bugs/refactors stay as raw lists

---

💡 Example Transformation

Before (raw commit):

feat: add AccessMaxDuration field to connections (#1235)

After (AI-enhanced):

This release expands access control capabilities with time-based
restrictions and improved connection management...

- Added maximum session duration controls for connections to enforce
  automatic timeouts (#1235)

The AI reads the full PR body to understand why the field was added and what value it provides to customers.

---

📦 Files Changed

• .github/workflows/changelog-preview.yml (new): GitHub Actions workflow for preview generation
• scripts/format-changelog.sh (new): Core changelog formatting and AI integration engine
• scripts/publish-release.sh (modified): Enhanced with interactive AI options

---

🎯 Use Cases

Use Case 1: Preview Before Release

1. Go to GitHub Actions → "Generate Changelog Preview"
2. Enter version range (e.g., 1.47.2 to HEAD)
3. Enable AI summarization
4. Download artifact to review

Use Case 2: Create Release

1. Run ./scripts/publish-release.sh
2. Answer interactive prompts
3. Review AI-generated changelog in editor
4. Confirm to publish release to GitHub

---

🔐 Requirements

• ANTHROPIC_API_KEY: Required for AI summarization (stored as GitHub secret)
• GitHub CLI (gh): Required for fetching PR data
• Git tags: Proper version tagging for release ranges