Marking stability levels
Issues and pull requests are labeled with the Stability level they target, and features that aren't GA carry a badge 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 | #8b5cf6 |
| Alpha | stability: alpha | #f97316 |
| Beta | stability: beta | #06b6d4 |
| GA | stability: ga | #22c55e |
- One stability label on each issue and pull request.
- 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 take the level of what they affect. A bug in a GA feature is labeled GA, which tells everyone it breaks something people rely on and comes first.
- 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. Stability levels in practice has what's typically expected at each level.
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 8b5cf6 --description "Prototype: exploring an idea; expect it to change completely or be thrown away" --force
gh label create "stability: alpha" --color f97316 --description "Alpha: works but still taking shape; expect frequent breaking changes and bugs" --force
gh label create "stability: beta" --color 06b6d4 --description "Beta: mostly stable; occasional breaking changes, announced ahead of time" --force
gh label create "stability: ga" --color 22c55e --description "GA: generally available and stable; breaking changes only in a new version" --force
They're generated from src/shared/stability/stability.ts in this repository, so they always match the labels above.
Showing stability in software
Any feature that isn't GA should say so where people use it. Use the shared components rather than a custom badge, so stability levels look the same in every Exalynt product and in these documents.
import { STABILITY, StabilityBadge } from "./shared/stability";
<h2>
Invoice export <StabilityBadge level="beta" />
</h2>;
// With a tooltip, e.g. MUI's in the console:
<Tooltip title={STABILITY.beta.summary}>
<StabilityBadge level="beta" />
</Tooltip>;
| Export | What it's for |
|---|---|
StabilityBadge | The pill: icon and name in the level's color. iconOnly shows just the icon, with the name as its accessible label. Other props and the ref go to the <span>, so it can be wrapped in a tooltip or link. |
StabilityIcon | The level's icon alone, in the current text color. |
STABILITY, STABILITY_LEVELS | Each level's name, summary, expectations, colors, and GitHub label, for tooltips, help text, or your own layouts. |
Getting the components: copy src/shared/stability/ from this repository into your project. It depends only on React and uses a CSS Module, which Vite and Docusaurus support out of the box. Colors follow the light and dark theme the same way theme.css does, through prefers-color-scheme and the data-theme attribute on the root element. This repository is the source of truth: change a level here, then copy the folder to the projects that use it.
Show badges on Prototype, Alpha, and Beta features, and update the badge when the feature moves up. GA is the default expectation, so GA features carry no badge unless you're comparing levels.
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.
Why don't GA features get a badge?
A badge is there to set expectations for something that's still changing. GA is what people expect by default, so marking it everywhere adds noise and makes the real signals easier to miss.