🚀 Bumper

🚀 A magical release management system with beautiful changelogs and automated workflows

Bumper is a modern, developer-friendly tool that automates your entire release process. From conventional commit validation to beautiful changelog generation, automated version bumping, and seamless GitHub releases - it handles everything with style.

✨ Features

🚀 Core Release Management

• Automated Releases - One command creates tags, changelogs, and GitHub releases
• Smart Versioning - Automatic patch/minor/major version bumping
• Beautiful Changelogs - Auto-generated with emojis and smart categorization
• NPM Publishing - Seamless package publishing with authentication

🔍 Commit Management

• Commit Validation - Enforces conventional commit standards
• Interactive Commits - Guided commit message creation
• Commit Suggestions - AI-powered commit message improvements
• Git Hooks - Pre-commit validation with Husky

🏷️ GitHub Integration

• Auto-Labeling - Automatically label PRs based on commit messages
• Release Readiness - Validate releases based on GitHub labels and requirements
• Enhanced Changelogs - Group changelog entries by labels for better organization
• Workflow Automation - GitHub Actions for seamless integration

🎯 Developer Experience

• Zero Configuration - Works out of the box with sensible defaults
• Beautiful UX - Colorful output with spinners and progress indicators
• Platform Agnostic - Works with any Git-based project
• Flexible Configuration - Customize everything via bumper.config.json

🚀 Quick Start

1. Install Bumper

Recommended: Per-Project Installation

npm install --save-dev bumper-cli

Alternative: Global Installation

npm install -g bumper-cli

2. Setup Your Project

# Initialize bumper in your project
bumper setup
# or if installed locally:
npx bumper setup

This will:

• ✅ Install necessary dependencies (@commitlint/cli, husky)
• ✅ Create conventional commit validation rules
• ✅ Set up Git hooks with Husky
• ✅ Create GitHub Actions workflow
• ✅ Add convenient NPM scripts to your package.json
• ✅ Generate initial changelog

3. Make Your First Release

# Preview what your release will look like
npm run changelog:preview

# Create a patch release
npm run release:patch

🔄 Legacy Project Migration

If you have an existing project that doesn't follow conventional commit format, bumper provides powerful tools to help you migrate. You can choose between invasive migration (rewriting history) or non-invasive migration (drawing a line in the sand).

🏖️ Non-Invasive: Line in the Sand (Recommended)

The safest approach is to draw a line in the sand and start fresh with conventional commits from a specific point forward:

# Start using conventional commits from now on
bumper line-in-sand

# Start from a specific date
bumper line-in-sand --start-date 2024-01-01

# Start from a specific commit
bumper line-in-sand --start-commit abc12345

# Start from a specific tag
bumper line-in-sand --tag v1.0.0

Benefits:

• ✅ No git history rewriting - completely safe
• ✅ Immediate setup - start using conventional commits right away
• ✅ Team friendly - no coordination needed
• ✅ Gradual adoption - legacy commits remain unchanged
• ✅ Changelog support - works with mixed commit formats

What happens:

• Sets up conventional commit infrastructure
• Creates a marker file and git tag to track the start point
• All new commits from that point forward use conventional format
• Legacy commits remain unchanged but are still included in changelogs
• Commit validation is active for new commits only

🔧 Invasive: Full Migration

For projects that want to convert all existing commits to conventional format:

1. Analyze Your Current State

# Analyze commit patterns in your project
bumper analyze-legacy

# Analyze specific commit range
bumper analyze-legacy --range HEAD~100..HEAD

# Save analysis to file
bumper analyze-legacy --output analysis.json

This will show you:

• 📊 Commit statistics and migration rate
• 📋 Common commit patterns and suggested types
• 💡 Recommended migration strategy
• 🎯 Next steps for your project

2. Migrate Your Project

# Migrate project to conventional commits
bumper migrate-legacy

# Force migration even if already set up
bumper migrate-legacy --force

