Designing an SDK Release Train: Labels, Versions, Changelogs, and Approval Gates
Shipping the same feature across native and multi-platform SDKs is a coordination problem before it is a coding problem. A release train turns that coordination into a repeatable pipeline: every merged change carries a category, the next version is derived from those categories, a changelog is assembled, and a human approves before anything is published. This guide explains the moving parts and gives you a decision checklist for adopting the pattern.
Why a release train instead of ad-hoc releases
When a product supports several platforms and stores, a single feature can require changes in native iOS and Android code, a shared hybrid layer, and each multi-platform wrapper. If those steps are manual, the release becomes slow, hard to hand off, and difficult to predict. Support teams cannot tell developers when a fix will land, and bug fixes can take days or weeks to reach hybrid SDKs.
A release train addresses this by scheduling preparation and deployment, categorizing every change, and keeping a human approval gate. The goal is not to remove judgment; it is to make the routine parts deterministic so judgment is spent on the changes that matter.
Categorize changes with pull request labels
Commit-message conventions work for some projects, but they add friction for external contributors and are hard to enforce when a team uses squash-and-merge. A label on the pull request is easier to require and easier to inspect from automation. The label set below is the categorization vocabulary used by the release train; each label maps to a kind of change and, later, to a changelog section or version decision.
Require labels before merge
A label-driven train only works if every pull request is labeled. Run a check on CI during code review that inspects the pull request labels and posts a comment when one is missing. Keeping that check in a shared repository means every SDK repository can import the same rule instead of maintaining its own copy.
The check should be a warning or a failing status according to your team's policy. The important property is that an unlabeled pull request cannot silently enter the release calculation.
Determine the next version from labels
With labels in place, the next version can be computed without guessing. Start from the latest non-prerelease release, collect the commits on the main branch since that release, and read the labels of the associated pull requests through the GitHub API. Then apply semantic versioning:
- A breaking change makes the next release major.
- A non-breaking feature makes it minor.
- Anything else makes it a patch.
A worked example makes the rule concrete. From version 0.0.5, a breaking change produces 1.0.0, a feature produces 0.1.0, and a patch produces 0.0.6. If the computed release is major, the automation should stop rather than publish it, because major releases can break developers' code and need human handling.
Assemble changelogs by section
A changelog is only useful if a reader can tell a bug fix from a new feature. Use the same label data that drives versioning to place each change into a section. The release train described here uses four sections: breaking changes, new features, bug fixes, and other changes. Publish the result both in the GitHub release and in a CHANGELOG.md file in each repository so the information travels with the code.
Update the hybrid dependency on a schedule
Multi-platform SDKs often sit on top of a shared library that itself depends on the native SDKs. A scheduled job can open a pull request that bumps the shared library to the latest stable native releases. Skip major releases and prereleases in that automatic update; those need a person to decide. Merging the dependency pull request starts a new release of the shared library. Whether to hold the hybrid SDKs back for a full cycle is a policy choice: a deliberate stagger of one release cycle gives the native release time to surface important bugs before they reach the multi-platform SDKs, while a shorter gap ships fixes faster at the cost of that safety window. Decide the delay explicitly and document it so the schedule stays predictable.
Keep a human approval gate before deployment
Automation prepares the release pull request, but a person reviews it. Reviewers check the changes, adjust changelog wording when needed, and approve the job. A workable policy is to require that approval before the release branch is tagged, and to treat the tag as the trigger for publishing packages and creating the GitHub release. Keep the approval step mandatory even when the diff looks routine, and define who is allowed to approve so the gate does not become a formality.
Adoption checklist
- Define a label set that covers breaking, build, ci, docs, feat, fix, perf, refactor, style, test, and next_release changes. - Enforce labels on every pull request with a CI check. - Compute the next version from labels and semantic versioning. - Stop automation when the next version would be major. - Generate changelog sections from the same labels. - Schedule dependency updates separately from release preparation. - Require human approval before tagging and deploying. - Move shared scripts, checks, and CI jobs into reusable modules. - Confirm that automated releases rest on a test suite you trust; if coverage is thin, add tests before widening automation. - Track the time saved after adoption by comparing release cadence and manual effort before and after, rather than assuming a benefit.
| Label | Description |
|---|---|
| breaking | Changes that are breaking |
| build | Changes that affect the build system |
| ci | Changes to our CI configuration files and scripts |
| docs | Documentation-only changes |
| feat | A new feature |
| fix | A bug fix |
| perf | A code change that improves performance |
| refactor | A code change that neither fixes a bug nor adds a feature |
| style | Changes that don’t affect the meaning of the code (white-space, formatting, missing semicolons, etc.) |
| test | Adding missing tests or correcting existing tests |
| next_release | Preparing a new release |
The breaking label cannot be used alone; it must accompany another label.
Frequently asked questions
Why not categorize changes with commit messages?
Commit-message conventions such as the Angular format work well when every contributor follows them, but they add friction for external contributors and are hard to enforce when a team squashes and merges pull requests. Pull request labels are easier to require and easier for automation to read.
Should the release train publish major versions automatically?
No. Major releases can break developers' code, so the automation should detect a major version and skip the rest of the release steps. A person handles that release separately.
Why delay hybrid SDK releases by a week?
The delay is a deliberate stagger. A native release goes out first, and the hybrid SDKs pick it up in a later cycle. That window gives the team time to catch important bugs before they reach the multi-platform SDKs and widen the problem.
What triggers deployment after approval?
Approving the job tags the release branch with the version number. That tag is the trigger for the deployment process, which publishes packages and creates a GitHub release against the tag.