harperreed/dotfiles / .claude/skills/releasing-software
releasing-software
VerifiedUse when preparing a release, tagging a version, or when user says "release", "tag", "ship it", "push to production" - ensures all release artifacts are verified before tagging to avoid the retag-four-times failure pattern
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.4 KB |
SKILL.md
View on GitHub---
name: releasing-software
description: Use when preparing a release, tagging a version, or when user says "release", "tag", "ship it", "push to production" - ensures all release artifacts are verified before tagging to avoid the retag-four-times failure pattern
---
# Releasing Software
## Overview
**Never tag until CI passes.** Every retag erodes trust and wastes time.
This skill prevents the "tag, watch CI fail, retag, repeat" anti-pattern by establishing a pre-flight checklist that catches issues BEFORE creating the tag.
## The Iron Law
```
NO TAG WITHOUT GREEN CI
```
Run the full verification locally. Fix everything. THEN tag. Not before.
## Pre-Release Checklist
**MANDATORY: Use TodoWrite to create todos for EACH item.**
### 1. Verify Build Paths
Check ALL places that reference your main package:
- [ ] `goreleaser.yml` - `main:` field (common: `./cmd/app` vs `.`)
- [ ] `.github/workflows/*.yml` - any `go build` commands
- [ ] `Makefile` - build targets
- [ ] `Dockerfile` - build commands
```bash
# Find all references to cmd/ or main package paths
grep -r "cmd/" . --include="*.yml" --include="*.yaml" --include="Makefile" --include="Dockerfile"
grep -r "go build" . --include="*.yml" --include="*.yaml" --include="Makefile"
```
### 2. Verify Tests Exist
Go 1.23+ coverage tool fails on packages without tests:
```bash
# Check for test files in each package
find . -name "*_test.go" | wc -l
# If zero, add placeholder tests to EVERY package
```
**Every package needs at least one test file** or CI coverage step fails with `no such tool "covdata"`.
### 3. Verify Local CI Passes
```bash
# Run what CI runs
make test # or go test ./...
make lint # or golangci-lint run
make build # verify it compiles
# If using coverage
make test-coverage
```
### 4. Verify Documentation
- [ ] README.md exists and is current
- [ ] CHANGELOG.md updated (if maintained)
- [ ] Version references updated
### 5. Verify Release Config
- [ ] goreleaser description is correct (not template leftovers)
- [ ] goreleaser homepage URL is correct
- [ ] `.gitignore` includes build artifacts, coverage files
### 6. Verify Clean Git State
```bash
git status # Nothing unexpected staged
git diff --stat # Review all changes
git log --oneline -5 # Verify recent history
```
## Release Procedure
**Only after ALL checks pass:**
```bash
# 1. Commit all changes
git add -A && git commit -m "release: prepare v0.0.X"
# 2. Wait for pre-commit hooks to pass
# If hooks fail, fix and re-commit
# 3. Push and wait for CI
git push origin main
# 4. WAIT FOR CI TO PASS - check status
gh run list --limit 2
# OR watch in browser
# 5. Only after CI is green, create tag
git tag -a v0.0.X -m "v0.0.X"
git push origin v0.0.X
# 6. Verify release workflow completes
gh run list --limit 2
```
## Red Flags - STOP
If you catch yourself doing any of these, STOP:
- Tagging before CI completes
- "CI will probably pass"
- "I'll fix it if it fails"
- Deleting and recreating tags
- Force-pushing tags
- "It's just a minor release"
**All of these mean: Wait for CI. Fix issues. Then tag.**
## Common Failures
| Symptom | Cause | Fix |
|---------|-------|-----|
| `couldn't find main file` | Wrong path in goreleaser | Set `main: .` if main.go at root |
| `no such tool "covdata"` | Package without tests | Add placeholder test to each package |
| Release succeeds but brew fails | Wrong description/homepage | Update goreleaser brews section |
| Had to retag | Tagged before CI passed | WAIT FOR GREEN CI |
| 504 errors in CI | GitHub infra issue | Retry workflow, not a code problem |
## Version Bumping
When incrementing version:
1. **Patch** (0.0.X): Bug fixes, no new features
2. **Minor** (0.X.0): New features, backwards compatible
3. **Major** (X.0.0): Breaking changes
Search codebase for version references:
```bash
grep -r "version" . --include="*.go" --include="*.yml" --include="*.json" | grep -v test | grep -v vendor
```
## Post-Release Verification
After tag is pushed:
```bash
# Watch release workflow
gh run watch
# Verify release assets
gh release view v0.0.X
# Test installation (if applicable)
go install github.com/user/repo@v0.0.X
```
## The Bottom Line
**Retagging is a symptom of rushing.**
The 5 minutes spent on pre-flight checks saves 30 minutes of retag cycles and preserves your release history integrity.
Every tag should be final. If you're deleting tags, you skipped the checklist.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |