Problem

With Beads' rapid development pace, the changelog and release notes alone don't provide enough context for users (me!) to understand what's changed and why. Commits are fine-grained, and changelog entries are technical—but they miss the narrative that helps users understand impact and adoption path.

Solution

We've created a script that aggregates multiple sources to generate a narrative-style newsletter:

• Changelog sections for the release
• Git commit messages for granular context
• New commands extracted from code diffs
• Breaking changes parsed from changelog entries
• AI-powered narrative generation to explain what changed and why it matters

The newsletter script:

• Generates narrative prose (not bullet lists) explaining new features and breaking changes
• Helps users understand workflow impacts of major changes
• Provides a higher-level view of the development arc
• Can be run weekly, monthly, or for specific release ranges
• Supports Claude and OpenAI models

This fills the communication gap between technical changelog entries and user-friendly release notes.

Example Uses

# Last week
uv run scripts/generate-newsletter.py

# Specific release range
uv run scripts/generate-newsletter.py --from-release v0.39.0 --to-release v0.48.0

# Last 30 days
uv run scripts/generate-newsletter.py --days 30

See the included PR for the full implementation and usage guide.