reissue 0.4.0 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9ec9aad4eae0a3eaf769c1ae42cc58ca21ad704ff0b82697782fc882600902e7
-  data.tar.gz: d98907cd5df4104320b6793caafe4d33333be534c253172b7b6bb7090ff2504e
+  metadata.gz: 58c406237f6e7ef96ad4a4e1ed1aa2ba3e4cb10145edd6d44bff791a8e37d5be
+  data.tar.gz: 26b103713df3d7de9c1f9af49df079a2e9954b9b7e96a58bc8e3e203607e531d
 SHA512:
-  metadata.gz: 16072744735112068c9b5a4475d2d6d917fad5ffa82772ea59989380f85672a32fe4c6b226cb8db00eef74b7dd1bf328c23f4f60cef42228eb79058cb3f29568
-  data.tar.gz: 5554eec13624f10d14bc59fd2b2428f7a1e5803d3a0af15c90810d62490dc8875eba2d57eb8966ec88dd900607dc14c83ae967dba9fb2f658c1e0d3df05724b3
+  metadata.gz: 01d186d7b5f87e5c3ef2be402eb758971ff4dec3626d2e2aed8d67d5fd6418d064687682176b509b038b39710e8c313279047e807e42d927c902e4b5bbee649e
+  data.tar.gz: 63d5c29928e104484ce0f1c5ce6ef101a8909ed8727ae441c3a5bb81c9aaf6ecbfb46b7f4af69540f6665fc71ea8e9f9a73d1ea928371d3f8fb7a84b7077198c

data/CHANGELOG.md

@@ -5,20 +5,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
-## [0.4.0] - 2025-05-08
+## [0.4.2] - 2025-09-16
 
 ### Changed
 
-- Update reformat task to create a new changelog if it doesn't exist
+- New version was never created after the last release.
 
-## [0.3.4] - Unreleased
+## [0.4.2] - 2025-09-16
 
-## [0.3.3] - 2025-01-17
-
-### Added
-
-- CODEOWNERS file
-
-### Fixed
+### Changed
 
-- Properly retain changelog on `reissue:finalize`
+- New version was never created after the last release.

data/README.md

@@ -1,142 +1,211 @@
 # Reissue
 
-Prepare the releases of your Ruby gems with ease.
+Automate your Ruby gem releases with proper versioning and changelog management.
 
-When creating versioned software, it is important to keep track of the changes and the versions that are released.
+Keep your version numbers and changelogs consistent and up-to-date with minimal effort.
 
-After each release of a gem, you should immediatly bump the version with a new number and update the changelog with a place
-to capture the information about new changes.
+## Bottom Line Up Front
 
