Inside the Machine: Six Weeks of Release Engineering Behind Asterix v3.0
Major version bumps are where open-source projects reveal their true character. Anyone can merge pull requests; shipping a breaking release with thousands of downstream users watching is a different discipline entirely.
When we cut Asterix v3.0 earlier this year, we documented every step of the process in the open — the debates, the rollbacks, and the 2 a.m. hotfix. This is that record, organized so your team can lift the useful parts.
Phase One: The RFC That Took Five Weeks
Every breaking change in Asterix starts as a Request for Comments in our /rfcs directory. For v3.0, RFC-041 — the proposal to replace our plugin ABI with a capability-based manifest — generated 340 comments over five weeks.
The lesson we keep relearning: the loudest objections usually surface in week three, not week one. We now enforce a minimum seven-day comment window after the last substantive reply before an RFC can reach "accepted" status. Tools we use:
- GitHub Discussions with a dedicated RFC category, so the signal stays out of the issue tracker
- A decision log maintained in the repo, recording not just what we decided but which alternatives we rejected and why
- A deprecation policy (two minor versions of warnings before removal) that RFC authors must cite explicitly
Phase Two: The Breaking-Change Triage Board
Once the RFC was accepted, we moved every v3.0 item onto a GitHub Project board with four columns: proposed, accepted, landed, and blocker. Anything tagged blocker prevented the release branch from being cut, no exceptions.
The discipline matters more than the tooling. In previous cycles, "we'll slip it into the next major" quietly became the escape hatch for scope creep. This time, we froze the blocker list six weeks before target and treated additions to it as a formal decision requiring two maintainer sign-offs.
Phase Three: Release Candidates in the Wild
We cut v3.0.0-rc.1 on a Tuesday and asked our most demanding integrators — including two US-based fintech teams who run Asterix in production at scale — to test against their real workloads under NDA-free agreements.
RC testing surfaced two issues our CI couldn't catch: a race condition that only appeared under sustained load on AWS m6i instances, and a documentation gap that left Windows users without a working migration path. Both were fixed by rc.3.
Our RC checklist, condensed:
- Full changelog drafted from commit history, then manually verified against every merged PR
- Migration guide published before the RC, not after
- Benchmark suite run against the previous stable version, with results posted publicly
- Signed artifacts produced via Sigstore and verified in a clean environment
Launch Day and the Hotfix Nobody Mentions
We tagged v3.0.0 on a Wednesday morning Eastern Time — deliberately, so US-based maintainers were awake and European contributors were still online. Within nine hours, a user in Ohio filed an issue about a regression in the config parser affecting anyone upgrading from v2.7 or earlier.
Because our release branch workflow (release/v3.0) was already in place, we cut v3.0.1 in under four hours: patch, CI, sign, publish, announce. The postmortem was written the same day and lives in the repo today.
What You Should Borrow
Three practices transfer to projects of any size. First, publish your migration guide with the release candidate, not the final — it will get more real-world review than any internal pass. Second, keep a decision log; six months from now, nobody will remember why you rejected the obvious alternative. Third, treat your release branch as a contract: if it isn't on the blocker list, it ships in the next minor.
Open source gives you an audience that will find every flaw in your process. That's not a burden — it's the best QA team you'll ever have.
