From 5f8d13203b9d9d7624022ba94e0408f1a94a334d Mon Sep 17 00:00:00 2001 From: gastown/crew/max Date: Fri, 2 Jan 2026 01:33:19 -0800 Subject: [PATCH] docs: Add OSS project files (CHANGELOG, linter config, release docs) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - CHANGELOG.md: Initial release notes for v0.1.0 - .golangci.yml: Linter configuration adapted from beads - RELEASING.md: Release process documentation 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- .golangci.yml | 63 +++++++++++++ CHANGELOG.md | 54 ++++++++++++ RELEASING.md | 238 ++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 355 insertions(+) create mode 100644 .golangci.yml create mode 100644 CHANGELOG.md create mode 100644 RELEASING.md diff --git a/.golangci.yml b/.golangci.yml new file mode 100644 index 00000000..3c317fdd --- /dev/null +++ b/.golangci.yml @@ -0,0 +1,63 @@ +version: "2" + +run: + timeout: 5m + tests: false + +linters: + default: 'none' + enable: + - errcheck + - gosec + - misspell + - unconvert + - unparam + + settings: + errcheck: + exclude-functions: + - (*database/sql.DB).Close + - (*database/sql.Rows).Close + - (*database/sql.Tx).Rollback + - (*database/sql.Stmt).Close + - (*database/sql.Conn).Close + - (*os.File).Close + - (os).RemoveAll + - (os).Remove + - (os).Setenv + - (os).Unsetenv + - (os).Chdir + - (os).MkdirAll + - (fmt).Sscanf + misspell: + locale: US + + exclusions: + rules: + # G304: File inclusion via variable in tests is safe (test data) + - path: '_test\.go' + linters: + - gosec + text: "G304" + # G306: File permissions 0644 in tests are acceptable (test fixtures) + - path: '_test\.go' + linters: + - gosec + text: "G306" + # G302/G306: Directory/file permissions 0700/0750 are acceptable + - linters: + - gosec + text: "G302.*0700|G301.*0750" + # G204: Safe subprocess launches with validated arguments (tmux, git, etc.) + - path: 'internal/tmux/|internal/git/|internal/cmd/' + linters: + - gosec + text: 'G204' + # errcheck: Ignore unchecked errors in test files for common cleanup patterns + - path: '_test\.go' + linters: + - errcheck + text: "Error return value of .*(Close|Rollback|RemoveAll|Setenv|Unsetenv|Chdir|MkdirAll|Remove|Write).* is not checked" + +issues: + uniq-by-line: true diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 00000000..9be108ed --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,54 @@ +# Changelog + +All notable changes to the Gas Town project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [0.1.0] - 2026-01-02 + +### Added + +Initial public release of Gas Town - a multi-agent workspace manager for Claude Code. + +#### Core Architecture +- **Town structure** - Hierarchical workspace with rigs, crews, and polecats +- **Rig management** - `gt rig add/list/remove` for project containers +- **Crew workspaces** - `gt crew add` for persistent developer workspaces +- **Polecat workers** - Transient agent workers managed by Witness + +#### Agent Roles +- **Mayor** - Global coordinator for cross-rig work +- **Deacon** - Town-level lifecycle patrol and heartbeat +- **Witness** - Per-rig polecat lifecycle manager +- **Refinery** - Merge queue processor with code review +- **Crew** - Persistent developer workspaces +- **Polecat** - Transient worker agents + +#### Work Management +- **Convoy system** - `gt convoy create/list/status` for tracking related work +- **Sling workflow** - `gt sling ` to assign work to agents +- **Hook mechanism** - Work attached to agent hooks for pickup +- **Molecule workflows** - Formula-based multi-step task execution + +#### Communication +- **Mail system** - `gt mail inbox/send/read` for agent messaging +- **Escalation protocol** - `gt escalate` with severity levels +- **Handoff mechanism** - `gt handoff` for context-preserving session cycling + +#### Integration +- **Beads integration** - Issue tracking via beads (`bd` commands) +- **Tmux sessions** - Agent sessions in tmux with theming +- **GitHub CLI** - PR creation and merge queue via `gh` + +#### Developer Experience +- **Status dashboard** - `gt status` for town overview +- **Session cycling** - `C-b n/p` to navigate between agents +- **Activity feed** - `gt feed` for real-time event stream +- **Nudge system** - `gt nudge` for reliable message delivery to sessions + +### Infrastructure +- **Daemon mode** - Background lifecycle management +- **npm package** - Cross-platform binary distribution +- **GitHub Actions** - CI/CD workflows for releases +- **GoReleaser** - Multi-platform binary builds diff --git a/RELEASING.md b/RELEASING.md new file mode 100644 index 00000000..dd728ef8 --- /dev/null +++ b/RELEASING.md @@ -0,0 +1,238 @@ +# Release Process for Gas Town + +This document describes the release process for Gas Town, including GitHub releases and npm packages. + +## Table of Contents + +- [Overview](#overview) +- [Prerequisites](#prerequisites) +- [Release Checklist](#release-checklist) +- [1. Prepare Release](#1-prepare-release) +- [2. GitHub Release](#2-github-release) +- [3. npm Package Release](#3-npm-package-release) +- [4. Verify Release](#4-verify-release) +- [Hotfix Releases](#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 + +```bash +# 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: + +```markdown +## [0.2.0] - 2026-01-15 + +### Added +- New feature X + +### Changed +- Improved Y + +### Fixed +- Bug in Z +``` + +Commit the CHANGELOG changes: + +```bash +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 + +```bash +# 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 + +```bash +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: + +```bash +# 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 + +```bash +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 + +```bash +# IMPORTANT: Ensure GitHub release with binaries is live first! +cd npm-package +npm publish --access public +``` + +### Verify npm Release + +```bash +npm install -g @gastown/gt +gt version # Should show 0.2.0 +``` + +## 4. Verify Release + +After all channels are updated: + +### GitHub + +```bash +# 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 + +```bash +npm install -g @gastown/gt +gt version +``` + +## Hotfix Releases + +For urgent bug fixes: + +```bash +# 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](https://semver.org/): + +- **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