Reissue

Automate your Ruby gem releases with proper versioning and changelog management.

Keep your version numbers and changelogs consistent and up-to-date with minimal effort.

Bottom Line Up Front

When releasing gems, you typically run rake build:checksum to build the gem and generate the checksum, then rake release to push the .gem file to rubygems.org.

With Reissue, the process remains the same, but you get automatic version bumping and changelog management included.

Also supports non-gem Ruby projects.

How It Works

The workflow:

1. Start with a version number (e.g., 0.1.0) for your unreleased project.
2. Make commits and develop features.
3. Release the version, finalizing the changelog with the release date.
4. Reissue automatically bumps to the next version (e.g., 0.1.1) and prepares the changelog for future changes.

After each release, Reissue handles the version bump and changelog updates, so you're immediately ready for the next development cycle.

Installation

Add to your application's Gemfile:

$ bundle add reissue

Or install directly:

$ gem install reissue

Usage

Gem Projects

Add to your Rakefile:

require "reissue/gem"

Reissue::Task.create :reissue do |task|
  # Required: Path to your version file
  task.version_file = "lib/my_gem/version.rb"
end

This integrates with standard gem tasks:

• rake build - Now finalizes the changelog before building
• rake release - Automatically bumps version after release

Additional tasks (usually run automatically):

• rake reissue[segment] - Bump version (major, minor, patch)
• rake reissue:finalize[date] - Add release date to changelog
• rake reissue:reformat[version_limit] - Clean up changelog formatting
• rake reissue:preview - Preview changelog entries from fragments or git trailers
• rake reissue:clear_fragments - Clear changelog fragments after release

Non-Gem Projects

For non-gem Ruby projects, add to your Rakefile:

require "reissue/rake"

Reissue::Task.create :reissue do |task|
  task.version_file = "path/to/version.rb"
end

Then use the rake tasks to manage your releases.

Configuration Options

All available configuration options:

Reissue::Task.create :reissue do |task|
  # Required: The file to update with the new version number
  task.version_file = "lib/my_gem/version.rb"
  
  # Optional: The name of the task. Defaults to "reissue"
  task.name = "reissue"
  
  # Optional: The description of the main task
  task.description = "Prepare the next version of the gem"
  
  # Optional: The changelog file to update. Defaults to "CHANGELOG.md"
  task.changelog_file = "CHANGELOG.md"
  
  # Optional: The number of versions to maintain in the changelog. Defaults to 2
  task.version_limit = 5
  
  # Optional: Whether to commit the changes automatically. Defaults to true
  task.commit = true
  
  # Optional: Whether to commit the results of the finalize task. Defaults to true
  task.commit_finalize = true
  
  # Optional: Whether to push the changes automatically. Defaults to false
  # Options: false, true (push working branch), :branch (create and push new branch)
  task.push_finalize = :branch
  
  # Optional: Configure fragment handling for changelog entries. Defaults to nil (disabled)
  # Options:
  #   - nil or false: Fragments disabled
  #   - String path: Use directory-based fragments (e.g., "changelog_fragments")
  #   - :git: Extract changelog entries from git commit trailers
  task.fragment = "changelog_fragments"
  # task.fragment = :git  # Use git trailers for changelog entries
  
  # Optional: Whether to clear fragment files after releasing. Defaults to false
  # When true, fragments are cleared after a release (only applies when using directory fragments)
  # Note: Has no effect when using :git fragments
  task.clear_fragments = true
  
  # Deprecated: Use `fragment` instead of `fragment_directory`
  # task.fragment_directory = "changelog_fragments"  # DEPRECATED: Use task.fragment instead

  # Optional: Retain changelog files for previous versions. Defaults to false
  # Options: true (retain in "changelogs" directory), "path/to/archive", or a Proc
  task.retain_changelogs = true
  # task.retain_changelogs = "path/to/archive"
  # task.retain_changelogs = ->(version, content) { # custom logic }
  
  # Optional: Custom version formatting logic. Receives a Gem::Version object and segment
  task.version_redo_proc = ->(version, segment) do
    # your special versioning logic
    version.bump
  end
end

Using Git Trailers for Changelog Entries

Reissue can extract changelog entries directly from git commit messages using trailers. This keeps your changelog data close to the code changes.

Configuration

