reissue 0.4.22 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a9e4d5dc8c0b04d5c41514285fa8e8f2e7e87cc028b156ab7de97473e1e58276
-  data.tar.gz: e4af6b1a8061ec686f33e852b0abccd0d4e92335b87ad48c286e0645b7932ed7
+  metadata.gz: 9c5b7a3ee9dbd72238bf4b6212c953283caa5be24da67647358e74ac1fb1118f
+  data.tar.gz: 07f9b5bc9c3263a010f2a942701c49c110dd6db566d154e501db59d13c2d6cac
 SHA512:
-  metadata.gz: 12fe862113b9d5a765f7efd562ce4555b873e8496068c480f3a0531b873fbbcedc10bf44c1d971e7404ab1236f43125f08c31bac988ba88fb800dd78d5021618
-  data.tar.gz: 2235ef992fdfbda13a06e27bf1df4b582cb3ba9cfa034cdcc6bc1e7c61f8fa33167f553031dc7401eefb29edb59fc5e8ecbe699cdec3f2431796002356115b32
+  metadata.gz: 9f3a8bcfcebd80438e8b0ac3f0702594f6a5f6b265fcc1f156b40a0c4481286dc9c007ed8c2949dffc9c7f6e640cb20e2495f1774387d0537adc3e5d485b6dd8
+  data.tar.gz: ee70e94135baa48e89ecc033f071cc31814e02925b0df16c7c73b6891dc57bc671aa9e5af19a4257fdd213a8aacc859256a5f7cd9737504db8a5202df6482735

data/CHANGELOG.md

@@ -5,10 +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.23] - 2026-07-21
+
+### Added
+
+- Optional runbook_file setting maintains a post-release runbook populated from Runbook: git trailers or direct edits (b41ba15)
+
 ## [0.4.22] - 2026-04-09
 
 ### Fixed
 
 - changelog sections not following changelog_sections order on release (5f9c475)
-
-## [0.4.21] - 2026-03-11

data/README.md

@@ -345,6 +345,54 @@ Version trailers are case-insensitive:
 - **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)
 
+## Post-release Runbook
+
+Reissue can maintain a runbook file listing manual steps to perform after a release — run a rake task, clean up data, re-index documents, and so on. This is aimed at applications; gems are unlikely to need it.
+
+```ruby
+Reissue::Task.create :reissue do |task|
+  task.version_file = "config/version.rb"
+  task.fragment = :git
+  task.runbook_file = "RUNBOOK.md"  # Default: nil (disabled)
+end
+```
+
+The runbook holds only the latest release. Items are checkboxes so operators can tick them off:
+
+```markdown
+# Runbook
+
+Steps to perform after releasing the version below.
+
+## [1.2.3] - 2026-07-21
+
+- [ ] Run `rake data:cleanup` (abc1234)
+- [ ] Re-index search documents (def5678)
+```
+
+### Adding Runbook Items
+
+Add `Runbook:` trailers to commit messages (case-insensitive, independent of the `fragment` setting):
+
+```bash
+git commit -m "Add data migration
+
+Fixed: Duplicate user records
+Runbook: Run \`rake data:cleanup\` after deploy"
+```
+
+You can also edit the checklist under `## [Unreleased]` directly; direct edits and trailers are merged and deduplicated.
+
+Note: `Runbook:` is reserved for the runbook — do not add "Runbook" to `changelog_sections`.
+
+### Lifecycle
+
+1. **During development** — items accumulate from `Runbook:` trailers and direct edits.
+2. **Finalize** (`rake reissue:finalize` / before `rake build`) — trailers since the last version tag are merged into the file and the header is stamped with the release version and date, matching the changelog. The file is committed with the finalize commit, so the release tag contains the finalized runbook.
+3. **New version setup** (`rake reissue` after release) — the runbook is cleared back to a header-only `## [Unreleased]` section. Prior runbooks remain reachable via release tags.
+
+`rake reissue:preview` also shows pending runbook items when `runbook_file` is configured.
+
 ## 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.

data/lib/reissue/fragment_handler/directory_fragment_handler.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "pathname"
-
 module Reissue
   # Handler for reading fragments from a directory
   class DirectoryFragmentHandler < FragmentHandler

data/lib/reissue/fragment_handler/git_fragment_handler.rb

@@ -44,6 +44,16 @@ module Reissue
         find_last_tag
       end
 
