storm — Project Guide#

Internal operations and release workflow

This document outlines:

• The release lifecycle
• CLI integration into development workflows
• Distribution setup for major package managers

Lifecycle#

Local Development#

• Edit and test locally:

  go run ./cmd/storm unreleased add --type fixed --summary "Fix diff rendering"
  go run ./cmd/storm unreleased list
  go run ./cmd/storm unreleased review
  

• Each .changes/*.md entry represents one meaningful change.

2. Preparing a Release#

1. Generate and review

   storm generate v1.2.0 HEAD --interactive
   

   • Opens a Bubble Tea UI for categorization.
   • Outputs candidate .changes/ files if confirmed.

2. Verify unreleased notes

   storm unreleased list
   

3. Promote to changelog

   storm release --version 1.3.0
   

   This:

   • Merges .changes/*.md into CHANGELOG.md
   • Inserts the date
   • Clears .changes/
   • (Optional) creates an annotated Git tag

4. Commit and tag

   git add CHANGELOG.md
   git commit -m "Release 1.3.0"
   git tag -a v1.3.0 -m "Release 1.3.0"
   

Validation#

Before pushing:

go test ./...
go run ./cmd/storm release --dry-run

Once satisfied:

git push origin main --tags

CLI Integration in Workflows#

storm is meant to sit between git log and CHANGELOG.md. Use it at the end of development cycles or integrate it into CI pipelines.

Example integrations#

Local Workflow#

• Add a new .changes file per PR or major commit.
• Review unreleased entries before each merge to main.
• Run storm release when preparing a new version.

Automated Release Job (CI)#

Example pseudo-pipeline (GitHub Actions / Drone / Woodpecker):

steps:
  - name: Compute next version
    run: |
      NEXT=$(storm bump --bump patch)
      echo "::set-output name=version::$NEXT"
  - name: Generate changelog
    run: |
      go install ./cmd/storm
      storm release --version ${{ steps.bump.outputs.version }} --toolchain package.json
  - name: Tag and push
    run: |
      git add CHANGELOG.md
      git commit -m "Release ${{ steps.bump.outputs.version }}"
      git tag -a v${{ steps.bump.outputs.version }} -m "Release ${{ steps.bump.outputs.version }}"
      git push origin main --tags

Integration with other tools#

• Taskfile / Justfile: add release recipe calling storm release.
• GoReleaser: run storm release in before.hooks.
• Custom TUI tools: embed internal/changeset and changelog packages directly.

Packaging & Distribution#

Homebrew (macOS / Linux)#

Create a tap repo#

Make a repo: github.com/stormlightlabs/homebrew-tap.

Formula template (storm.rb)#

class Gostorm < Formula
  desc "Git-aware changelog manager with TUI review"
  homepage "https://github.com/stormlightlabs/git-storm"
  version "1.3.0"
  url "https://github.com/stormlightlabs/git-storm/archive/refs/tags/v1.3.0.tar.gz"
  sha256 "<insert_sha256_here>"
  license "MIT"

  depends_on "go" => :build

  def install
    system "go", "build", *std_go_args, "./cmd/storm"
  end

  test do
    system "#{bin}/storm", "--help"
  end
end

Update formula on each release#

Automate with goreleaser:

brews:
  - tap: stormlightlabs/homebrew-tap
    name: storm
    folder: Formula
    commit_author:
      name: Owais Jamil
      email: owais@example.com

Chocolatey (Windows)#

Create package skeleton#

tools/
  chocolateyinstall.ps1
  VERIFICATION.txt
storm.nuspec

chocolateyinstall.ps1#

$ErrorActionPreference = 'Stop'
$toolsDir   = "$(Split-Path -Parent $MyInvocation.MyCommand.Definition)"
$url        = 'https://github.com/stormlightlabs/git-storm/releases/download/v1.3.0/storm_1.3.0_windows_amd64.zip'

Install-ChocolateyZipPackage 'storm' $url $toolsDir

.nuspec#

<package>
  <metadata>
    <id>storm</id>
    <version>1.3.0</version>
    <authors>Owais Jamil</authors>
    <description>Git-aware changelog manager with TUI review</description>
    <licenseUrl>https://opensource.org/licenses/MIT</licenseUrl>
    <projectUrl>https://github.com/stormlightlabs/git-storm</projectUrl>
  </metadata>
</package>

Build & push#

choco pack
choco push storm.1.3.0.nupkg --source https://push.chocolatey.org/

AUR#

Create PKGBUILD#

pkgname=storm
pkgver=1.3.0
pkgrel=1
pkgdesc="Git-aware changelog manager with TUI review"
arch=('x86_64')
url="https://github.com/stormlightlabs/git-storm"
license=('MIT')
depends=('git' 'go')
source=("$url/archive/refs/tags/v${pkgver}.tar.gz")
sha256sums=('SKIP')

build() {
  cd "$srcdir/storm-$pkgver"
  go build -o storm ./cmd/storm
}

package() {
  install -Dm755 storm "$pkgdir/usr/bin/storm"
}

Submit#

Clone AUR repo:

git clone ssh://aur@aur.archlinux.org/storm.git
cp PKGBUILD storm/
cd storm
makepkg --printsrcinfo > .SRCINFO
git add .
git commit -m "Add storm v1.3.0"
git push

Summary#

Maintenance Notes#

• Keep .changes/ entries atomic and descriptive.
• Avoid retroactive changelog edits outside releases.
• Tag every release in Git with an exact semantic version (vX.Y.Z).
• Ensure TUI remains optional (disable automatically in CI).
• Treat changelog generation as a testable unit — not a side effect.