Reissue::Task.create :reissue do |task|
  task.version_file = "lib/my_gem/version.rb"
  task.fragment = :git  # Enable git trailer extraction
end

Adding Trailers to Commits

Use changelog section names as trailer keys in your commit messages:

git commit -m "Implement user authentication

Added: User login and logout functionality
Added: Password reset via email
Fixed: Session timeout not working correctly
Security: Rate limiting on login attempts"

Supported Sections

Git trailers use the standard Keep a Changelog sections:

• Added: for new features
• Changed: for changes in existing functionality
• Deprecated: for soon-to-be removed features
• Removed: for now removed features
• Fixed: for any bug fixes
• Security: for vulnerability fixes

How It Works

1. When you run rake reissue, it finds all commits since the last version tag
2. Extracts trailers matching changelog sections from commit messages
3. Adds them to the appropriate sections in your CHANGELOG.md
4. Trailers are case-insensitive (e.g., fixed:, Fixed:, FIXED: all work)

Example Workflow

# Make your changes
git add .
git commit -m "Add export functionality

Added: CSV export for user data
Added: PDF report generation
Fixed: Date formatting in exports"

# Release (trailers are automatically extracted)
rake build:checksum
rake release

The changelog will be updated with the entries from your commit trailers.

Version Bumping with Git Trailers

When using git fragments (task.fragment = :git), you can also control version bumping through commit trailers. Add a Version: trailer to your commit messages to specify the type of version bump.

Configuration

The version bump feature is automatically enabled when using git fragments:

Reissue::Task.create :reissue do |task|
  task.version_file = "lib/my_gem/version.rb"
  task.fragment = :git  # Enables both changelog and version trailers
end

Version Trailer Syntax

Add a Version: trailer to specify the bump type:

git commit -m "Add breaking API changes

Added: New REST API endpoints
Changed: Authentication now requires API keys
Version: major"

Supported version bump types:

• Version: major - Increments major version (1.2.3 → 2.0.0)
• Version: minor - Increments minor version (1.2.3 → 1.3.0)
• Version: patch - Increments patch version (1.2.3 → 1.2.4)

Precedence Rules

When multiple commits contain Version: trailers, the highest precedence bump is applied:

Precedence: major > minor > patch

Examples:

• Commits with Version: patch and Version: minor → minor bump applied
• Commits with Version: minor and Version: major → major bump applied
• Multiple Version: major trailers → only one major bump applied

Idempotency

The version bump is idempotent - running rake build multiple times before releasing will only bump the version once:

1. First build: Version bumped from 1.2.3 → 2.0.0 (based on Version: major trailer)
2. Second build: Version bump skipped (already at 2.0.0)
3. Third build: Version bump skipped (already at 2.0.0)
4. After release: Patch bump to 2.0.1 (standard post-release behavior)

This is achieved by comparing the current version in your version file with the last git tag version. If they differ, the version was already bumped and the bump is skipped.

Example Workflow

# Make changes with a major version bump
git commit -m "Redesign authentication system

Changed: Complete overhaul of auth architecture
Removed: Support for legacy OAuth 1.0
Added: OAuth 2.0 and JWT support
Version: major"

# Build (version bumps from 1.2.3 → 2.0.0)
rake build:checksum

# Build again (version bump skipped - already at 2.0.0)
rake build:checksum

# Release (creates v2.0.0 tag and bumps to 2.0.1)
rake release

Case Insensitivity

Version trailers are case-insensitive:

• Version: major, version: major, VERSION: MAJOR all work

When to Use Version Trailers

• Breaking changes: Use Version: major for incompatible API changes
• New features: Use Version: minor for backwards-compatible new functionality
• Bug fixes: Use Version: patch for backwards-compatible bug fixes (or omit - patch is the default post-release bump)

Development

After checking out the repo, run bin/setup to install dependencies. Then run rake test to run the tests. You can also run bin/console for an interactive prompt.

Using Git Trailers for Changelog Entries

Reissue builds its changelog from git trailers. When making commits, add trailers that adhere to the Keep a Changelog format.

git commit -m "Add breaking API changes

Added: New Reissue API
Changed: API of Reissue switched from foo to bar
Version: major"

Releasing This Gem

1. Run rake build:checksum to build the gem and generate checksums
2. Run rake release to push to rubygems.org
3. The version will automatically bump and the changelog will be updated
4. Push the changes to the repository

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/SOFware/reissue.