changelog generator & diff tool
stormlightlabs.github.io/git-storm/
changelog
changeset
markdown
golang
git
1---
2title: Development
3outline: deep
4---
5
6# Development
7
8Storm is designed to be hackable: each package works on its own and can be
9composed in tests or other Go programs. This document contains the guidance that
10previously lived in the repository README.
11
12## Guidance
13
141. **Composable:** packages such as `diff`, `gitlog`, and `tui` should expose
15 standalone entry points that can be imported elsewhere.
162. **Frontmatter:** `.changes/*.md` entries follow this schema:
17
18 ```yaml
19 type: added
20 scope: cli
21 summary: Add changelog command
22 ```
23
243. **Palette:** all TUIs must use the colors defined in `internal/style`.
254. **Command chaining:** every command should behave well in pipelines, e.g.
26
27 ```sh
28 storm unreleased list --json
29 storm generate --since v1.2.0 --interactive
30 storm release --bump patch --toolchain package.json
31 ```
32
335. **Tests:**
34 - Prefer teatest for Bubble Tea programs.
35 - Use golden files for diff/changelog output when useful.
36 - Spin up in-memory `go-git` repositories in unit tests.
37
38## Notes
39
40- Keep the workflow deterministic so releases can be derived from local files
41 alone.
42- TUIs should degrade gracefully when `stdin`/`stdout` are not TTYs.
43- The binary should not depend on external services beyond git data already in
44 the repo.
45
46## Roadmap
47
48| Phase | Deliverable |
49| ----- | ---------------------------------------------- |
50| 1 | Core CLI (`generate`, `unreleased`, `release`) |
51| 2 | Git integration and commit parsing |
52| 3 | Diff engine and styling |
53| 4 | `.changes` storage and parsing |
54| 5 | Interactive TUI |
55| 6 | Keep a Changelog writer |
56| 7 | Git tagging and CI integration |
57
58## Conventional Commits
59
60Storm follows the [Conventional Commits](https://www.conventionalcommits.org)
61spec. Use the format `type(scope): summary` with optional body and footers.
62
63### Structure
64
65| Element | Format | Description |
66| ------- | ------ | ----------- |
67| Header | `<type>(<scope>): <description>` | Main commit line. |
68| Scope | Optional, e.g. `api`, `cli`, `deps`. | Part of the codebase affected. |
69| Breaking indicator | `!` after type/scope, e.g. `feat(api)!:` | Marks breaking change. |
70| Body | Blank line then body text. | Explains what and why. |
71| Footer | Blank line then metadata. | Issue references, `BREAKING CHANGE`, etc. |
72
73### Types
74
75| Type | Description |
76| ---- | ----------- |
77| `feat` | New feature. |
78| `fix` | Bug fix. |
79| `docs` | Documentation change. |
80| `style` | Formatting-only change. |
81| `refactor` | Structural change without new features or fixes. |
82| `perf` | Performance improvement. |
83| `test` | Adds or updates tests. |
84| `build` | Build system or dependency change. |
85| `ci` | CI config change. |
86| `chore` | Tooling or config change outside src/test. |
87| `revert` | Reverts a previous commit. |
88
89### Examples
90
91```text
92feat(api): add pagination endpoint
93fix(ui): correct button alignment issue
94docs: update README installation instructions
95perf(core): optimize user query performance
96refactor: restructure payment module for clarity
97style: apply consistent formatting
98test(auth): add integration tests for OAuth flow
99build(deps): bump dependencies to latest versions
100ci: add GitHub Actions workflow for CI
101chore: update .gitignore and clean up obsolete files
102feat(api)!: remove support for legacy endpoints
103
104BREAKING CHANGE: API no longer accepts XML-formatted requests.
105```