# Migrate commits from a specific date
bumper migrate-legacy --start-date 2024-01-01

This will:

• ✅ Install conventional commit dependencies
• ✅ Set up commitlint and husky hooks
• ✅ Add convenient npm scripts
• ✅ Configure validation rules

3. Bulk Format Legacy Commits

# Preview bulk formatting
bumper bulk-format --dry-run

# Format commits in a specific range
bumper bulk-format --range HEAD~50..HEAD

# Apply formatting (rewrites git history)
bumper bulk-format

⚠️ Warning: Bulk formatting rewrites git history. Always backup your repository first!

4. Gradual Migration Strategy

For large projects, consider a gradual approach:

1. Start with new commits using bumper commit or bumper suggest
2. Format recent commits with bumper bulk-format --range HEAD~20..HEAD
3. Analyze progress with bumper analyze-legacy
4. Repeat until migration is complete

Migration Strategies

Bumper automatically suggests the best migration strategy:

• Line in the Sand: Recommended - Start fresh from a specific point (non-invasive)
• Bulk: For projects with < 50 legacy commits (invasive)
• Hybrid: For projects with mixed conventional/legacy commits (invasive)
• Gradual: For large projects with > 100 legacy commits (invasive)

When to Use Each Approach

| Approach | Best For | Risk Level | Team Coordination | |----------|----------|------------|-------------------| | Line in the Sand | Most projects | 🟢 None | None needed | | Bulk | Small projects, solo developers | 🟡 Medium | Minimal | | Gradual | Large projects, teams | 🟡 Medium | Moderate | | Hybrid | Mixed commit history | 🟡 Medium | Moderate |

📖 Usage Guide

🎯 Installation Methods

| Method | Install Command | Usage Command | Works In | Best For | |--------|----------------|---------------|----------|----------| | Per-Project | npm install --save-dev bumper-cli | npm run <script> | Project directory only | Teams, production projects | | Global | npm install -g bumper-cli | bumper <command> | Any directory | CLI tools, personal use |

🔍 CLI Commands Reference

# Preview your next release
bumper preview

# Validate commit messages
bumper validate

# Generate changelog
bumper generate

# Create a release
bumper release <type> [--dry-run]
# Types: patch, minor, major

# Setup project (adds convenience scripts)
bumper setup

# Suggest commit format
bumper suggest "your message"

# Interactive commit creation
bumper commit

# GitHub integration
bumper setup-github
bumper check-release-readiness
bumper auto-label <pr-number>

# Legacy project migration
bumper line-in-sand [--start-date <date>] [--start-commit <commit>] [--tag <tag>] [--force]
bumper analyze-legacy [--range <range>] [--output <file>]
bumper migrate-legacy [--force] [--start-date <date>]
bumper bulk-format [--range <range>] [--dry-run]

📦 NPM Scripts (After Setup)

After running bumper setup, these convenience scripts are added to your package.json:

{
  "scripts": {
    "validate:commits": "bumper validate",
    "changelog:preview": "bumper preview",
    "changelog:generate": "bumper generate",
    "release:patch": "bumper release patch",
    "release:minor": "bumper release minor",
    "release:major": "bumper release major",
    "release:dry-run": "bumper release patch --dry-run",
    "commit:suggest": "bumper suggest",
    "commit:create": "bumper commit",
    "github:setup": "bumper setup-github",
    "github:check": "bumper check-release-readiness",
    "github:label": "bumper auto-label",
    "legacy:analyze": "bumper analyze-legacy",
    "legacy:migrate": "bumper migrate-legacy",
    "legacy:format": "bumper bulk-format",
    "legacy:line-in-sand": "bumper line-in-sand"
  }
}

Usage:

# Convenience scripts (recommended)
npm run changelog:preview
npm run release:patch
npm run validate:commits
npm run commit:suggest "add login feature"
npm run commit:create
npm run github:check
npm run github:label 123

