storybook/.claude/RELEASE-CHECKLIST.md

# Storybook Release Process Checklist

> **Template Version:** 1.0
>
> This checklist integrates with the commit and testing policies defined in
> `.claude/CLAUDE.md`. All CLAUDE.md policies remain in effect throughout the
> release process. Do not proceed to Phase 8 (Release Artifacts) until
> Phases 1-7 are complete.

## How to Use

1. Copy this checklist into a new file at `.claude/tmp/release-vX.Y.Z.md`
2. Replace `vX.Y.Z` with the target version throughout
3. Work through each phase in order, checking off items as they are completed
4. Do not skip phases or reorder them -- earlier phases gate later ones

---

## Phase 1: Code Quality & Testing

> _Enforces CLAUDE.md: "All tests must pass", "No unused variables or dead code"_

- [ ] All `cargo test` tests pass with 0 failures
- [ ] All `cargo test --lib` unit tests pass
- [ ] `cargo clippy` reports no warnings or errors
- [ ] `cargo fmt --check` reports no formatting issues
- [ ] No unused variables, imports, or dead code in the codebase
- [ ] No `#[allow(dead_code)]` or underscore-prefixed suppressions added for release
- [ ] All new code introduced since last release has corresponding tests
- [ ] Pre-commit hooks pass cleanly (trailing whitespace, rustfmt, clippy)

## Phase 2: Documentation

- [ ] `docs/README.md` reflects the new version and any feature changes
- [ ] All reference docs in `docs/reference/` are up to date with current syntax
- [ ] Tutorial docs in `docs/tutorial/` work with the current compiler
- [ ] SBIR specification (`docs/SBIR-vX.Y.Z-SPEC.md`) exists if binary format changed
- [ ] `docs/TYPE-SYSTEM.md` is current (if type system changes are included)
- [ ] `docs/design.md` reflects any architectural changes
- [ ] No broken internal links between documentation files
- [ ] API and CLI help text matches current behavior

## Phase 3: Examples & Demos

- [ ] All `.story` example files in `docs/examples/` parse without errors
- [ ] Examples compile to valid SBIR output
- [ ] Baker family example (`docs/examples/24-baker-family-complete.md`) is current
- [ ] Examples demonstrate any new features introduced in this release
- [ ] No examples reference removed or renamed syntax

## Phase 4: Version Control & Changelog

> _Enforces CLAUDE.md: commit message format, conventional commits_

- [ ] `Cargo.toml` version field updated to `X.Y.Z`
- [ ] `docs/SBIR-CHANGELOG.md` updated with changes since last release
- [ ] All commits since last release follow conventional commit format
- [ ] No commits bypass pre-commit hooks (`--no-verify` not used)
- [ ] Git history is clean -- no fixup or WIP commits remain
- [ ] Branch is up to date with `mainline`

## Phase 5: Build & Package

- [ ] `cargo build --release` succeeds with no warnings
- [ ] `cargo install --path . --bin sb --force` installs correctly
- [ ] `cargo install --path . --bin storybook-lsp --force` installs correctly
- [ ] LSP binary at `~/.cargo/bin/storybook-lsp` launches without errors
- [ ] `sb` CLI binary executes and shows correct version

## Phase 6: Cross-Platform Testing

- [ ] macOS (primary development platform): full test suite passes
- [ ] Linux (if CI available): full test suite passes
- [ ] Zed extension builds successfully (`cd zed-storybook && ./build-extension.sh`)
- [ ] Zed extension loads and provides syntax highlighting
- [ ] LSP features work in Zed: completions, diagnostics, semantic highlighting
- [ ] `extension.toml` `rev` field points to correct commit SHA

## Phase 7: Performance & Regression

- [ ] Compile times have not regressed significantly
- [ ] Parser handles large `.story` files without timeout
- [ ] SBIR binary output is deterministic (same input produces same output)
- [ ] No regressions in existing test suite from previous release
- [ ] Memory usage is reasonable for typical workloads

## Phase 8: Release Artifacts

> **GATE: Do not begin this phase until Phases 1-7 are all complete.**

- [ ] Final `cargo test` pass immediately before tagging
- [ ] Create annotated git tag: `git tag -a vX.Y.Z -m "Release vX.Y.Z"`
- [ ] Tag message includes a brief summary of major changes
- [ ] Verify tag points to the correct commit: `git log --oneline -1 vX.Y.Z`
- [ ] Push tag to remote: `git push origin vX.Y.Z`

## Phase 9: Communication

- [ ] Release notes written summarizing user-facing changes
- [ ] Breaking changes clearly documented with migration guidance
- [ ] Known issues or limitations listed
- [ ] Contributors acknowledged (if applicable)

## Phase 10: Post-Release Verification

- [ ] Fresh clone of the repository builds successfully
- [ ] `cargo install` from the tagged commit works
- [ ] Zed extension works with the released version
- [ ] LSP connects and provides diagnostics on a sample `.story` file
- [ ] Version number in CLI output matches the tag

---

## Rollback Plan

If critical issues are discovered after tagging:

1. **Do not delete the tag.** Published tags should remain for traceability.
2. Identify and fix the issue on `mainline`.
3. Run the full checklist again for a patch release (`vX.Y.Z+1`).
4. Tag the patch release and document the issue in the changelog.
5. If the release was communicated externally, send a follow-up noting the patch.

For issues discovered before pushing the tag:

1. Delete the local tag: `git tag -d vX.Y.Z`
2. Fix the issue and commit the fix.
3. Re-run Phases 1-7 before re-tagging.

---

## Sign-Off

| Role             | Name | Date | Approved |
|------------------|------|------|----------|
| Developer        |      |      | [ ]      |
| Reviewer         |      |      | [ ]      |
| Release Manager  |      |      | [ ]      |

**Release approved:** [ ] Yes / [ ] No

---

## Notes

- This checklist integrates with `.claude/CLAUDE.md` policies. All commit,
  testing, and code quality rules from CLAUDE.md apply at every phase.
- When updating this template, increment the Template Version at the top
  and note what changed below.
- For breaking changes, consider whether SBIR format version needs updating
  and whether a migration guide is required.

### Template Changelog

- **1.0** - Initial release checklist template