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

Roadmap#

Core CLI#

The foundation CLI structure with core commands.

Commands#

  • storm version - Print version information
  • storm generate - Generate changelog entries from Git commits
    • Parse commit range (from/to refs)
    • Support --since flag
    • Support --interactive flag for TUI selection
    • Parse conventional commits
    • Write entries to .changes/
    • Deduplication logic (see TODO in generate.go)
    • Add --output-json for machine use
  • storm unreleased - Manage unreleased changes
    • unreleased add - Create new entry
    • unreleased list - Display entries (text and JSON)
    • unreleased review - Interactive TUI review
    • unreleased partial - Create entry linked to specific commit
      • Filename format: <sha7>.<type>.md
      • Auto-detect type from conventional commit format
      • Optional --type, --scope, --summary override flags
      • Optional --issue flag (TODO: see issue-linking task below)
    • Implement delete action from review
    • Implement edit action from review
  • storm check - Validate that changes include unreleased partials
    • Detect missing partials for changed code paths
    • Honor [nochanges] and [skip changelog] markers in commit messages
    • Exit non-zero for CI enforcement
    • Support --since flag for checking since a tag
  • storm release - Promote unreleased changes to CHANGELOG
    • Read all .changes/*.md files
    • Merge into CHANGELOG.md
    • Create version header with date
    • Clear .changes/ directory with --clear-changes flag
    • Optional date override with --date flag
    • Generate GitHub comparison links automatically
    • Dry-run mode
    • Optional Git tag creation
  • storm diff: display inline diffs between refs with support for file filtering, context expansion, and multiple view modes.

Git Integration and Commit Parsing#

  • Core gitlog utilities for parsing refs, retrieving commits and file contents, and categorizing conventional commits by type and change significance.

Diff Engine and Styling#

  • Diff package implements the Myers diff algorithm with split and unified rendering, compressed unchanged sections, and an iceberg-themed color palette for styled visual output.

.changes Storage and Parsing#

  • Provides a local .changes/ store that writes and lists YAML-frontmatter entries, auto-creates the directory, and deduplicates rebased commits by diff hash to keep unreleased changelog items clean.

TUI#

  • Delivered Bubble Tea UIs for selecting commits, reviewing unreleased changes, and interactively viewing multi-file diffs with full keyboard-driven navigation and view toggles.

Keep a Changelog Writer#

  • Adds a full changelog pipeline that parses the existing file, builds and writes new releases, and validates dates/sections to strictly match the Keep a Changelog spec, including autogenerated comparison links.
  • Ensure deterministic sorting by category and filename timestamp

Issue Linking#

Add support for linking changelog entries to issue/PR numbers.

Tasks#

  • Add --issue flag to unreleased add and unreleased partial
  • Add issue field to Entry struct
  • Include issue number in YAML frontmatter
  • Support issue validation in check command
  • Format issue links in generated CHANGELOG (e.g., #123, owner/repo#123)

Phase 7: Git Tagging and CI Integration#

Repository tagging and automation-friendly features.

Tasks#

  • Implement Git tagging in release command
    • Create annotated tag with version
    • Include release notes in tag message
    • Validate tag doesn't already exist
    • Support --tag flag
  • Implement CI validation with check command
    • Validate changelog entries exist for commits
    • Honor [nochanges] markers
    • Exit codes for CI integration
  • Add JSON output modes for all commands
    • unreleased list --json
    • generate --output-json
    • release --output-json
  • Add --dry-run support
    • release --dry-run
    • Show what would be written without writing
    • Display preview of CHANGELOG changes with styled output
  • Non-TTY environment handling
    • Detect TTY availability
    • Fallback to non-interactive mode
    • CI-friendly error messages
  • Add pre-commit hook examples
    • Validate commit message format
    • Ensure .changes/ entries exist for features
  • Create GitHub Actions workflow examples
    • Auto-release on version tag
    • Validate CHANGELOG on PR

Testing Strategy#

Current Status#

  • Test utilities package - internal/testutils/
  • Unit tests for changelog package - internal/changelog/changelog_test.go
  • Unit tests for diff engine
  • Unit tests for Git integration (in-memory repos)
  • Golden files for diff output
  • Golden files for changelog output
  • Bubble Tea program testing

Planned Test Coverage#

  • internal/diff - Myers algorithm correctness
  • internal/gitlog - Commit parsing and range queries
  • internal/changeset - File I/O and YAML parsing
  • internal/changelog - Keep a Changelog formatting (13 test cases, all passing)
  • cmd/generate - End-to-end commit to entry flow
  • cmd/unreleased - Entry management
  • cmd/release - Changelog generation and tagging

Notes#

  • No shell calls to git - all operations via go-git
  • Conventional commits are parsed but not enforced
  • TUI sessions degrade gracefully in non-TTY environments
  • All output follows Keep a Changelog v1.1.0 specification