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