+      # Read runbook entries from git commit trailers
+      #
+      # @return [Array<String>] Runbook items with the short SHA appended
+      def read_runbook_entries
+        return [] unless git_available? && in_git_repo?
+
+        commits = commits_since_last_tag
+        parse_runbook_entries_from_commits(commits)
+      end
+
       # Read version bump from git commit trailers
       #
       # @return [Symbol, nil] One of :major, :minor, :patch, or nil if none found
@@ -185,6 +195,44 @@ module Reissue
         result
       end
 
+      RUNBOOK_TRAILER_REGEX = /^runbook:\s*(.+)$/i
+
+      def parse_runbook_entries_from_commits(commits)
+        entries = []
+
+        commits.each do |commit|
+          sha = commit[:sha]
+          lines = commit[:message].lines
+
+          i = 0
+          while i < lines.length
+            line = lines[i].rstrip
+            i += 1
+            next if line.strip.empty?
+
+            if (match = line.match(RUNBOOK_TRAILER_REGEX))
+              trailer_value = match[1].strip
+
+              # Collect continuation lines (non-empty lines that don't start a new trailer)
+              while i < lines.length
+                next_line = lines[i].rstrip
+                break if next_line.strip.empty?
+                break if next_line.match(RUNBOOK_TRAILER_REGEX)
+                break if next_line.match(trailer_regex)
+                break if next_line.match?(/^[A-Za-z][\w-]+:\s/)
+
+                trailer_value += " #{next_line.strip}"
+                i += 1
+              end
+
+              entries << "#{trailer_value} (#{sha})"
+            end
+          end
+        end
+
+        entries
+      end
+
       def normalize_section_name(name)
         # Normalize to proper case (e.g., "FIXED" -> "Fixed", "added" -> "Added")
         name.capitalize

data/lib/reissue/rake.rb

@@ -37,6 +37,12 @@ module Reissue
     # Provide a callable to decide how to store the files.
     attr_accessor :retain_changelogs
 
+    # The path to a runbook file listing steps to perform after a release.
+    # Populated from "Runbook:" git trailers or direct edits, finalized with
+    # the release version, and cleared when a new version is prepared.
+    # Default: nil (disabled).
+    attr_accessor :runbook_file
+
     # The fragment configuration for changelog entries.
     # @return [String, nil] nil (disabled) or a directory path string for fragment files
     # @example Using directory-based fragments
@@ -126,6 +132,7 @@ module Reissue
       @updated_paths = []
       @changelog_file = "CHANGELOG.md"
       @retain_changelogs = false
+      @runbook_file = nil
       @fragment = nil
       @clear_fragments = false
       @commit = true
@@ -187,9 +194,9 @@ module Reissue
       !status.success?
     end
 
-    # Stage updated_paths that exist on disk.
+    # Stage updated_paths (and the runbook file) that exist on disk.
     def stage_updated_paths
-      existing = updated_paths.select { |p| File.exist?(p) }
+      existing = (updated_paths + [runbook_file].compact).select { |p| File.exist?(p) }
       if existing.any?
         run_command("git add #{existing.join(" ")}", "Failed to stage additional paths: #{existing.join(", ")}")
       end
@@ -206,7 +213,8 @@ module Reissue
             changelog_file:,
             version_limit:,
             fragment: fragment,
-            tag_pattern:
+            tag_pattern:,
+            runbook_file:
           )
         else
           segment = args[:segment] || "patch"
@@ -217,7 +225,8 @@ module Reissue
             version_limit:,
             version_redo_proc:,
             fragment: fragment,
-            tag_pattern:
+            tag_pattern:,
+            runbook_file:
           )
         end
         bundle
@@ -287,7 +296,8 @@ module Reissue
             fragment: fragment,
             tag_pattern:,
             version_file:,
-            version_redo_proc:
+            version_redo_proc:,
+            runbook_file:
           )
         else
           date = args[:version_or_segment] || Time.now.strftime("%Y-%m-%d")
@@ -297,7 +307,8 @@ module Reissue
             retain_changelogs:,
             fragment: fragment,
             tag_pattern:,
-            version_file:
+            version_file:,
+            runbook_file:
           )
         end
 
@@ -375,6 +386,20 @@ module Reissue
           puts "Fragment handling is not configured."
           puts "Set task.fragment to a directory path or :git to enable changelog fragments."
         end
