Development

Storm is designed to be hackable: each package works on its own and can be composed in tests or other Go programs. This document contains the guidance that previously lived in the repository README.

Guidance

1. Composable: packages such as diff, gitlog, and tui should expose standalone entry points that can be imported elsewhere.

2. Frontmatter: .changes/*.md entries follow this schema:

   type: added
   scope: cli
   summary: Add changelog command

3. Palette: all TUIs must use the colors defined in internal/style.

4. Command chaining: every command should behave well in pipelines, e.g.

   storm unreleased list --json
   storm generate --since v1.2.0 --interactive
   storm release --bump patch --toolchain package.json

5. Tests:

   • Prefer teatest for Bubble Tea programs.
   • Use golden files for diff/changelog output when useful.
   • Spin up in-memory go-git repositories in unit tests.

Notes

• Keep the workflow deterministic so releases can be derived from local files alone.
• TUIs should degrade gracefully when stdin/stdout are not TTYs.
• The binary should not depend on external services beyond git data already in the repo.

Roadmap

Phase	Deliverable
1	Core CLI (generate, unreleased, release)
2	Git integration and commit parsing
3	Diff engine and styling
4	.changes storage and parsing
5	Interactive TUI
6	Keep a Changelog writer
7	Git tagging and CI integration

Conventional Commits

Storm follows the Conventional Commits spec. Use the format type(scope): summary with optional body and footers.

Structure

Element	Format	Description
Header	<type>(<scope>): <description>	Main commit line.
Scope	Optional, e.g. api, cli, deps.	Part of the codebase affected.
Breaking indicator	! after type/scope, e.g. feat(api)!:	Marks breaking change.
Body	Blank line then body text.	Explains what and why.
Footer	Blank line then metadata.	Issue references, BREAKING CHANGE, etc.

Types

Type	Description
feat	New feature.
fix	Bug fix.
docs	Documentation change.
style	Formatting-only change.
refactor	Structural change without new features or fixes.
perf	Performance improvement.
test	Adds or updates tests.
build	Build system or dependency change.
ci	CI config change.
chore	Tooling or config change outside src/test.
revert	Reverts a previous commit.

Examples

feat(api): add pagination endpoint
fix(ui): correct button alignment issue
docs: update README installation instructions
perf(core): optimize user query performance
refactor: restructure payment module for clarity
style: apply consistent formatting
test(auth): add integration tests for OAuth flow
build(deps): bump dependencies to latest versions
ci: add GitHub Actions workflow for CI
chore: update .gitignore and clean up obsolete files
feat(api)!: remove support for legacy endpoints

BREAKING CHANGE: API no longer accepts XML-formatted requests.