Blog
SDK Changelogs That Warn Before the Breaking Change
Developers search the error the new version printed, not your changelog title. Put the error code in the release note, and print the note's URL from the CLI when the break happens.
2026-08-20 · 6 min read · AethelLayer
The error is the entry point
Nobody reads a changelog on a Friday until a command fails. The stderr line should include the version and a stable URL for that break. The changelog entry should use the same error code as the H2.
A major version with only 'various fixes' produces support tickets that are really unread notes.
Deprecate in a minor, remove in a major
Print a warning for one minor cycle with the replacement command. Remove the old path in the next major, and keep the error that names the replacement. Do not delete a flag in a patch.
Pin the quickstart to a version while the break is rolling out. 'Latest' is how Thursday's docs fail on Friday.
Watch the version on the probe
A spike of one code on one version is a release, not a trend. The inbox should show the version next to the code so you do not 'fix' a bug that only exists on a yanked build.
If the sentences say 'I followed the README', the README is still on the old snippet. Change it the same day.
One issue per break
Group drafts by code and version. Send one GitHub issue, link the changelog, and close the duplicates. Evaluators do not need ten notifications for one renamed flag.
Keep reading
Capture the failure before they leave
Capture the failure before they leave. Book early access or talk to sales, then install @aethellayer/sdk when you are onboarded.