Skip to content

apuya/react-basics-ui / .claude/skills/release

release

Unverified

Release 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.

ModeUse whenOutput
PlanA release is upcoming and scope, cadence, or audience must be setRelease plan (version, freeze date, RC date, GA date, audience, exit criteria, rollback owner)
CutA release branch or RC must be mintedBranch name, base SHA, version bump, merge-back rule, who can land what
QualifyAn RC must be promoted or rejectedExit checklist verdict per item, blockers named, decision and owner
RollA release is going to users in stagesRollout schedule (cohorts, percentages, hold points, metric watch)
FlagA feature flag needs creation, ramp, or retirementFlag spec (purpose, default, audience, ramp plan, cleanup trigger and date)
HotfixA defect must ship outside the normal cadenceHotfix branch source, scope rule, version bump, merge-back path, rollout shape
RollbackA release must be withdrawn or its inverse authoredRollback procedure (trigger, command, expected duration, verification, comms)
NotesA release needs notes for one or more audiencesNotes per audience (user-facing, operator, integrator) with severity and migration steps
AuditAn existing release process needs reviewTiered 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:

SectionApplies here?
Versioning / semver bump rulesYes — the core of it. The public API is the product
Release notes, changelogYes. The integrator audience is the only audience
Release branch, hotfix flowYes, in reduced form
Staged rollout, percent ramps, cohortsNo. Consumers upgrade when they choose
Feature flags, kill switches, flag lifecycleNo. No runtime you can toggle
Rollback playbookNot 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:

  1. Publish a fixed patch immediately — this is roll-forward, and it is the actual remedy.
  2. npm deprecate <pkg>@<bad-version> "<why, and what to upgrade to>" so installs warn.
  3. 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: Badge dropped its deprecated variant / leadingIcon / trailingIcon props; Table removed Table.Body, Table.HeaderContainer, and Table.ActionBar; Input renamed leadingIcon → leadingVisual. That is a 2.0.0, and each of those needs a migration line in the release notes.

There is no CHANGELOG.md and 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."

  1. Scope. A named version with an explicit list of changes that belong to it, and an explicit list of changes that do not.
  2. Freeze. A point after which only fixes against the named scope land on the release branch. Mainline keeps moving.
  3. 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.
  4. 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.
  5. Roll. The qualified artifact is exposed to users in defined stages, each with a hold point and a metric to watch.
  6. 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.
  7. 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.

SchemeShapeUse when
Semantic (semver)MAJOR.MINOR.PATCHConsumers integrate against an interface and must reason about breakage
Calendar (calver)YYYY.MM or YYYY.MM.PATCHCadence is the contract; no public interface stability claim
SequentialMonotonic integerInternal-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 below 1.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

CadenceShapeCostUse when
ContinuousEvery merge to mainline is releasable; release on demandNo release branch overhead; every commit must be release-qualitySingle-tenant SaaS, one production environment
TrainFixed interval (weekly, monthly) cuts a branch on schedule whether or not scope is fullPredictable; some releases ship thinMultiple consumers expect a rhythm
MilestoneA release ships when its scope is completeScope-driven; date is a forecastVersioned 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.0 cuts from mainline, mainline becomes 1.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 shapeUse whenHold criterion
Cohort (internal → beta → general)The product has identifiable user groupsEach cohort runs for the observation window before the next
Percentage (1 % → 10 % → 50 % → 100 %)The audience is large and uniformError/latency budget at the previous step held during the window
RegionalRegulatory or latency reasons require isolation per regionThe 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:

  1. Set the flag to the post-flag default in code (remove the branch).
  2. Remove the flag definition.
  3. Delete tests that exercised the unused branch.
  4. 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.

AudienceWhat they needStyle
End userWhat is new or different in the product they usePlain language, action where action is needed
OperatorWhat runs differently, what alerts may change, what to do during rollbackSpecific: command names, file paths, alert names
IntegratorWhat changed in the public interface, with migration stepsVersioned: 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
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: 196kUpdated Claude CodeCodexVerifiedInstall
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: 192kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 192kUpdated Claude CodeCodexVerifiedInstall
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: 192kUpdated Claude CodeCodexVerifiedInstall