reissue 0.5.0 → 0.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9c5b7a3ee9dbd72238bf4b6212c953283caa5be24da67647358e74ac1fb1118f
-  data.tar.gz: 07f9b5bc9c3263a010f2a942701c49c110dd6db566d154e501db59d13c2d6cac
+  metadata.gz: ec588273a5faaed4d2287b8bde8877deb2e64b4ff8ef84ff71ce5ce58dd85ffc
+  data.tar.gz: 4ae823291b5180145e82bdba30d87c89a69440f5ab41df9c6120813898afdc1c
 SHA512:
-  metadata.gz: 9f3a8bcfcebd80438e8b0ac3f0702594f6a5f6b265fcc1f156b40a0c4481286dc9c007ed8c2949dffc9c7f6e640cb20e2495f1774387d0537adc3e5d485b6dd8
-  data.tar.gz: ee70e94135baa48e89ecc033f071cc31814e02925b0df16c7c73b6891dc57bc671aa9e5af19a4257fdd213a8aacc859256a5f7cd9737504db8a5202df6482735
+  metadata.gz: 91d584ae8adb5bebee45f1ca5668df9e136399a56134350ea8cf76c25dff748406f909cfb3d4110d8c92907376c3105c6d1d94d89d7c9047b5d0955004f28e84
+  data.tar.gz: d27c47553f7ac4a2969a6ac15e91ad23e928f74c989526e7a20e6a92e8ef333363cd04817bed4ab89833bd2ae8f7bc234e02e6a1fa87e1110660a57551a39594

data/CHANGELOG.md

@@ -5,14 +5,31 @@ 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.23] - 2026-07-21
+## [0.5.2] - 2026-09-17
 
 ### Added
 
-- Optional runbook_file setting maintains a post-release runbook populated from Runbook: git trailers or direct edits (b41ba15)
+- finalize_message option sets the finalize commit subject from the version and date (3716c08)
 
-## [0.4.22] - 2026-04-09
+### Changed
+
+- Finalize commits use the subject "Finalize changelog for VERSION" without the release date (3716c08)
+
+### Fixed
+
+- Shared release workflow retries post-release PR creation up to three times before failing, since the gem is already published and the branch pushed by that point (84bf0da)
+
+## [0.5.1] - 2026-07-24
+
+### Added
+
+- reissue:next_version task reports the version the next release would use without changing anything (9feb212)
+- reissue:initialize[runbook] scaffolds a starter runbook file (dfa521a)
+
+### Changed
+
+- Runbook finalize and new-version reset preserve a custom title and preamble (a0d874c)
 
 ### Fixed
 
-- changelog sections not following changelog_sections order on release (5f9c475)
+- Releases no longer publish a version whose changelog entry and git tag name the previous version (acf4c1a)

data/README.md

@@ -123,6 +123,10 @@ Reissue::Task.create :reissue do |task|
   # Optional: Whether to commit the results of the finalize task. Defaults to true
   task.commit_finalize = true
   
+  # Optional: A callable returning the finalize commit subject, given version and date.
+  # Defaults to: ->(version, date) { "Finalize changelog for #{version}" }
+  task.finalize_message = ->(version, date) { "Release #{version}" }
+  
   # 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
@@ -357,6 +361,8 @@ Reissue::Task.create :reissue do |task|
 end
 ```
 
+You don't have to create the file yourself — the first `rake reissue` or `rake reissue:finalize` writes it when `runbook_file` is set. To start from a template you can customize, run `rake reissue:initialize[runbook]`, which creates `RUNBOOK.md` (pass a different name, e.g. `rake reissue:initialize[OPERATIONS.md]`, to use another path).
+
 The runbook holds only the latest release. Items are checkboxes so operators can tick them off:
 
 ```markdown
@@ -370,6 +376,8 @@ Steps to perform after releasing the version below.
 - [ ] Re-index search documents (def5678)
 ```
 
+The title and the preamble beneath it are yours to edit. Give the file a custom heading and intro and reissue preserves them across finalize and new-version resets — only the version heading and the checklist are rewritten, the same way a custom preamble survives in `CHANGELOG.md`.
+
 ### Adding Runbook Items
 
 Add `Runbook:` trailers to commit messages (case-insensitive, independent of the `fragment` setting):

data/lib/reissue/gem.rb

@@ -7,6 +7,30 @@ module Reissue
       super
       @updated_paths << "checksums"
     end
+
+    # Keep bundler's gemspec in step with the bump.
+    #
+    # Bundler loads the gemspec when bundler/gem_tasks is required, well before
+    # reissue:bump rewrites the version file. `gem build` shells out and re-reads
+    # the file, so the gem itself carries the bumped version, but the release tag
+    # and bundler's confirmation messages read the copy held in memory. Without
+    # this they name the version from before the bump, and the release publishes
+    # one version under another version's tag.
+    def apply_version_bump(updater, bump)
+      new_version = super
+      sync_bundler_gemspec_version(new_version)
+      new_version
+    end
+
+    # @param new_version [String] the version the bump landed on
+    def sync_bundler_gemspec_version(new_version)
+      return unless defined?(Bundler::GemHelper)
+
+      helper = Bundler::GemHelper.instance
+      return unless helper&.gemspec
+
+      helper.gemspec.version = ::Gem::Version.new(new_version)
+    end
   end
 end
 Reissue::Task.prepend Reissue::Gem

data/lib/reissue/rake.rb

@@ -79,6 +79,11 @@ module Reissue
     # Whether to commit the finalize change to the changelog. Default: true.
     attr_accessor :commit_finalize
 
+    # Callable receiving the version and release date, returning the commit subject.
+    # The default omits the date to stay under the 50-character subject limit.
+    # Default: ->(version, date) { "Finalize changelog for #{version}" }
+    attr_accessor :finalize_message
+
     # Whether to commit the clear fragments change.
     # Returns false for :git fragments since there are no files to commit.
     attr_writer :commit_clear_fragments
@@ -137,6 +142,7 @@ module Reissue
       @clear_fragments = false
       @commit = true
       @commit_finalize = true
+      @finalize_message = ->(version, _date) { "Finalize changelog for #{version}" }
       @commit_clear_fragments = true
       @push_finalize = false
       @version_limit = 2
@@ -188,6 +194,78 @@ module Reissue
       end
     end
 
+    # The version the next release would use, derived exactly the way reissue:bump
+    # derives it, without writing anything.
+    #
+    # @return [Gem::Version] the version a release would publish
+    def next_release_version
+      require_relative "fragment_handler"
+      require_relative "version_updater"
+
+      # reissue:bump only consults git trailers for :git fragments.
+      handler = (Reissue::FragmentHandler.for(:git, tag_pattern: tag_pattern) if fragment == :git)
+      tag_version = handler&.last_tag_version
+      bump = handler&.read_version_bump
+      updater = Reissue::VersionUpdater.new(version_file, version_redo_proc: version_redo_proc)
+
+      if deferred_versioning
+        # The version file holds "Unreleased"; finalize resolves the real version
+        # from the last tag and the trailer.
+        unless tag_version && bump
+          raise "Cannot determine the next version. Deferred versioning resolves it from " \
+                "the last version tag and a Version: trailer, and one of those is missing."
+        end
+        return updater.redo(tag_version, bump)
+      end
+
+      current_version = ::Gem::Version.new(File.read(version_file).match(Reissue::VersionUpdater::VERSION_MATCH)[0])
+
+      if bump.nil?
+        current_version
+      elsif tag_version && tag_version != current_version
+        # A post-release bump already moved the file past the tag, so the trailer
+        # only counts if it would land beyond where the file already is.
+        [updater.redo(tag_version, bump), current_version].max
+      else
+        updater.redo(current_version, bump)
+      end
+    end
+
+    # Apply a version bump and leave the changelog agreeing with it.
+    #
+    # @param updater [Reissue::VersionUpdater] the updater to bump with
+    # @param bump [Symbol] the segment to bump
+    # @return [String] the version the bump landed on
+    def apply_version_bump(updater, bump)
+      new_version = updater.call(bump)
+      realign_unreleased_changelog(new_version)
+      bundle
+      puts "Version bumped (#{bump}) to #{new_version}"
+      new_version
+    end
+
+    # Point the changelog's unreleased entry at the version just bumped to.
+    #
+    # The bump moves the version file forward, but the unreleased entry still
+    # carries the number from the previous cycle. reissue:finalize dates whatever
+    # that entry says, so leaving it alone publishes a gem built at the new
+    # version while the only dated changelog entry names the old one.
+    #
+    # @param new_version [String] the version the bump landed on
+    def realign_unreleased_changelog(new_version)
+      return unless changelog_file && File.exist?(changelog_file)
+
+      changelog = Reissue::Parser.parse(File.read(changelog_file))
+      unreleased = changelog["versions"].find { |version| version["date"] == "Unreleased" }
+      return if unreleased.nil? || unreleased["version"] == new_version
+
+      unreleased["version"] = new_version
+
+      changelog_updater = Reissue::ChangelogUpdater.new(changelog_file)
+      changelog_updater.instance_variable_set(:@changelog, changelog)
+      changelog_updater.write(changelog_file)
+    end
+
     # Check if there are staged changes ready to commit.
     def changes_to_commit?
       _, _, status = Open3.capture3("git diff --cached --quiet")
@@ -312,7 +390,7 @@ module Reissue
           )
         end
 
-        finalize_message = "Finalize the changelog for version #{version} on #{date}"
+        message = finalize_message.call(version, date)
         if commit_finalize
           if finalize_with_branch?
             tasker["#{name}:branch"].invoke("finalize/#{version}")
@@ -320,13 +398,13 @@ module Reissue
           run_command("git add -u", "Failed to stage finalized changelog")
           stage_updated_paths
           if changes_to_commit?
-            run_command("git commit -m '#{finalize_message}'", "Failed to commit finalized changelog")
+            run_command("git commit -m '#{message}'", "Failed to commit finalized changelog")
             tasker["#{name}:push"].invoke if push_finalize?
           else
-            puts finalize_message
+            puts message
           end
         else
-          puts finalize_message
+          puts message
         end
       end
 
@@ -359,6 +437,15 @@ module Reissue
             end
           end
 
+          # Preview reports; it does not fail. next_release_version raises when
+          # deferred versioning has no tag or trailer to resolve from.
+          previewed_version = begin
+            next_release_version
+          rescue RuntimeError
+            nil
+          end
+          puts "Version to be released: #{previewed_version || "cannot be determined"}\n\n"
+
           entries = handler.read
 
           if entries.empty?
@@ -418,6 +505,11 @@ module Reissue
         end
       end
 
+      desc "Print the version the next release would use, without changing anything"
+      task "#{name}:next_version" do
+        puts next_release_version
+      end
+
       desc "Bump version based on git trailers"
       task "#{name}:bump" do
         next if deferred_versioning
@@ -441,9 +533,7 @@ module Reissue
         if tag_version && current_version == tag_version
           if bump
             updater = Reissue::VersionUpdater.new(version_file, version_redo_proc: version_redo_proc)
-            updater.call(bump)
-            bundle
-            puts "Version bumped (#{bump}) to #{updater.instance_variable_get(:@new_version)}"
+            apply_version_bump(updater, bump)
           end
         elsif tag_version && current_version != tag_version
           if bump
@@ -451,9 +541,7 @@ module Reissue
             desired_version = updater.redo(tag_version, bump)
 
             if desired_version > current_version
-              updater.call(bump)
-              bundle
-              puts "Version bumped (#{bump}) to #{updater.instance_variable_get(:@new_version)}"
+              apply_version_bump(updater, bump)
             else
               puts "Version already bumped (#{tag_version} → #{current_version}), skipping"
             end
@@ -462,9 +550,7 @@ module Reissue
           end
         elsif bump
           updater = Reissue::VersionUpdater.new(version_file, version_redo_proc: version_redo_proc)
-          updater.call(bump)
-          bundle
-          puts "Version bumped (#{bump}) to #{updater.instance_variable_get(:@new_version)}"
+          apply_version_bump(updater, bump)
         end
       end
     end
@@ -474,8 +560,8 @@ end
 # Define the reissue:initialize task as a standalone task
 # This works without any configuration, allowing users to bootstrap their project
 namespace :reissue do
-  desc "Initialize reissue by creating a CHANGELOG.md and showing Rakefile configuration"
-  task :initialize do
+  desc "Initialize reissue by creating a CHANGELOG.md and showing Rakefile configuration. Pass [runbook] to also create a RUNBOOK.md."
+  task :initialize, [:runbook] do |task, args|
     changelog_file = "CHANGELOG.md"
 
     if File.exist?(changelog_file)
@@ -485,6 +571,16 @@ namespace :reissue do
       puts "✓ Created #{changelog_file}"
     end
 
+    if args[:runbook]
+      runbook_file = (args[:runbook] == "runbook") ? "RUNBOOK.md" : args[:runbook]
+      if File.exist?(runbook_file)
+        puts "✓ #{runbook_file} already exists"
+      else
+        Reissue::Runbook.new(runbook_file).generate
+        puts "✓ Created #{runbook_file}"
+      end
+    end
+
     puts
     puts "Add the following to your Rakefile to enable reissue tasks:"
     puts
@@ -514,6 +610,7 @@ namespace :reissue do
 
         # Post-release runbook (mainly for applications)
         # task.runbook_file = "RUNBOOK.md"        # Maintain a runbook from Runbook: git trailers
+        #                                         # Seed a starter file with: rake reissue:initialize[runbook]
 
         # Git workflow options
         task.commit = true                        # Auto-commit version bumps

data/lib/reissue/runbook.rb

@@ -6,15 +6,20 @@ module Reissue
   class Runbook
     ITEM_PATTERN = /^- (?:\[(?<checked>[ xX])\] )?(?<text>.+)$/
 
+    DEFAULT_TITLE = "Runbook"
+    DEFAULT_PREAMBLE = "Steps to perform after releasing the version below."
+
     def initialize(runbook_file)
       @runbook_file = runbook_file
     end
 
     attr_reader :runbook_file
 
-    # Writes a header-only template for the given version.
+    # Writes a header-only template for the given version, preserving any
+    # custom title and preamble already in the file.
     def generate(version: "Unreleased")
-      File.write(runbook_file, template(heading(version)))
+      title, preamble = parsed_header
+      File.write(runbook_file, template(heading(version), title:, preamble:))
     end
 
     alias_method :clear, :generate
@@ -25,18 +30,33 @@ module Reissue
     end
 
     # Stamps the header with the release version and date, merging directly
-    # edited items with trailer items (deduplicated by text).
+    # edited items with trailer items (deduplicated by text). Preserves any
+    # custom title and preamble already in the file.
     def finalize(version:, date:, trailer_items: [])
+      title, preamble = parsed_header
       merged = parsed_items
       texts = merged.map { |item| item[:text] }
       trailer_items.each do |text|
         merged << {text: text, checked: false} unless texts.include?(text)
       end
-      File.write(runbook_file, template(heading(version, date), merged))
+      File.write(runbook_file, template(heading(version, date), merged, title:, preamble:))
     end
 
     private
 
+    # Returns the [title, preamble] found before the first version heading,
+    # falling back to the defaults when the file is missing or header-only.
+    def parsed_header
+      return [DEFAULT_TITLE, DEFAULT_PREAMBLE] unless File.exist?(runbook_file)
+
+      header_chunk = File.read(runbook_file).split(/^## /, 2).first.to_s
+      title_match = header_chunk.match(/^#\s+(?<title>.+)$/)
+      title = title_match ? title_match[:title].strip : DEFAULT_TITLE
+      preamble = (title_match ? header_chunk.sub(title_match[0], "") : header_chunk).strip
+      preamble = DEFAULT_PREAMBLE if preamble.empty?
+      [title, preamble]
+    end
+
     def parsed_items
       return [] unless File.exist?(runbook_file)
 
@@ -51,11 +71,11 @@ module Reissue
       date ? "## [#{version}] - #{date}" : "## [#{version}]"
     end
 
-    def template(heading, items = [])
+    def template(heading, items = [], title: DEFAULT_TITLE, preamble: DEFAULT_PREAMBLE)
       header = <<~MARKDOWN
-        # Runbook
+        # #{title}
 
-        Steps to perform after releasing the version below.
+        #{preamble}
 
         #{heading}
       MARKDOWN

data/lib/reissue/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module Reissue
-  VERSION = "0.5.0"
-  RELEASE_DATE = "2026-07-21"
+  VERSION = "0.5.2"
+  RELEASE_DATE = "2026-09-17"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: reissue
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.5.2
 platform: ruby
 authors:
 - Jim Gay