Proposal: Improve Alloy release process

[jharvey10]

Background

Over the past several release cycles, Alloy has consistently missed planned release dates—often by a couple weeks. The release workflow is 40+ steps across 9 files and represents a heavily manual, error-prone process. Core tasks such as versioning, tagging, and changelog creation required manual intervention, and the process does not align well with industry best practices. As Alloy’s adoption has grown, this unpredictability and operational overhead has become increasingly costly.

Key pain points

• Release drift (actual vs expected release dates)
• Lengthy, manual release process
• Constant CHANGELOG.md conflicts
• Changelog data duplicates PR and commit data
• Many RCs often need to be cut per release due to late content adds or process hiccups

Proposal

1. Automate Versioning & Changelog Generation

• Adopt release-please and conventional commits to automatically manage semantic versioning, generate release PRs, and update CHANGELOG.md.
• Use a lightweight wrapper (release-please-runner) to apply Alloy-specific logic while keeping the workflow fully CI-driven.
• Eliminate manual changelog editing and version bumping.

2. Standardize and Automate the Release Pipeline

Introduce GitHub Actions workflows backed by small, purpose-built Go tools to create a predictable, reproducible release process:

• Create Release Branch
  Tool: create-release-branch — automates creation and validation of release branches.

• Create Release Candidate
  Tool: create-rc — automates tagging RCs and generating draft GitHub Releases.

• Publish Release Artifacts
  Structured CI workflow ensures consistent generation and publication of all release assets.

• Forward-Port to main
  Tool: forwardport-release-to-main — ensures version bumps and changelog updates are synced back into main.

• Automated Backports
  Tool: backport — reliably creates backport branches and PRs by automatically cherry-picking changes to the appropriate release branch.

3. Process changes

• Reduce manual steps from 40+ to 5 or less.
• Explore releasing twice as often, while keeping the OTel update commitment the same time-wise (e.g. "tick" "tock" release cadence).
• Avoid manual cherr-picking at all costs.
• Avoid touching CHANGELOG.md at all costs.
• Institute a code freeze prior to cutting minor release branches.
  • Ensure that only critical fixes are added between cutoff and stable releas.

The combination of all of these tools and practices will modernize the Alloy release process, alleviate cognitive load from maintainers, increase consistency from release to release, and increase our team velocity.

Tip

_{React with 👍 if this issue is important to you.}