Version: 2.0 (Modular Architecture)
Status: ✅ Production-Ready
Last Updated: 2025-11-25
Modernization: Completed (Phases 1-3)
The Zer0-Mistakes release automation system provides comprehensive, modular automation for semantic versioning, changelog generation, gem building, and publishing. The system was fully modernized in November 2025, transitioning from monolithic scripts to a modular, testable architecture.
System Requirements:
brew install bash)# Install Bash 5 on macOS (one-time)
brew install bash
export PATH="/opt/homebrew/bin:$PATH"
# Preview release
/opt/homebrew/bin/bash scripts/release patch --dry-run
# Build and test (no publish)
scripts/release patch --skip-publish --no-github-release
# Full release
/opt/homebrew/bin/bash scripts/release patch
Press Cmd+Shift+P → “Tasks: Run Task” → Choose:
The release automation is built on 6 focused libraries:
scripts/lib/
├── common.sh (165 lines) - Logging, error handling, utilities
├── validation.sh (120 lines) - Environment validation
├── version.sh (155 lines) - Version management
├── git.sh (165 lines) - Git operations
├── changelog.sh (230 lines) - Changelog generation
└── gem.sh (160 lines) - Gem build/publish
Total: 995 lines of modular, testable code
Two simplified commands provide the user interface:
scripts/
├── release (200 lines) - Complete release workflow
├── build (80 lines) - Gem building only
├── gem-publish.sh - Deprecation wrapper → release
├── release.sh - Deprecation wrapper → release
└── build.sh - Deprecation wrapper → build
Benefits:
The scripts/release command executes:
# Version Types
scripts/release patch # 0.6.0 → 0.6.1
scripts/release minor # 0.6.0 → 0.7.0
scripts/release major # 0.6.0 → 1.0.0
# Control Options
--dry-run # Preview without changes
--skip-tests # Skip test execution
--skip-publish # Skip RubyGems publishing
--no-github-release # Skip GitHub release
--non-interactive # No confirmation prompts
--help # Show usage information
Development Testing:
# 1. Preview changes
/opt/homebrew/bin/bash scripts/release patch --dry-run
# 2. Build and test locally
scripts/release patch --skip-publish --no-github-release
# 3. If all good, do full release
/opt/homebrew/bin/bash scripts/release patch
Quick Gem Build:
# Build gem without release workflow
./scripts/build
# Preview build steps
./scripts/build --dry-run
CI/CD Pipeline:
# Non-interactive release
/opt/homebrew/bin/bash scripts/release patch --non-interactive
The system automatically generates changelogs from conventional commit messages:
Commit Format:
<type>(<scope>): <subject>
<body>
<footer>
Supported Types:
feat: → Added sectionfix: → Fixed sectionrefactor: → Changed sectiondocs: → Changed sectionperf: → Changed sectiontest: → Other sectionchore: → Other sectionBREAKING CHANGE: → Breaking Changes sectionExample Commits:
feat: add responsive navigation component
fix: resolve sidebar collapse issue on mobile
docs: update installation instructions
refactor: simplify version calculation logic
The changelog generator automatically excludes:
chore: bump version)Comprehensive test coverage with 63+ assertions:
# Run all tests
./scripts/test/lib/run_tests.sh
# Test specific library
./scripts/test/lib/test_version.sh
./scripts/test/lib/test_changelog.sh
./scripts/test/lib/test_git.sh
Test Coverage:
# Test environment validation
./scripts/release --help
# Test build system
./scripts/build --dry-run
# Test full workflow (safe)
/opt/homebrew/bin/bash scripts/release patch --dry-run --non-interactive
Bash Version Error:
[ERROR] This script requires Bash 4.0 or higher (current: 3.2.57)
[INFO] On macOS, install via: brew install bash
Solution:
brew install bash
/opt/homebrew/bin/bash scripts/release patch
Working Directory Not Clean:
[ERROR] Working directory is not clean. Please commit or stash changes first.
Solution:
git status # Review changes
git add . && git commit -m "..." # Commit changes
# or
git stash # Stash temporarily
RubyGems Authentication:
[ERROR] RubyGems credentials not configured
Solution:
gem signin
# Or manually configure ~/.gem/credentials
For comprehensive troubleshooting, see: TROUBLESHOOTING.md
Old Commands:
./scripts/gem-publish.sh patch
make release-patch
New Commands:
/opt/homebrew/bin/bash scripts/release patch
# or use VS Code tasks
One-Time Setup:
brew install bash
echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
Update GitHub Actions:
jobs:
release:
runs-on: macos-latest
steps:
- uses: actions/checkout@v4
- name: Install Bash 5
run: brew install bash
- name: Release
run: /opt/homebrew/bin/bash scripts/release patch --non-interactive
env:
RUBYGEMS_API_KEY: $
| Step | Duration |
|---|---|
| Validation | 2-5 seconds |
| Version calculation | <1 second |
| Changelog generation | 5-30 seconds |
| Version updates | 1-2 seconds |
| Test suite | 10-60 seconds |
| Gem build | 5-15 seconds |
| RubyGems publish | 10-30 seconds |
| GitHub release | 5-10 seconds |
| Push changes | 2-5 seconds |
Total: 2-5 minutes for complete release
Issue: Changelog generation may exit prematurely during commit processing loop.
Impact: Changelog automation incomplete
Workaround:
scripts/build for gem buildingStatus: Documented, tracked for v0.7.0
scripts/lib/)Example:
# Add function to scripts/lib/version.sh
validate_version_format() {
local version="$1"
[[ "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]
}
# Add test to scripts/test/lib/test_version.sh
test_validate_version_format() {
assert_success validate_version_format "1.2.3"
assert_failure validate_version_format "1.2"
}
Each library includes:
Phase 1: Library Extraction (Completed 2025-11-25)
Phase 2: Simplified Commands (Completed 2025-11-25)
scripts/release and scripts/build commandsPhase 3: Documentation & Testing (Completed 2025-11-25)
Code Quality:
Testing:
Developer Experience:
Open an issue at: https://github.com/bamr87/zer0-mistakes/issues/new
Include:
bash --version)git status)Last Updated: 2025-11-25
System Version: 2.0 (Modular Architecture)
Status: Production-Ready
Maintainer: bamr87