+
+        if runbook_file
+          require_relative "fragment_handler"
+          runbook_entries = Reissue::FragmentHandler.for(:git, tag_pattern: tag_pattern).read_runbook_entries
+
+          puts
+          if runbook_entries.empty?
+            puts "No runbook items found."
+            puts "  (No Runbook: trailers found since last version tag)"
+          else
+            puts "Runbook items that will be added to #{runbook_file}:\n\n"
+            runbook_entries.each { |item| puts "- [ ] #{item}" }
+          end
+        end
       end
 
       desc "Clear fragments"
@@ -487,6 +512,9 @@ namespace :reissue do
         # task.fragment = "changelog_fragments"   # Or use a directory of fragment files
         task.clear_fragments = false              # Clear fragment files after release. Not necessary when using git trailers.
 
+        # Post-release runbook (mainly for applications)
+        # task.runbook_file = "RUNBOOK.md"        # Maintain a runbook from Runbook: git trailers
+
         # Git workflow options
         task.commit = true                        # Auto-commit version bumps
         task.commit_finalize = true               # Auto-commit changelog finalization

data/lib/reissue/runbook.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Reissue
+  # Maintains a post-release runbook file listing steps to perform after
+  # releasing a version. The file holds only the latest release.
+  class Runbook
+    ITEM_PATTERN = /^- (?:\[(?<checked>[ xX])\] )?(?<text>.+)$/
+
+    def initialize(runbook_file)
+      @runbook_file = runbook_file
+    end
+
+    attr_reader :runbook_file
+
+    # Writes a header-only template for the given version.
+    def generate(version: "Unreleased")
+      File.write(runbook_file, template(heading(version)))
+    end
+
+    alias_method :clear, :generate
+
+    # Returns the text of each checklist item, without checkbox markers.
+    def items
+      parsed_items.map { |item| item[:text] }
+    end
+
+    # Stamps the header with the release version and date, merging directly
+    # edited items with trailer items (deduplicated by text).
+    def finalize(version:, date:, trailer_items: [])
+      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))
+    end
+
+    private
+
+    def parsed_items
+      return [] unless File.exist?(runbook_file)
+
+      File.read(runbook_file).lines.filter_map do |line|
+        match = line.rstrip.match(ITEM_PATTERN)
+        next unless match
+        {text: match[:text], checked: match[:checked]&.downcase == "x"}
+      end
+    end
+
+    def heading(version, date = nil)
+      date ? "## [#{version}] - #{date}" : "## [#{version}]"
+    end
+
+    def template(heading, items = [])
+      header = <<~MARKDOWN
+        # Runbook
+
+        Steps to perform after releasing the version below.
+
+        #{heading}
+      MARKDOWN
+      return header if items.empty?
+
+      list = items.map { |item| "- [#{item[:checked] ? "x" : " "}] #{item[:text]}" }.join("\n")
+      "#{header}\n#{list}\n"
+    end
+  end
+end

data/lib/reissue/version.rb

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

data/lib/reissue/version_updater.rb

@@ -21,12 +21,12 @@ module Reissue
         when :patch
           segments.slice(0, 2) + segments.slice(2..-1).then { |array|
             array[-1] = array[-1].next
-            [array.map(&:to_s).join]
+            [array.join]
           }
         when :pre
           segments.slice(0, 3) + segments.slice(3..-1).then { |array|
             array[-1] = array[-1].next
-            [array.map(&:to_s).join]
+            [array.join]
           }
         else
           raise ArgumentError, "Invalid segment name: #{segment_name}"

data/lib/reissue.rb

@@ -4,6 +4,7 @@ require_relative "reissue/version"
 require_relative "reissue/version_updater"
 require_relative "reissue/changelog_updater"
 require_relative "reissue/fragment_handler"
+require_relative "reissue/runbook"
 
 # Reissue is a module that provides functionality for updating version numbers and changelogs.
 module Reissue
@@ -40,7 +41,8 @@ module Reissue
     version_redo_proc: nil,
     fragment: nil,
     fragment_directory: nil,
-    tag_pattern: nil
+    tag_pattern: nil,
+    runbook_file: nil
   )
     # Handle deprecation
     if fragment_directory && !fragment
