Marking stability levels
Issues and pull requests are labeled with the Stability level they target, and features that aren't GA carry a stability mark where people use them. That way reviewers, teammates, clients, and users all know how stable something is at a glance. Stability levels explains what each level means, and Stability levels in practice covers using them with clients.
Label issues and pull requests
Every Exalynt repository has the same four labels:
| Level | Label | Color |
|---|---|---|
| Prototype | stability: prototype | #6d6a7c |
| Alpha | stability: alpha | #9c4f6c |
| Beta | stability: beta | #3f6f88 |
| GA | stability: ga | #4c7a58 |
- One stability label on each issue and pull request, except bugs.
- Label the level the work is aiming for, not where the code is today. A pull request that takes a feature from Alpha to Beta is labeled Beta.
- Change the label when the plan changes. If a prototype goes well and you take it straight on to Alpha, update the label. Labels are cheap; keep them accurate.
- Bugs don't get a stability label. Bugs aren't related to stability levels: a fix restores how something should already work rather than moving it to a level.
- Mention moves in the description, e.g. "Moves invoice export to Beta." That's all a move needs.
The label also tells reviewers how much to ask for. The Stability checklist has what each level generally includes.
Breaking changes after GA
Once something is GA, breaking changes go through versioning. In practice:
- APIs get a new version (e.g.
/v2) next to the current one. - Libraries get a new major version under semantic versioning.
- Workflows and screens get the new flow alongside the old one, behind a feature flag or setting.
- The new version gets its own level, usually Alpha or Beta, while fixes to the current version stay GA.
- Nothing is removed until the client has agreed a deprecation period and has a migration path.
Setting up the labels
To create the labels in a repository, or update them after they change, run these commands in a clone of it (or add --repo exalynt/<name>):
gh label create "stability: prototype" --color 6d6a7c --description "Prototype: exploring an idea; expect it to change completely or be thrown away" --force
gh label create "stability: alpha" --color 9c4f6c --description "Alpha: works but still taking shape; expect frequent breaking changes and bugs" --force
gh label create "stability: beta" --color 3f6f88 --description "Beta: refining; occasional breaking changes, announced ahead of time when we can" --force
gh label create "stability: ga" --color 4c7a58 --description "GA: generally available and stable; breaking changes only in a new version" --force
They're generated from the level definitions in the design package, @exalynt/design, so they always match the labels above.
Showing stability in software
Any feature that isn't GA should say so where people use it, with the stability mark: Alpha. The design system covers the mark's sizes and colors, where to show it, and the StabilityMark component that draws it.
Frequently asked questions
What if a pull request spans more than one level?
Split it if that's easy. If not, label it with the highest level it touches, since that's what the whole change has to hold up to.
Do refactoring, tooling, and dependency updates need a label?
Yes. Label them with the level of the code they change. Changes to CI, deployment, or shared tooling that people already depend on are GA.
Can I label work Prototype so it needs fewer tests?
Only if it really is a prototype. The label tells people what they can rely on, so if the work is going to be depended on, label it for that, or make sure the client knows it isn't ready to be.