gastown/RELEASING.md

Release Process for Gas Town

This document describes the release process for Gas Town, including GitHub releases and npm packages.

Table of Contents

• Overview
• Prerequisites
• Release Checklist
• 1. Prepare Release
• 2. GitHub Release
• 3. npm Package Release
• 4. Verify Release
• Hotfix Releases

Overview

A Gas Town release involves multiple distribution channels:

1. GitHub Release - Binary downloads for all platforms
2. npm - Node.js package for cross-platform installation (@gastown/gt)

Prerequisites

Required Tools

• git with push access to steveyegge/gastown
• goreleaser for building binaries
• npm with authentication (for npm releases)
• gh CLI (GitHub CLI, recommended)

Required Access

• GitHub: Write access to repository and ability to create releases
• npm: Publish access to @gastown organization

Verify Setup

# Check git
git remote -v  # Should show steveyegge/gastown

# Check goreleaser
goreleaser --version

# Check GitHub CLI
gh auth status

# Check npm
npm whoami  # Should show your npm username

Release Checklist

Before starting a release:

• All tests passing (go test ./...)
• npm package tests passing (cd npm-package && npm test)
• CHANGELOG.md updated with release notes
• No uncommitted changes
• On main branch and up to date with origin

1. Prepare Release

Update CHANGELOG.md

Add release notes to CHANGELOG.md following the Keep a Changelog format:

## [0.2.0] - 2026-01-15

### Added
- New feature X

### Changed
- Improved Y

### Fixed
- Bug in Z

Commit the CHANGELOG changes:

git add CHANGELOG.md
git commit -m "docs: Add CHANGELOG entry for v0.2.0"
git push origin main

Update Version

Update version in relevant files:

1. internal/cmd/version.go - CLI version constant
2. npm-package/package.json - npm package version

# Update versions
vim internal/cmd/version.go
vim npm-package/package.json

# Commit
git add -A
git commit -m "chore: Bump version to 0.2.0"
git push origin main

Create Release Tag

git tag -a v0.2.0 -m "Release v0.2.0"
git push origin v0.2.0

This triggers GitHub Actions to build release artifacts automatically.

2. GitHub Release

Using GoReleaser (Recommended)

GoReleaser automates binary building and GitHub release creation:

# Clean any previous builds
rm -rf dist/

# Create release (uses GITHUB_TOKEN from gh CLI)
GITHUB_TOKEN=$(gh auth token) goreleaser release --clean

This will:

• Build binaries for all platforms (macOS, Linux, Windows - amd64/arm64)
• Create checksums
• Generate release notes from CHANGELOG.md
• Upload everything to GitHub releases

Verify GitHub Release

1. Visit https://github.com/steveyegge/gastown/releases
2. Verify the new version is marked as "Latest"
3. Check all platform binaries are present

3. npm Package Release

The npm package wraps the native binary for Node.js environments.

Test Installation Locally

cd npm-package

# Run tests
npm test

# Pack and test install
npm pack
npm install -g ./gastown-gt-0.2.0.tgz
gt version  # Should show 0.2.0

# Cleanup
npm uninstall -g @gastown/gt
rm gastown-gt-0.2.0.tgz

Publish to npm

# IMPORTANT: Ensure GitHub release with binaries is live first!
cd npm-package
npm publish --access public

Verify npm Release

npm install -g @gastown/gt
gt version  # Should show 0.2.0

4. Verify Release

After all channels are updated:

GitHub

# Download and test binary
curl -LO https://github.com/steveyegge/gastown/releases/download/v0.2.0/gastown_0.2.0_darwin_arm64.tar.gz
tar -xzf gastown_0.2.0_darwin_arm64.tar.gz
./gt version

npm

npm install -g @gastown/gt
gt version

Hotfix Releases

For urgent bug fixes:

# Create hotfix branch from tag
git checkout -b hotfix/v0.2.1 v0.2.0

# Make fixes and bump version
# ... edit files ...

# Commit, tag, and release
git add -A
git commit -m "fix: Critical bug fix"
git tag -a v0.2.1 -m "Hotfix release v0.2.1"
git push origin hotfix/v0.2.1
git push origin v0.2.1

# Follow normal release process
GITHUB_TOKEN=$(gh auth token) goreleaser release --clean

# Merge back to main
git checkout main
git merge hotfix/v0.2.1
git push origin main

Version Numbering

Gas Town follows Semantic Versioning:

• MAJOR (x.0.0): Breaking changes
• MINOR (0.x.0): New features, backwards compatible
• PATCH (0.0.x): Bug fixes, backwards compatible

Questions?

• Open an issue: https://github.com/steveyegge/gastown/issues
• Check existing releases: https://github.com/steveyegge/gastown/releases