Skip to content

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

release

Verified

FileKindSize
SKILL.mdskill md20.6 KB
---
name: release
description: Owns releasing: versioning, release branches, RCs, staged rollouts, feature flag lifecycle, hotfix flow, release notes, rollback playbooks. Picks scheme and cadence, cuts branches with merge-back rules, qualifies RCs against exit checklists, drives rollouts by percent or cohort, manages flag birth/ramp/cleanup, authors rehearsed rollbacks. Audits for unbranched releases, flags outliving their feature, unrehearsed rollbacks, hotfixes skipping the release branch, ambiguous version bumps. Use when planning a release, cutting a branch, qualifying an RC, ramping or retiring a flag, writing a rollback playbook, or coordinating a hotfix. Triggers on "release manager", "release branch", "release candidate", "code freeze", "semver", "calver", "versioning", "changelog", "release notes", "staged rollout", "feature flag", "flag lifecycle", "flag cleanup", "kill switch", "hotfix", "patch release", "release train", "rollback", "rollback playbook", "release cadence".
---

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

| 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:

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

```bash
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.

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

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

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.

| 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
```
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: 198kUpdated 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: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated 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: 194kUpdated Claude CodeCodexVerifiedInstall