@@ -55,10 +57,11 @@ module Reissue
       changelog_updater = ChangelogUpdater.new(changelog_file)
       changelog_updater.call(new_version, date:, changes:, changelog_file:, version_limit:, retain_changelogs:, fragment:, tag_pattern:)
     end
+    Runbook.new(runbook_file).clear if runbook_file
     new_version
   end
 
-  def self.deferred_call(version_file:, changelog_file: "CHANGELOG.md", version_limit: 2, retain_changelogs: false, fragment: nil, tag_pattern: nil)
+  def self.deferred_call(version_file:, changelog_file: "CHANGELOG.md", version_limit: 2, retain_changelogs: false, fragment: nil, tag_pattern: nil, runbook_file: nil)
     version_updater = VersionUpdater.new(version_file)
     version_updater.set_version("Unreleased", version_file:)
     version_updater.update_release_date("Unreleased", version_file:)
@@ -68,10 +71,11 @@ module Reissue
       changelog_updater.call("Unreleased", date: nil, changes: {}, changelog_file:, version_limit:, retain_changelogs:, fragment:, tag_pattern:)
     end
 
+    Runbook.new(runbook_file).clear if runbook_file
     "Unreleased"
   end
 
-  def self.deferred_finalize(date = Date.today, version: nil, segment: nil, changelog_file: "CHANGELOG.md", retain_changelogs: false, fragment: nil, tag_pattern: nil, version_file: nil, version_redo_proc: nil)
+  def self.deferred_finalize(date = Date.today, version: nil, segment: nil, changelog_file: "CHANGELOG.md", retain_changelogs: false, fragment: nil, tag_pattern: nil, version_file: nil, version_redo_proc: nil, runbook_file: nil)
     resolved_version = if version&.match?(/^\d/)
       version
     elsif segment || version
@@ -145,7 +149,14 @@ module Reissue
     end
 
     changelog = changelog_updater.finalize(date: date, changelog_file: changelog_file, retain_changelogs: retain_changelogs, resolved_version: resolved_version)
-    changelog["versions"].first.slice("version", "date").values
+    changelog["versions"].first.slice("version", "date").values.tap do |finalized_version, finalized_date|
+      finalize_runbook(runbook_file, version: finalized_version, date: finalized_date, tag_pattern:) if runbook_file
+    end
+  end
+
+  private_class_method def self.finalize_runbook(runbook_file, version:, date:, tag_pattern: nil)
+    trailer_items = FragmentHandler.for(:git, tag_pattern:).read_runbook_entries
+    Runbook.new(runbook_file).finalize(version:, date:, trailer_items:)
   end
 
   private_class_method def self.resolve_version_from_tag(segment, tag_pattern: nil, version_redo_proc: nil)
@@ -165,7 +176,7 @@ module Reissue
   # @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, fragment: nil, fragment_directory: nil, tag_pattern: nil, version_file: nil)
+  def self.finalize(date = Date.today, changelog_file: "CHANGELOG.md", retain_changelogs: false, fragment: nil, fragment_directory: nil, tag_pattern: nil, version_file: nil, runbook_file: nil)
     # Handle deprecation
     if fragment_directory && !fragment
       warn "[DEPRECATION] `fragment_directory` parameter is deprecated. Please use `fragment` instead."
@@ -224,7 +235,9 @@ module Reissue
       version_updater.update_release_date(date.to_s, version_file:)
     end
 
-    changelog["versions"].first.slice("version", "date").values
+    changelog["versions"].first.slice("version", "date").values.tap do |finalized_version, finalized_date|
+      finalize_runbook(runbook_file, version: finalized_version, date: finalized_date, tag_pattern:) if runbook_file
+    end
   end
 
   # Reformats the changelog file to ensure it is correctly formatted.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: reissue
 version: !ruby/object:Gem::Version
-  version: 0.4.22
+  version: 0.5.0
 platform: ruby
 authors:
 - Jim Gay
@@ -46,6 +46,7 @@ files:
 - lib/reissue/parser.rb
 - lib/reissue/printer.rb
 - lib/reissue/rake.rb
+- lib/reissue/runbook.rb
 - lib/reissue/version.rb
 - lib/reissue/version_updater.rb
 homepage: https://github.com/SOFware/reissue
@@ -68,7 +69,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 4.0.6
 specification_version: 4
 summary: Keep your versions and changelogs up to date and prepared for release.
 test_files: []