changelog-and-release-conventions.md

RFC: Changelog and Release Conventions

Status

Proposed

Goal

Adopt a release workflow that:

• generates a durable CHANGELOG.md
• produces GitHub Releases from structured change data
• creates richer release notes that can be reused for announcements, docs, and content
• improves merge quality by enforcing consistent commit and pull request titles

Why now

Today this repository has deploy workflows, but no first-class changelog or release-note system. That limits reuse of shipped work for:

• product updates
• customer-facing release notes
• internal sharing
• social and content distribution

The missing primitive is structured change metadata. Once commits and PR titles follow a shared convention, the repository can automate changelog generation and release publishing instead of relying on manual summarization.

Principles

• Deterministic release metadata comes first.
• AI-authored narrative comes second.
• Start with a repo-level changelog before splitting into package-level changelogs.
• Do not couple changelog rollout to a deploy-process rewrite in the first phase.
• Enforce the convention in CI, not only through local tooling.

Proposed rollout

Phase 1: Conventional commits baseline

Introduce Conventional Commits as the required format for mergeable work.

This phase includes:

• commitlint for commit message validation
• PR title linting so squash merges remain compatible with release tooling
• a local Husky commit-msg hook for fast feedback

Allowed types:

• feat: user-facing feature
• fix: bug fix
• perf: measurable performance improvement
• refactor: structural change without behavior change
• docs: documentation only
• test: test-only changes
• build: build tooling or dependencies
• ci: CI or workflow changes
• style: formatting-only change
• chore: maintenance work that does not fit the above
• revert: revert a previous change

Examples:

• feat(api): add session replay export endpoint
• fix(web): prevent duplicate release dialog submissions
• chore(ci): lint pull request titles
• refactor(managed-browser)!: remove legacy release handshake

Breaking changes should use ! in the header and include a body or footer that explains the impact.

Phase 2: Repo-level changelog automation

Add release-please to steel-main and start with one root-level CHANGELOG.md.

Expected behavior:

• create release PRs from merged conventional commits
• update the root changelog automatically
• publish GitHub Releases
• keep deploy workflows unchanged during the pilot

This is the lowest-risk rollout because the repository already has a production deploy model driven by branch conventions. Release automation should be introduced without changing deploy triggers in the first pass.

Phase 3: Narrative release notes with Claude

Once release automation is stable, add a GitHub Action using Claude to enrich release notes.

Claude should:

• consume the structured output from release-please
• produce a more readable release summary
• call out operator impact, upgrade notes, and migrations
• generate content-ready summaries for changelog posts or social distribution

Claude should not:

• decide semantic versions
• decide release boundaries
• replace the deterministic release generator

Phase 4: Org-wide standardization

After the steel-main pilot works, extract the pattern into a shared standard for other repositories:

• shared commitlint config
• shared release-please template
• shared release-note prompt or reusable Claude workflow

Recommendation for steel-main

Implement in this order:

1. enforce conventional commits and PR titles
2. pilot repo-level release-please
3. observe one or two release cycles
4. add Claude-generated narrative release notes
5. consider deploy-trigger alignment later

Non-goals for the first pass

• per-package changelogs
• semver policy for each workspace
• migration from branch-triggered deploys to tag-triggered deploys
• AI-owned versioning logic

Success criteria

• every release updates CHANGELOG.md automatically
• pull requests fail fast when titles or commits do not match the convention
• release notes are usable for external sharing with minimal manual editing
• the current deploy process continues to work during the pilot

This branch

This branch implements only Phase 1:

• commitlint config
• local commit-msg hook
• GitHub Action for commit linting
• GitHub Action for semantic PR title linting