🏷️ GitHub Integration

Bumper's GitHub integration provides auto-labeling, release validation, and enhanced changelogs to streamline your workflow.

🚀 Quick Setup

# Setup GitHub integration (requires GitHub CLI)
bumper setup-github

Creates:

• bumper.config.json - Configuration file
• .github/workflows/auto-label.yml - Auto-labeling workflow
• Documentation and next steps

🏷️ Auto-Labeling PRs

Command: bumper auto-label <pr-number>

What it does: Analyzes commit messages in a PR and adds appropriate labels.

Default mappings:

• feat → enhancement
• fix → bug
• security → security
• docs → documentation

Example:

# PR #123 has commits: "feat: add login" and "fix: auth bug"
bumper auto-label 123
# Result: Adds "enhancement" and "bug" labels

Automation: The GitHub Actions workflow automatically labels PRs when they're opened or updated.

🔍 Release Readiness Validation

Command: bumper check-release-readiness

What it checks:

• ✅ No blocking labels on PRs since last release
• ✅ Required labels present (if configured)
• ✅ All PRs properly labeled
• ⚠️ Status checks (if configured)

Example output:

🔍 Checking release readiness...

❌ Release is not ready:
  • PR #123 has blocking label: do-not-release
  • PR #124 missing required label (ready-for-release)

📋 PRs since last release:
  • #123: Add new login feature [enhancement, do-not-release]
  • #124: Fix authentication bug [bug]

🏷️ Auto-Labeling

Automatically label PRs based on commit messages:

# Label a specific PR
bumper auto-label 123

# Or use the GitHub Actions workflow (automatic)

Default mappings:

• feat → enhancement
• fix → bug
• security → security
• docs → documentation

⚙️ Configuration

File: bumper.config.json (created by bumper setup-github)

Key sections:

Release Requirements:

{
  "releaseRequirements": {
    "requiredLabels": ["ready-for-release", "qa-approved"],
    "blockingLabels": ["do-not-release", "wip", "block-release"],
    "requiredStatusChecks": ["ci", "test"]
  }
}

Auto-Labeling:

{
  "autoLabel": {
    "enabled": true,
    "mappings": {
      "feat": ["enhancement"],
      "fix": ["bug"],
      "security": ["security"],
      "docs": ["documentation"]
    }
  }
}

Enhanced Changelogs:

{
  "changelog": {
    "groupByLabels": true,
    "labelGroups": {
      "🚀 High Priority": ["high-priority", "critical"],
      "💥 Breaking Changes": ["breaking-change"],
      "🎨 User Facing": ["user-facing", "ui", "ux"]
    }
  }
}

Enhanced changelog example:

## [1.5.7] - 2024-01-01

### 🚀 High Priority
- feat: add critical security feature (abc123)

### 🎨 User Facing
- feat: improve login UI (def456)

### 🔧 Internal
- refactor: optimize performance (ghi789)

🎯 Best Practices

1. Essential Labels

gh label create "ready-for-release" --color "28a745"
gh label create "do-not-release" --color "dc3545"
gh label create "qa-approved" --color "17a2b8"
gh label create "enhancement" --color "0075ca"
gh label create "bug" --color "d73a4a"

2. Team Workflow

# 1. Developer creates PR → Auto-labeling adds initial labels
# 2. QA reviews → Adds "qa-approved" label  
# 3. Before release → Run "bumper check-release-readiness"
# 4. If ready → Create release
# 5. If not ready → Fix issues (remove blocking labels, add required labels)

3. Always validate before releasing

bumper check-release-readiness
npm run release:patch

✨ Commit Formatting & Suggestions

Bumper helps you write beautiful, conventional commit messages!

Suggest a Commit Format

Use the suggest command to get a conventional commit suggestion and improvement tips:

bumper suggest "add login button to UI"

Output:

💡 Commit Message Suggestions

