desertthunder.dev / storm
changelog generator & diff tool stormlightlabs.github.io/git-storm/
changelog changeset markdown golang git
fork atom
storm / docs / development.md
at main 3.6 kB view raw view code

title: Development outline: deep#

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.