-Reissue helps you to prepare the next version of your project by providing tools which will update version numbers and
-update the changelog with a new version and a date.
+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](https://rubygems.org).
 
-Use Reissue to prepare your first commit going into the new version.
+With Reissue, the process remains the same, but you get automatic version bumping and changelog management included.
 
-Standard procedure for releasing projects with Reissue:
+Also supports non-gem Ruby projects.
 
-1. Create a version with some number like 0.1.0.
-2. Add commits to the project. These will be associated with the version 0.1.0.
-3. When you are releasing your project, finalize it by running
-  `rake reissue:finalize` to update the Unreleased version in your changelog.
-4. Bump the version to 0.1.1 with `rake reissue[patch]` and commit those changes.
-   Future commits will be associated with the version 0.1.1 until your next release.
+## 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
 
-Install the gem and add to the application's Gemfile by executing:
+Add to your application's Gemfile:
 
     $ bundle add reissue
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+Or install directly:
 
     $ gem install reissue
 
 ## Usage
 
-If you are working with a gem, you can add the following to the Rakefile:
+### Gem Projects
+
+Add to your Rakefile:
 
 ```ruby
 require "reissue/gem"
 
 Reissue::Task.create :reissue do |task|
-  # Required: The file to update with the new version number.
+  # Required: Path to your version file
   task.version_file = "lib/my_gem/version.rb"
 end
 ```
 
-This will add the following rake tasks:
-
-- `rake reissue[segment]` - Prepare a new version for future work for the given
-  version segment.
-- `rake reissue:finalize[date]` - Update the CHANGELOG.md file with a date for
-  the latest version.
-- `rake reissue:reformat[version_limit]` - Reformat the CHANGELOG.md file and
-  optionally limit the number of versions to maintain.
-- `rake reissue:branch[branch-name]` - Create a new branch for the next version.
-  Controlled by the `push_finalize` and `commit_finalize` options.
-- `rake reissue:push` - Push the changes to the remote repository. Controlled
-  by the `push_finalize` and `commit_finalize` options.
+This integrates with standard gem tasks:
+- `rake build` - Now finalizes the changelog before building
+- `rake release` - Automatically bumps version after release
 
-This will also update the `build` task from rubygems to first run
-`reissue:finalize` and then build the gem, ensuring that your changelog is
-up-to-date before the gem is built.
+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
 
-It updates the `release` task from rubygems to run `reissue` after the gem is
-pushed to rubygems.
+### Non-Gem Projects
 
-Build your own release with rake tasks provided by the gem.
-
-Add the following to the Rakefile:
+For non-gem Ruby projects, add to your Rakefile:
 
 ```ruby
 require "reissue/rake"
 
 Reissue::Task.create :reissue do |task|
-  # Required: The file to update with the new version number.
   task.version_file = "path/to/version.rb"
 end
 ```
 
-When creating your task, you have additional options to customize the behavior:
-
-```ruby
-require "reissue/rake"
-
-Reissue::Task.create :your_name_and_namespace do |task|
+Then use the rake tasks to manage your releases.
 
-  # Optional: The name of the task. Defaults to "reissue".
-  task.name = "your_name_and_namespace"
+### Configuration Options
 
-  # Optional: The description of the main task.
-  task.description = "Prepare the next version of the gem."
+All available configuration options:
 
-  # Required: The file to update with the new version number.
-  task.version_file = "path/to/version.rb"
-
-  # Optional: The number of versions to maintain in the changelog. Defaults to 2.
+```ruby
+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: A Proc to format the version number. Receives a Gem::Version object, and segment.
+  
+  # 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
+```
 
-  # Optional: The file to update with the new version number. Defaults to "CHANGELOG.md".
-  task.changelog_file = "path/to/CHANGELOG.md"
-
-  # Optional: A Boolean, String, or Proc to retain the changelog files for the previous versions. Defaults to false.
-  # Setting to true will retain the changelog files in the "changelogs" directory.
-  # Setting to a String will use that path as the directory to retain the changelog files.
-  # The Proc receives a version hash and the changelog content.
-  task.retain_changelogs = ->(version, content) do
-    # your special retention logic
-  end
-  # or task.retain_changelogs = "path/to/changelogs"
-  # or task.retain_changelogs = true
+## Using Git Trailers for Changelog Entries
 
-  # Optional: Whether to commit the changes automatically. Defaults to true.
-  task.commit = false
+Reissue can extract changelog entries directly from git commit messages using trailers. This keeps your changelog data close to the code changes.
 
-  # Optional: Whether or not to commit the results of the finalize task. Defaults to true.
-  task.commit_finalize = false
+### Configuration
 
-  # Optional: Whether to push the changes automatically. Defaults to false.
-  task.push_finalize = :branch # or false, or true to push the working branch
+```ruby
+Reissue::Task.create :reissue do |task|
+  task.version_file = "lib/my_gem/version.rb"
+  task.fragment = :git  # Enable git trailer extraction
 end
 ```
 
-## Development
+### Adding Trailers to Commits
+
+Use changelog section names as trailer keys in your commit messages:
+
+```bash
+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
 
-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 that will allow you to experiment.
+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
 
-## Releasing
+### 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
+
+```bash
+# 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.
+
+## Development
 
-Run `rake build:checksum` to build the gem and generate the checksum. This will also update the version number in the gemspec file.
+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.
 
-Run `rake release` to create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+## Releasing This Gem
 
-This will leave a new commit with the version number incremented in the version file and the changelog updated with the new version.
-Push the changes to the repository.
+1. Run `rake build:checksum` to build the gem and generate checksums
+2. Run `rake release` to push to [rubygems.org](https://rubygems.org)
+3. The version will automatically bump and the changelog will be updated
+4. Push the changes to the repository
 
 ## Contributing
 

data/Rakefile

@@ -16,5 +16,7 @@ require_relative "lib/reissue/gem"
 
 Reissue::Task.create :reissue do |task|
   task.version_file = "lib/reissue/version.rb"
+  task.fragment = :git  # Use git trailers for changelog entries
   task.push_finalize = :branch
+  # Note: clear_fragments has no effect with :git
 end

data/lib/reissue/changelog_updater.rb

@@ -1,5 +1,6 @@
 require_relative "parser"
 require_relative "printer"
+require_relative "fragment_handler"
 
 module Reissue
   # Updates the changelog file with new versions and changes.
@@ -18,9 +19,18 @@ module Reissue
     # @param changes [Hash] The changes for the version (default: {}).
     # @param changelog_file [String] The path to the changelog file (default: @changelog_file).
     # @param version_limit [Integer] The number of versions to keep (default: 2).
-    def call(version, date: "Unreleased", changes: {}, changelog_file: @changelog_file, version_limit: 2, retain_changelogs: false)
-      update(version, date:, changes:, version_limit:)
+    # @param fragment [String] The fragment source configuration (default: nil).
+    # @param fragment_directory [String] @deprecated Use fragment instead
+    def call(version, date: "Unreleased", changes: {}, changelog_file: @changelog_file, version_limit: 2, retain_changelogs: false, fragment: nil, fragment_directory: nil)
+      # Handle deprecation
+      if fragment_directory && !fragment
+        warn "[DEPRECATION] `fragment_directory` parameter is deprecated. Please use `fragment` instead."
+        fragment = fragment_directory
+      end
+
+      update(version, date:, changes:, version_limit:, fragment:)
       write(changelog_file, retain_changelogs:)
+
       changelog
     end
 
@@ -45,11 +55,23 @@ module Reissue
     # @param date [String] The release date (default: "Unreleased").
     # @param changes [Hash] The changes for the version (default: {}).
     # @param version_limit [Integer] The number of versions to keep (default: 2).
+    # @param fragment [String] The fragment source configuration (default: nil).
     # @return [Hash] The updated changelog.
-    def update(version, date: "Unreleased", changes: {}, version_limit: 2)
+    def update(version, date: "Unreleased", changes: {}, version_limit: 2, fragment: nil)
       @changelog = Parser.parse(File.read(@changelog_file))
 
-      changelog["versions"].unshift({"version" => version, "date" => date, "changes" => changes})
+      # Merge fragment changes if source is provided
+      merged_changes = changes.dup
+      if fragment
+        handler = FragmentHandler.for(fragment)
+        fragment_changes = handler.read
+        fragment_changes.each do |section, entries|
+          merged_changes[section] ||= []
+          merged_changes[section].concat(entries)
+        end
+      end
+
+      changelog["versions"].unshift({"version" => version, "date" => date, "changes" => merged_changes})
       changelog["versions"] = changelog["versions"].first(version_limit)
       changelog
     end

data/lib/reissue/fragment_handler/directory_fragment_handler.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Reissue
+  # Handler for reading fragments from a directory
+  class DirectoryFragmentHandler < FragmentHandler
+    DEFAULT_VALID_SECTIONS = %w[added changed deprecated removed fixed security].freeze
+
+    attr_reader :directory, :valid_sections
+
+    # Initialize the handler with a directory path
+    #
+    # @param directory [String] The path to the fragments directory
+    # @param valid_sections [Array<String>, nil] List of valid section names, or nil to allow all
+    def initialize(directory, valid_sections: DEFAULT_VALID_SECTIONS)
+      @directory = directory
+      @fragment_directory = Pathname.new(directory)
+      @valid_sections = valid_sections
+    end
+
+    # Read fragments from the directory
+    #
+    # @return [Hash] A hash of changelog entries organized by category
+    def read
+      return {} unless @fragment_directory.exist?
+
+      fragments = {}
+
+      @fragment_directory.glob("*.*.md").each do |fragment_file|
+        filename = fragment_file.basename.to_s
+        parts = filename.split(".")
+
+        next unless parts.length == 3
+
+        section = parts[1].downcase
+        next unless valid_section?(section)
+
+        content = fragment_file.read.strip
+        next if content.empty?
+
+        # Capitalize section name for changelog format
+        section_key = section.capitalize
+        fragments[section_key] ||= []
+        fragments[section_key] << content
+      end
+
+      fragments
+    end
+
+    # Clear all fragment files from the directory
+    #
+    # @return [nil]
+    def clear
+      return unless @fragment_directory.exist?
+
+      @fragment_directory.glob("*.*.md").each(&:delete)
+    end
+
+    private
+
+    def valid_section?(section)
+      return true if @valid_sections.nil?
+      return false unless @valid_sections.is_a?(Array)
+
+      @valid_sections.map(&:downcase).include?(section.downcase)
+    end
+  end
+end

data/lib/reissue/fragment_handler/git_fragment_handler.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Reissue
+  class FragmentHandler
+    # Handles reading changelog entries from git commit trailers
+    class GitFragmentHandler < FragmentHandler
+      # Regex to match changelog section trailers in commit messages
+      TRAILER_REGEX = /^(Added|Changed|Deprecated|Removed|Fixed|Security):\s*(.+)$/i
+
+      # Valid changelog sections that can be used as trailers
+      VALID_SECTIONS = %w[Added Changed Deprecated Removed Fixed Security].freeze
+
+      # Read changelog entries from git commit trailers
+      #
+      # @return [Hash] A hash of changelog entries organized by section
+      def read
+        return {} unless git_available? && in_git_repo?
+
+        commits = commits_since_last_tag
+        parse_trailers_from_commits(commits)
+      end
+
+      # Clear operation is a no-op for git trailers
+      #
+      # @return [nil]
+      def clear
+        nil
+      end
+
+      private
+
+      def git_available?
+        system("git --version", out: File::NULL, err: File::NULL)
+      end
+
+      def in_git_repo?
+        system("git rev-parse --git-dir", out: File::NULL, err: File::NULL)
+      end
+
+      def commits_since_last_tag
+        last_tag = find_last_tag
+
+        commit_range = if last_tag
+          # Get commits since the last tag
+          "#{last_tag}..HEAD"
+        else
+          # No tags found, get all commits
+          "HEAD"
+        end
+
+        # Get commit messages with trailers, in reverse order (oldest first)
+        output = `git log #{commit_range} --reverse --format=%B 2>/dev/null`
+        return [] if output.empty?
+
+        # Split by double newline to separate commits
+        output.split(/\n\n+/)
+      end
+
+      def find_last_tag
+        # Try to find the most recent tag
+        tag = `git describe --tags --abbrev=0 2>/dev/null`.strip
+        tag.empty? ? nil : tag
+      end
+
+      def parse_trailers_from_commits(commits)
+        result = {}
+
+        commits.each do |commit|
+          # Split commit into lines and look for trailers
+          commit.lines.each do |line|
+            line = line.strip
+            next if line.empty?
+
+            if (match = line.match(TRAILER_REGEX))
+              section_name = normalize_section_name(match[1])
+              trailer_value = match[2].strip
+
+              result[section_name] ||= []
+              result[section_name] << trailer_value
+            end
+          end
+        end
+
+        result
+      end
+
+      def normalize_section_name(name)
+        # Normalize to proper case (e.g., "FIXED" -> "Fixed", "added" -> "Added")
+        name.capitalize
+      end
+    end
+  end
+end

data/lib/reissue/fragment_handler/null_fragment_handler.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Reissue
+  # Handler for when no fragment source is configured
+  class NullFragmentHandler < FragmentHandler
+    # Read fragments (returns empty hash since no source is configured)
+    #
+    # @return [Hash] An empty hash
+    def read
+      {}
+    end
+
+    # Clear fragments (no-op since no source is configured)
+    #
+    # @return [nil]
+    def clear
+      nil
+    end
+  end
+end

data/lib/reissue/fragment_handler.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Reissue
+  # Base class for handling fragment reading from various sources
+  class FragmentHandler
+    # Read fragments from the configured source
+    #
+    # @return [Hash] A hash of changelog entries organized by category
+    # @raise [NotImplementedError] Must be implemented by subclasses
+    def read
+      raise NotImplementedError, "Subclasses must implement #read"
+    end
+
+    # Clear fragments from the configured source
+    #
+    # @raise [NotImplementedError] Must be implemented by subclasses
+    def clear
+      raise NotImplementedError, "Subclasses must implement #clear"
+    end
+
+    # Factory method to create the appropriate handler for the given option
+    #
+    # @param fragment_option [nil, String, Symbol] The fragment configuration
+    # @param valid_sections [Array<String>, nil] List of valid section names (for directory handler)
+    # @return [FragmentHandler] The appropriate handler instance
+    # @raise [ArgumentError] If the option is not supported
+    def self.for(fragment_option, valid_sections: nil)
+      case fragment_option
+      when nil
+        require_relative "fragment_handler/null_fragment_handler"
+        NullFragmentHandler.new
+      when String
+        require_relative "fragment_handler/directory_fragment_handler"
+        options = {}
+        options[:valid_sections] = valid_sections if valid_sections
+        DirectoryFragmentHandler.new(fragment_option, **options)
+      when :git
+        require_relative "fragment_handler/git_fragment_handler"
+        GitFragmentHandler.new
+      else
+        raise ArgumentError, "Invalid fragment option: #{fragment_option.inspect}"
+      end
+    end
+  end
+end

data/lib/reissue/rake.rb

@@ -36,6 +36,29 @@ module Reissue
     # Provide a callable to decide how to store the files.
     attr_accessor :retain_changelogs
 
+    # The fragment configuration for changelog entries.
+    # @return [String, nil] nil (disabled) or a directory path string for fragment files
+    # @example Using directory-based fragments
+    #   task.fragment = "changelog_fragments"
+    # @note Default: nil (disabled)
+    attr_accessor :fragment
+
+    # @deprecated Use {#fragment} instead
+    def fragment_directory=(value)
+      warn "[DEPRECATION] `fragment_directory` is deprecated. Please use `fragment` instead."
+      self.fragment = value
+    end
+
+    # @deprecated Use {#fragment} instead
+    def fragment_directory
+      warn "[DEPRECATION] `fragment_directory` is deprecated. Please use `fragment` instead."
+      @fragment
+    end
+
+    # Whether to clear fragment files after processing.
+    # Default: false.
+    attr_accessor :clear_fragments
+
     # Additional paths to add to the commit.
     attr_writer :updated_paths
 
@@ -49,6 +72,9 @@ module Reissue
     # Whether to commit the finalize change to the changelog. Default: true.
     attr_accessor :commit_finalize
 
+    # Whether to commit the clear fragments change. Default: true.
+    attr_accessor :commit_clear_fragments
+
     # Whether to branch and push the changes. Default: :branch.
     # Requires commit_finialize to be true.
     #
@@ -74,8 +100,11 @@ module Reissue
       @updated_paths = []
       @changelog_file = "CHANGELOG.md"
       @retain_changelogs = false
+      @fragment = nil
+      @clear_fragments = false
       @commit = true
       @commit_finalize = true
+      @commit_clear_fragments = true
       @push_finalize = false
       @version_limit = 2
       @version_redo_proc = nil
@@ -113,9 +142,17 @@ module Reissue
       desc description
       task name, [:segment] do |task, args|
         segment = args[:segment] || "patch"
-        new_version = formatter.call(segment:, version_file:, version_limit:, version_redo_proc:)
+        new_version = formatter.call(
+          segment:,
+          version_file:,
+          version_limit:,
+          version_redo_proc:,
+          fragment: fragment
+        )
         bundle
 
+        tasker["#{name}:clear_fragments"].invoke
+
         system("git add -u")
         if updated_paths&.any?
           system("git add #{updated_paths.join(" ")}")
@@ -151,10 +188,17 @@ module Reissue
       desc "Finalize the changelog for an unreleased version to set the release date."
       task "#{name}:finalize", [:date] do |task, args|
         date = args[:date] || Time.now.strftime("%Y-%m-%d")
-        version, date = formatter.finalize(date, changelog_file:, retain_changelogs:)
+        version, date = formatter.finalize(
+          date,
+          changelog_file:,
+          retain_changelogs:,
+          fragment: fragment
+        )
         finalize_message = "Finalize the changelog for version #{version} on #{date}"
         if commit_finalize
-          tasker["#{name}:branch"].invoke("reissue/#{version}") if finalize_with_branch?
+          if finalize_with_branch?
+            tasker["#{name}:branch"].invoke("reissue/#{version}")
+          end
           system("git add -u")
           system("git commit -m '#{finalize_message}'")
           tasker["#{name}:push"].invoke if push_finalize?
@@ -163,16 +207,81 @@ module Reissue
         end
       end
 
-      desc "Create a new branch for the next version."
+      desc <<~MSG
+        Create a new branch for the next version.
+
+        If the branch already exists it will be deleted and a new one will be created along with a new tag.
+      MSG
+
       task "#{name}:branch", [:branch_name] do |task, args|
         raise "No branch name specified" unless args[:branch_name]
-        system("git checkout -b #{args[:branch_name]}")
+        branch_name = args[:branch_name]
+        # Force create branch by deleting if exists, then creating fresh
+        if system("git show-ref --verify --quiet refs/heads/#{branch_name}")
+          # Extract version from branch name (e.g., "reissue/0.4.1" -> "0.4.1")
+          version = branch_name.sub(/^reissue\//, "")
+          # Delete matching tag if it exists
+          system("git tag -d v#{version} 2>/dev/null || true")
+          # Delete the branch
+          system("git branch -D #{branch_name}")
+        end
+        system("git checkout -b #{branch_name}")
       end
 
       desc "Push the current branch to the remote repository."
       task "#{name}:push" do
         system("git push origin HEAD")
       end
+
+      desc "Preview changelog entries that will be added from fragments or git trailers"
+      task "#{name}:preview" do
+        if fragment
+          require_relative "fragment_handler"
+          handler = Reissue::FragmentHandler.for(fragment)
+          entries = handler.read
+
+          if entries.empty?
+            puts "No changelog entries found."
+            if fragment == :git
+              puts "  (No git trailers found since last version tag)"
+            else
+              puts "  (No fragment files found in '#{fragment}')"
+            end
+          else
+            puts "Changelog entries that will be added:\n\n"
+            # Sort sections in Keep a Changelog order
+            section_order = %w[Added Changed Deprecated Removed Fixed Security]
+            sorted_sections = entries.keys.sort_by { |k| section_order.index(k) || 999 }
+
+            sorted_sections.each do |section|
+              items = entries[section]
+              puts "### #{section}\n"
+              items.each { |item| puts "- #{item}" }
+              puts
+            end
+
+            puts "Total: #{entries.values.flatten.count} entries across #{entries.keys.count} sections"
+          end
+        else
+          puts "Fragment handling is not configured."
+          puts "Set task.fragment to a directory path or :git to enable changelog fragments."
+        end
+      end
+
+      desc "Clear fragments"
+      task "#{name}:clear_fragments" do
+        # Clear fragments after release if configured
+        if fragment && clear_fragments
+          formatter.clear_fragments(fragment)
+          clear_message = "Clear changelog fragments"
+          if commit_clear_fragments
+            system("git add #{fragment}")
+            system("git commit -m '#{clear_message}'")
+          else
+            system("echo '#{clear_message}'")
+          end
+        end
+      end
     end
   end
 end

data/lib/reissue/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Reissue
-  VERSION = "0.4.0"
+  VERSION = "0.4.2"
 end

data/lib/reissue.rb

@@ -3,6 +3,7 @@
 require_relative "reissue/version"
 require_relative "reissue/version_updater"
 require_relative "reissue/changelog_updater"
+require_relative "reissue/fragment_handler"
 
 # Reissue is a module that provides functionality for updating version numbers and changelogs.
 module Reissue
@@ -14,6 +15,8 @@ module Reissue
   # @param date [String] The release date. Default: Unreleased
   # @param changes [Hash] The changes made in this release. Default: {}
   # @param version_limit [Integer] The number of versions to retain in the changes. Default: 2
+  # @param fragment [String, nil] The fragment source configuration (directory path or nil to disable). Default: nil
+  # @param fragment_directory [String] @deprecated Use fragment parameter instead
   #
   # @return [String] The new version number.
   def self.call(
@@ -24,13 +27,21 @@ module Reissue
     date: "Unreleased",
     changes: {},
     version_limit: 2,
-    version_redo_proc: nil
+    version_redo_proc: nil,
+    fragment: nil,
+    fragment_directory: nil
   )
+    # Handle deprecation
+    if fragment_directory && !fragment
+      warn "[DEPRECATION] `fragment_directory` parameter is deprecated. Please use `fragment` instead."
+      fragment = fragment_directory
+    end
+
     version_updater = VersionUpdater.new(version_file, version_redo_proc:)
     new_version = version_updater.call(segment, version_file:)
     if changelog_file
       changelog_updater = ChangelogUpdater.new(changelog_file)
-      changelog_updater.call(new_version, date:, changes:, changelog_file:, version_limit:, retain_changelogs:)
+      changelog_updater.call(new_version, date:, changes:, changelog_file:, version_limit:, retain_changelogs:, fragment:)
     end
     new_version
   end
@@ -39,11 +50,41 @@ module Reissue
   #
   # @param date [String] The release date.
   # @param changelog_file [String] The path to the changelog file.
+  # @param fragment [String, nil] The fragment source configuration (directory path or nil to disable). Default: nil
+  # @param fragment_directory [String] @deprecated Use fragment parameter instead
   #
   # @return [Array] The version number and release date.
-  def self.finalize(date = Date.today, changelog_file: "CHANGELOG.md", retain_changelogs: false)
+  def self.finalize(date = Date.today, changelog_file: "CHANGELOG.md", retain_changelogs: false, fragment: nil, fragment_directory: nil)
+    # Handle deprecation
+    if fragment_directory && !fragment
+      warn "[DEPRECATION] `fragment_directory` parameter is deprecated. Please use `fragment` instead."
+      fragment = fragment_directory
+    end
+
     changelog_updater = ChangelogUpdater.new(changelog_file)
+
+    # If fragments are present, we need to update the unreleased version with them first
+    if fragment
+      # Get the current changelog to find the unreleased version
+      changelog = Parser.parse(File.read(changelog_file))
+      unreleased_version = changelog["versions"].find { |v| v["date"] == "Unreleased" }
+
+      if unreleased_version
+        # Update with fragment data
+        changelog_updater.update(
+          unreleased_version["version"],
+          date: "Unreleased",
+          changes: unreleased_version["changes"] || {},
+          fragment: fragment,
+          version_limit: changelog["versions"].size
+        )
+        changelog_updater.write(changelog_file, retain_changelogs: false)
+      end
+    end
+
+    # Now finalize with the date
     changelog = changelog_updater.finalize(date:, changelog_file:, retain_changelogs:)
+
     changelog["versions"].first.slice("version", "date").values
   end
 
@@ -86,4 +127,14 @@ module Reissue
       retain_changelogs: false
     )
   end
+
+  # Clears all fragment files in the specified source.
+  #
+  # @param fragment [String] The fragment source configuration.
+  def self.clear_fragments(fragment)
+    return unless fragment
+
+    handler = FragmentHandler.for(fragment)
+    handler.clear
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: reissue
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.2
 platform: ruby
 authors:
 - Jim Gay
@@ -36,6 +36,10 @@ files:
 - Rakefile
 - lib/reissue.rb
 - lib/reissue/changelog_updater.rb
+- lib/reissue/fragment_handler.rb
+- lib/reissue/fragment_handler/directory_fragment_handler.rb
+- lib/reissue/fragment_handler/git_fragment_handler.rb
+- lib/reissue/fragment_handler/null_fragment_handler.rb
 - lib/reissue/gem.rb
 - lib/reissue/markdown.rb
 - lib/reissue/parser.rb