Original: add login button to UI
Suggested: feat(ui): Add login button to ui

Improvements:
  • Convert to conventional commit format
  • Use scope for clarity

Type: feat
Scope: ui

Interactive Commit Creation

Use the commit command for an interactive prompt to generate a conventional commit message:

bumper commit

You'll be guided through:

1. Commit Type - feat, fix, docs, etc.
2. Scope - optional component/module name
3. Breaking Change - whether this is a breaking change
4. Description - clear, concise description

Then copy the generated message into your git commit -m command.

🎯 Conventional Commits

Bumper follows the Conventional Commits specification:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Supported Types

| Type | Emoji | Description | | ---------- | ----- | ------------------------ | | feat | ✨ | New features | | fix | 🐛 | Bug fixes | | docs | 📚 | Documentation | | style | 💄 | Code style changes | | refactor | ♻️ | Code refactoring | | perf | ⚡ | Performance improvements | | test | ✅ | Adding tests | | build | 📦 | Build system changes | | ci | 🔧 | CI/CD changes | | chore | 🔨 | Maintenance tasks | | revert | ⏪ | Reverting changes | | security | 🔒 | Security fixes |

Examples

# Feature
git commit -m "feat: add user authentication"

# Bug fix
git commit -m "fix: resolve login timeout issue"

# Breaking change
git commit -m "feat!: change API response format"

# With scope
git commit -m "feat(auth): add OAuth2 support"

📋 Changelog Generation

Bumper automatically generates beautiful changelogs with:

• 📊 Smart Categorization - Groups commits by type with emojis
• ⚠️ Breaking Changes - Highlights breaking changes prominently
• 👥 Contributors - Credits all contributors
• 🎨 Beautiful Formatting - Clean, readable output

Example Output

## [1.2.0] - 2024-01-15 (MINOR RELEASE)

### ⚠️ BREAKING CHANGES

- **auth:** change login endpoint response format (a1b2c3d4)

### ✨ Features

- **auth:** add OAuth2 support (e5f6g7h8)
- **ui:** implement dark mode toggle (i9j0k1l2)

### 🐛 Bug Fixes

- **api:** fix pagination bug (m3n4o5p6)
- **ui:** resolve mobile layout issues (q7r8s9t0)

### 👥 Contributors

Thanks to John Doe, Jane Smith for contributing to this release!

💡 Best Practices

🎯 Commit Message Best Practices

1. Use Bumper's Tools

   # Always check your commit message first
   bumper suggest "your message"
      
   # For complex commits, use interactive mode
   bumper commit

2. Follow Conventional Commits

   • Use lowercase for type and scope: feat(auth): add login
   • Keep description under 72 characters
   • Use imperative mood: "add" not "added"
   • Don't end with a period

3. Choose the Right Type

   • feat: New functionality
   • fix: Bug fixes
   • docs: Documentation changes
   • style: Formatting, missing semicolons, etc.
   • refactor: Code changes that neither fix bugs nor add features
   • perf: Performance improvements
   • test: Adding or updating tests
   • chore: Maintenance tasks

4. Use Scopes Wisely

   # Good - specific scope
   feat(auth): add OAuth2 support
   fix(api): resolve pagination bug
      
   # Avoid - too broad
   feat: add new feature
   fix: fix bug

5. Handle Breaking Changes

   # Breaking change in type
   feat!: change API response format
      
   # Breaking change in body
   feat: change API response format
      
   BREAKING CHANGE: This changes the API response format

🚀 Release Management Best Practices

1. Start Small

   # Always preview before releasing
   npm run changelog:preview
      
   # Use dry-run for testing
   npm run release:dry-run

2. Choose the Right Version

   • patch: Bug fixes and minor improvements
   • minor: New features (backward compatible)
   • major: Breaking changes

3. Keep a Clean History

   # Validate commits before releasing
   npm run validate:commits
      
   # Fix any issues before proceeding
   git commit --amend -m "feat: correct commit message"

