apuya/react-basics-ui / .claude/skills/release
release
UnverifiedRelease Manager
Owns the act of releasing: declaring that a specific revision becomes the next version, to whom it is exposed, on what schedule, and how it is withdrawn. Optimises for reversibility first, audience clarity second, calendar predictability third. Does not own how artifacts are built or deployed, and does not own whether the running system meets its SLO.
Mode Router
Pick one mode per invocation. If ambiguous, ask.
| Mode | Use when | Output |
|---|---|---|
| Plan | A release is upcoming and scope, cadence, or audience must be set | Release plan (version, freeze date, RC date, GA date, audience, exit criteria, rollback owner) |
| Cut | A release branch or RC must be minted | Branch name, base SHA, version bump, merge-back rule, who can land what |
| Qualify | An RC must be promoted or rejected | Exit checklist verdict per item, blockers named, decision and owner |
| Roll | A release is going to users in stages | Rollout schedule (cohorts, percentages, hold points, metric watch) |
| Flag | A feature flag needs creation, ramp, or retirement | Flag spec (purpose, default, audience, ramp plan, cleanup trigger and date) |
| Hotfix | A defect must ship outside the normal cadence | Hotfix branch source, scope rule, version bump, merge-back path, rollout shape |
| Rollback | A release must be withdrawn or its inverse authored | Rollback procedure (trigger, command, expected duration, verification, comms) |
| Notes | A release needs notes for one or more audiences | Notes per audience (user-facing, operator, integrator) with severity and migration steps |
| Audit | An existing release process needs review | Tiered findings (Blocker / High / Medium) with the rule each violates |
Releasing a package, not a deployment
Read this before the rest of the skill. react-basics-ui is published to a
registry; it is not deployed to servers you control. Several sections below assume
a running system and do not apply:
| Section | Applies here? |
|---|---|
| Versioning / semver bump rules | Yes — the core of it. The public API is the product |
| Release notes, changelog | Yes. The integrator audience is the only audience |
| Release branch, hotfix flow | Yes, in reduced form |
| Staged rollout, percent ramps, cohorts | No. Consumers upgrade when they choose |
| Feature flags, kill switches, flag lifecycle | No. No runtime you can toggle |
| Rollback playbook | Not as written — see below |
Rollback is deprecation
You cannot recall a published version; anyone who installed it still has it, and
npm unpublish is restricted and hostile to consumers who pinned it. The real
sequence when a bad version ships:
- Publish a fixed patch immediately — this is roll-forward, and it is the actual remedy.
npm deprecate <pkg>@<bad-version> "<why, and what to upgrade to>"so installs warn.- If the bad version was tagged
latest, repoint the tag:npm dist-tag add <pkg>@<good-version> latest.
Rehearsal still matters, but what you rehearse is npm pack and installing the
tarball into a scratch project — not a deploy rollback.
Pre-release uses dist-tags
npm publish --tag next keeps a release off latest so npm install <pkg>
doesn't pick it up. That is this ecosystem's equivalent of a staged rollout: opt-in
by tag rather than percentage.
The bump is decided by the type surface
For a library the MAJOR/MINOR question is usually answerable mechanically: build
the .d.ts before and after and diff it. A removed export, a removed prop, a
narrowed union, or a renamed prop is MAJOR — no judgement call needed.
Applies to the current state of this repo. The component-library refresh introduced breaking API changes against the published
1.0.0:Badgedropped its deprecatedvariant/leadingIcon/trailingIconprops;TableremovedTable.Body,Table.HeaderContainer, andTable.ActionBar;InputrenamedleadingIcon→leadingVisual. That is a2.0.0, and each of those needs a migration line in the release notes.There is no
CHANGELOG.mdand no git tags yet. Both should exist before the next publish — without them, an integrator has no way to learn what broke.
Pre-publish checklist for this package
npx playwright install chromium # once per machine
npm run lint && npx tsc --noEmit -p tsconfig.json && npx vitest run && npm run build
ls dist/index.js dist/index.cjs dist/index.d.ts dist/index.css # all four
npm pack --dry-run # inspect the tarball's file list
npx vitest run covers both projects — the jsdom unit suite and the story
play() functions in headless Chromium. Don't narrow it to --project unit
for a release: the story project is what proves the components still behave
under real pointer and keyboard input.
The files: ["dist"] field means only dist ships. If npm pack --dry-run lists
source files or omits dist/index.css, stop — consumers get a package that cannot
style itself.
Release lifecycle order
Every release moves through these stages in order. Skipping a stage is the most common source of "we shipped it but cannot say what we shipped."
- Scope. A named version with an explicit list of changes that belong to it, and an explicit list of changes that do not.
- Freeze. A point after which only fixes against the named scope land on the release branch. Mainline keeps moving.
- Cut. The release branch is created from a known base SHA. The version is bumped on mainline so the branch and mainline never share a version number again.
- Qualify. The RC is built from the branch and walked through an exit checklist. The verdict is binary: promote or reject. There is no "promote with known issues" without recorded acceptance.
- Roll. The qualified artifact is exposed to users in defined stages, each with a hold point and a metric to watch.
- Stabilise. The release runs at full audience for an observation window. Until that window closes, the rollback path is the primary fix mechanism, not roll-forward.
- Close. Merge-back to mainline, retire the branch, retire any flags whose feature is now permanent, record the version in the artifact registry.
A release that is "out" but has no closed stage is unfinished work — track it.
Versioning
Scheme
Pick one and stay with it. Mixing schemes inside one product line guarantees a future migration.
| Scheme | Shape | Use when |
|---|---|---|
| Semantic (semver) | MAJOR.MINOR.PATCH | Consumers integrate against an interface and must reason about breakage |
| Calendar (calver) | YYYY.MM or YYYY.MM.PATCH | Cadence is the contract; no public interface stability claim |
| Sequential | Monotonic integer | Internal-only artifacts where humans never read the version |
Bump rules (semver)
- MAJOR: a change a consumer must do work to absorb. Removing a field, narrowing a type, changing default behaviour, raising a minimum dependency.
- MINOR: additive and backward compatible. New endpoint, new optional field, new flag default-off.
- PATCH: fix without interface change. Bug fix, performance fix, security fix that does not alter behaviour.
An ambiguous bump is almost always a MAJOR — if reasonable people disagree about whether consumers must do work, at least one of them is going to be surprised.
Pre-release and build metadata
- Pre-release:
1.4.0-rc.1,1.4.0-beta.2. Sorts below1.4.0. - Build metadata:
1.4.0+sha.abc1234. Ignored for precedence but identifies the artifact.
A version string with no pre-release suffix is a promise that it is GA. Do not use bare numbers for RCs.
Cadence
| Cadence | Shape | Cost | Use when |
|---|---|---|---|
| Continuous | Every merge to mainline is releasable; release on demand | No release branch overhead; every commit must be release-quality | Single-tenant SaaS, one production environment |
| Train | Fixed interval (weekly, monthly) cuts a branch on schedule whether or not scope is full | Predictable; some releases ship thin | Multiple consumers expect a rhythm |
| Milestone | A release ships when its scope is complete | Scope-driven; date is a forecast | Versioned libraries, on-prem distributions |
A train that slips for scope is a milestone wearing a costume. Pick the shape honestly.
Branch strategy
Trunk-only
Mainline is the release. Tag commits; do not branch. Works when the cadence is continuous, the audience is one environment, and there is no need to backport a fix to an older version still in the wild.
Release branch
Cut a branch when:
- An older version must remain supportable while mainline progresses.
- Freeze and qualification take longer than the gap between merges.
- More than one version is concurrently in the field.
Rules for a release branch:
- Base SHA is recorded in the release plan. The branch is not redefinable after cut.
- Bump mainline immediately. If
1.4.0cuts from mainline, mainline becomes1.5.0-dev(or equivalent) in the same change. Branch and mainline never share a version. - What lands here: fixes against the named scope, plus regressions found during qualification. Nothing else.
- Merge-back is mandatory. Every commit on the branch returns to mainline before the branch closes — by merge, cherry-pick, or rebase — chosen once and applied consistently. Drift between branch and mainline is how a fixed bug reappears in the next release.
- Owner is named. The branch has one approver for what lands on it.
Hotfix
A hotfix branches from the tag being patched, not from mainline.
v1.4.0 ──────────● (tag)
│
└─ hotfix/1.4.1 ──● ─ tag v1.4.1
│
└─ merge-back to mainline AND to any newer release branch still in support
A hotfix that branches from mainline picks up unrelated changes and is no longer a hotfix. A hotfix that does not merge back will reappear as the same bug in the next release.
Release candidate qualification
An RC is qualified against an exit checklist agreed before the RC is built. Items are pass/fail. "Mostly passing" is failing.
Default exit checklist
- All tests of the suites named in the release plan are green on the RC artifact.
- Migrations (if any) have been applied to a clone of production and reversed cleanly.
- The rollback procedure for this release has been executed against the prior version in a non-production environment within the last 90 days.
- Release notes exist for every audience the release plan names.
- Every feature flag introduced by the release has a default value, an owner, and a cleanup trigger.
- Every behaviour change a consumer can observe is either covered by a version bump or recorded as deliberately silent.
- The on-call rotation knows the release is rolling and has the rollback command at hand.
A checklist item that is always passed without being checked is theatre. Either delete it or define what failure of that item looks like.
Known-issue acceptance
An issue surfaced during qualification is one of:
- Blocker: rejects the RC. New RC required.
- Accepted: documented in the release notes for the affected audience, with a workaround and a target version for the fix.
- Deferred: added to the scope of a future release with a date.
There is no fourth category. "We will fix it in the next RC" without a rejection produces RCs that never converge.
Staged rollout
The qualified artifact is exposed to users in stages. Each stage has a defined hold point and a metric to watch.
| Stage shape | Use when | Hold criterion |
|---|---|---|
| Cohort (internal → beta → general) | The product has identifiable user groups | Each cohort runs for the observation window before the next |
| Percentage (1 % → 10 % → 50 % → 100 %) | The audience is large and uniform | Error/latency budget at the previous step held during the window |
| Regional | Regulatory or latency reasons require isolation per region | The first region runs at the observation window before the next |
Hold points
The point of a stage is the hold. A rollout that proceeds without a hold is a single-stage rollout in disguise.
- Observation window: time the new version runs against the cohort before promoting. Long enough that the metric you watch can move.
- Metric to watch: named in the release plan, not invented during the rollout. Errors, latency, conversion, success rate of a critical path. The owner is named.
- Promotion trigger: the metric held within tolerance for the window. Not a clock.
- Abort trigger: the inverse — the condition that triggers the rollback and who is empowered to call it.
A staged rollout with no abort trigger is a staged deployment.
Feature flag lifecycle
A feature flag is a release tool, not a configuration system. Treat each flag as a temporary structure with a birth date and a death date.
Birth
A flag is created with:
- Purpose: the change it gates, in one sentence.
- Owner: a person, not a team. The person who cleans the flag up.
- Default: the value when the flag is not explicitly set. Default-off for new behaviour; default-on only for kill switches.
- Audience model: how the flag is evaluated — user, account, region, percentage, environment. One model per flag.
- Cleanup trigger: the condition that retires the flag —
flag at 100 % for 30 days,feature deprecated,regulatory window passes. A flag with no trigger is permanent configuration; rename it as such. - Target retirement date: an absolute date, not a milestone. Milestones slip.
Ramp
Each ramp step is a release in miniature: a hold point, a metric to watch, an abort trigger.
Retirement
When the cleanup trigger fires:
- Set the flag to the post-flag default in code (remove the branch).
- Remove the flag definition.
- Delete tests that exercised the unused branch.
- Close the flag record.
A flag at 100 % for months is dead code with a configuration surface. It is the most common source of "I changed a setting and nothing happened" incidents.
Kill switches
A kill switch is a permanent flag with default-on, used to disable a feature in production without a deploy.
- It is the only category of flag with no retirement date.
- It must be exercised at least quarterly. A kill switch that has never been thrown is a hypothesis.
- It must have a single, documented effect. "Disable feature X" — not "disable feature X and also drain queue Y."
Release notes
Notes are written per audience, not per change. The same change may appear in multiple notes with different framing, or in none.
| Audience | What they need | Style |
|---|---|---|
| End user | What is new or different in the product they use | Plain language, action where action is needed |
| Operator | What runs differently, what alerts may change, what to do during rollback | Specific: command names, file paths, alert names |
| Integrator | What changed in the public interface, with migration steps | Versioned: every breaking change cited with the old and new shape |
Rules
- Group by audience-relevant category (Added / Changed / Deprecated / Removed / Fixed / Security), not by author or by ticket number.
- Cite the version a change first appeared in, not "this release."
- A breaking change has a migration step. If the migration is "no action required," say so explicitly — silence is interpreted as "I missed it."
- A security fix has a severity. Suppressing severity to avoid alarm produces consumers who do not patch.
- Notes are frozen at GA. Post-GA edits get their own changelog entry; the original is preserved.
Rollback playbook
Every release ships with its inverse. The playbook is authored before the release rolls, exercised before it is needed, and runnable by an operator who did not write the release.
Contents
- Trigger: the named condition that calls the rollback. "Error rate above X for Y minutes." "Manual call by the on-call." Not "judgment."
- Command: the exact command, with arguments, copy-pastable. Not "redeploy the previous version" — the command that does so.
- Expected duration: how long from invocation to user-visible recovery.
- Verification: the check that confirms recovery — the same metric the abort trigger watched, returned to baseline.
- Compatibility note: what state the rollback leaves behind — data written in the new format, flags set during the rollout, queues drained or not.
- Comms: who is notified, on what channel, with what status-page entry template.
Rehearsal
The playbook is exercised against the prior version in a non-production environment on a defined cadence (quarterly minimum). An unexercised rollback is a hypothesis. The cost of finding it broken during an incident is the incident plus the rollback.
Roll-forward is not rollback
"Roll forward" means writing new code under outage pressure. It is a legitimate response when the change is non-reversible (schema migration, data backfill, sent email). It is not a substitute for a rollback path on reversible changes. A release plan that names roll-forward as the only path must justify why the change is non-reversible, in writing.
Red flags
Treat as bugs unless justified in writing:
- A release with no named version.
- A version bump where reasonable people disagreed about MAJOR vs MINOR and the disagreement is unresolved.
- A release branch with no recorded base SHA.
- A release branch and mainline sharing a version.
- A hotfix branched from mainline rather than from the tag being patched.
- A hotfix that does not merge back to mainline.
- An RC promoted with open blockers and no recorded acceptance.
- A staged rollout with no hold point or no named metric.
- A staged rollout where every stage was held for the same fixed clock time regardless of the metric.
- A feature flag with no owner, no default, or no cleanup trigger.
- A feature flag at 100 % for longer than the release cadence with no retirement scheduled.
- A kill switch that has never been exercised.
- A release with no rollback playbook.
- A rollback playbook with no rehearsal in the last 90 days.
- Release notes that say "various improvements and bug fixes" for a release with a public interface change.
- A breaking change shipped without a MAJOR bump.
- A security fix shipped without a severity.
- Post-GA edits to the changelog that overwrite the original entry.
- A release whose only owner has left the team.
- A release process where "the same person always approves" — single-point-of-failure on cadence.
Decision flowchart — "something is wrong with the release"
Release is in trouble
│
├─ Not yet rolled?
│ ├─ Scope is unclear → return to Plan; name what is in, what is out
│ ├─ RC failing exit check → reject RC, fix on branch, mint next RC
│ └─ Rollback unrehearsed → block promotion; rehearse against prior version
│
├─ Rolling now and metric is bad?
│ ├─ Within abort tolerance? → hold the stage, do not promote
│ └─ Past abort tolerance? → invoke rollback playbook; do not diagnose first
│
├─ Rolled, defect discovered?
│ ├─ Reversible → rollback; investigate from prior version
│ └─ Non-reversible → hotfix from the released tag; new patch release
│
└─ Rolled, stable, flag still partial?
├─ Cleanup trigger met → retire the flag; remove the branch in code
└─ Cleanup trigger missed → name the new trigger and date, or convert to permanent config
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |