reissue 0.5.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9c5b7a3ee9dbd72238bf4b6212c953283caa5be24da67647358e74ac1fb1118f
-  data.tar.gz: 07f9b5bc9c3263a010f2a942701c49c110dd6db566d154e501db59d13c2d6cac
+  metadata.gz: 6c5e8636f0e88ac91af9c6dec7033c12a62e55d6c47a0eb2212dc03d51877058
+  data.tar.gz: a83714b57eb820b00a4b3cbfdab77640d5062f7d3e00aba0b52aca83d89cbad0
 SHA512:
-  metadata.gz: 9f3a8bcfcebd80438e8b0ac3f0702594f6a5f6b265fcc1f156b40a0c4481286dc9c007ed8c2949dffc9c7f6e640cb20e2495f1774387d0537adc3e5d485b6dd8
-  data.tar.gz: ee70e94135baa48e89ecc033f071cc31814e02925b0df16c7c73b6891dc57bc671aa9e5af19a4257fdd213a8aacc859256a5f7cd9737504db8a5202df6482735
+  metadata.gz: 63a416ec48050137cd7ee8ecd1d295395aa2e32b243fbb0835aecd185a48ddf36abebfe1c979450ef6be9cec46a67c2163896fba5b265874dc7b13eb1bc76ad5
+  data.tar.gz: d6b7f8c2e94997cd952c8e84aa74f29659d06cae56d338e20c10d37405ee1eb8dbf5615688268d366855942d1745bd36d7cd2f8881a1c29104c6045ad29a1947

data/CHANGELOG.md

@@ -5,14 +5,23 @@ 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.1] - 2026-07-24
 
 ### Added
 
-- Optional runbook_file setting maintains a post-release runbook populated from Runbook: git trailers or direct edits (b41ba15)
+- 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
 
-## [0.4.22] - 2026-04-09
+- 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)
+
+## [0.4.23] - 2026-07-21
+
+### Added
+
+- Optional runbook_file setting maintains a post-release runbook populated from Runbook: git trailers or direct edits (b41ba15)

data/README.md

@@ -357,6 +357,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 +372,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

@@ -188,6 +188,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")
@@ -359,6 +431,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 +499,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 +527,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 +535,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 +544,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 +554,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 +565,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 +604,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.1"
+  RELEASE_DATE = "2026-07-24"
 end

metadata

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