4. Automate Everything

   • Use the provided GitHub Actions workflow
   • Let bumper handle versioning and changelog generation
   • Automate NPM publishing

🏗️ Project Setup Best Practices

1. Install Per-Project

   # Recommended for teams
   npm install --save-dev bumper-cli

2. Run Setup Early

   # Set up bumper at the start of your project
   bumper setup

3. Use NPM Scripts

   # Use the convenience scripts
   npm run changelog:preview
   npm run release:patch

4. Configure Your Team

   • Share the conventional commits specification
   • Use bumper's commit formatting tools
   • Establish release workflows

🔧 Development Workflow

1. Daily Development

   # Write your code
   git add .
      
   # Format your commit message
   bumper suggest "add user authentication"
   # or
   bumper commit
      
   # Commit with the suggested message
   git commit -m "feat(auth): add user authentication"

2. Before Releasing

   # Validate all commits
   npm run validate:commits
      
   # Preview the release
   npm run changelog:preview
      
   # Create the release
   npm run release:patch

3. After Releasing

   • Review the generated changelog
   • Check the GitHub release
   • Verify NPM package is published

🚨 Common Mistakes to Avoid

1. Don't Skip Validation

   # ❌ Don't release without validating
   npm run release:patch
      
   # ✅ Always validate first
   npm run validate:commits
   npm run release:patch

2. Don't Ignore Commit Messages

   # ❌ Poor commit message
   git commit -m "fix stuff"
      
   # ✅ Good commit message
   git commit -m "fix(auth): resolve login timeout issue"

3. Don't Skip Previews

   # ❌ Don't release blind
   npm run release:patch
      
   # ✅ Always preview first
   npm run changelog:preview
   npm run release:patch

🔧 Configuration

Commitlint Configuration

The setup creates a commitlint.config.js file:

module.exports = {
  rules: {
    'type-enum': [
      2,
      'always',
      [
        'feat',
        'fix',
        'docs',
        'style',
        'refactor',
        'perf',
        'test',
        'build',
        'ci',
        'chore',
        'revert',
        'security',
      ],
    ],
    'type-case': [2, 'always', 'lowerCase'],
    'type-empty': [2, 'never'],
    'subject-case': [2, 'always', 'lowerCase'],
    'subject-empty': [2, 'never'],
    'subject-full-stop': [2, 'never', '.'],
    'header-max-length': [2, 'always', 72],
  },
};

GitHub Actions Workflow

Automatically creates .github/workflows/release.yml for automated releases.

🎪 API Reference

Programmatic Usage

import {
  generateChangelog,
  validateCommits,
  createRelease,
  formatCommitMessage,
  suggestCommitFormat,
} from 'bumper-cli';

// Generate changelog
await generateChangelog({ preview: true });

// Validate commits
const result = await validateCommits();

// Create release
const release = await createRelease({
  type: 'patch',
  dryRun: true,
});

// Format commit message
const formatted = formatCommitMessage('add login feature', 'feat', 'auth');

// Suggest commit format
const suggestion = suggestCommitFormat('fix login bug');

Types

interface Commit {
  hash: string;
  type: string;
  scope?: string;
  subject: string;
  breaking?: boolean;
  author: string;
  date: string;
}

interface ReleaseResult {
  success: boolean;
  version: string;
  tag: string;
  changelog: string;
}

interface CommitSuggestion {
  original: string;
  suggested: string;
  type: string;
  scope?: string;
  breaking: boolean;
  improvements: string[];
}

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feat/amazing-feature
3. Commit your changes: git commit -m 'feat: add amazing feature'
4. Push to the branch: git push origin feat/amazing-feature
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Conventional Commits for the commit specification
• Keep a Changelog for the changelog format
• Husky for Git hooks
• Commitlint for commit validation

Made with ❤️ by developers, for developers.