Rework release preparation tasks

README.md

@@ -22,12 +22,20 @@ Then, at the top of your `Rakefile`, add:
 require 'voxpupuli-release'
 ```
 
-To cut a new release of your module, ensure the `metadata.json` reflects the proper version. Also ensure that the `CHANGELOG.md` has a note about the release and that it actually is named Release or release, some old modules refer to it as Version, which won't work. Lastly check that no tag exists with that version number (format `v#.#.#`), and then run:
+To cut a new release of your module, ensure the `metadata.json` reflects the expected new version of the module, that no tag exists with that version number (format `v#.#.#`), and then update the module `CHANGELOG.md` and `REFERENCE.md` by running:
+
+```plain
+bundle exec rake release:prepare
+```
+
+Commit these changes (likely in a new branch, open a Pull-Request and wait for it to be reviewed and merged).  When ready to ship the new release, ensure you are on the main branch, it is up-to-date, and run:
 
 ```plain
 bundle exec rake release
 ```
 
+This will perform some sanity checks, tag the current commit with the version number, and bump the version number to ensure no conflict will happen by mistake.
+
 ## License
 
 This gem is licensed under the Apache-2 license.

lib/voxpupuli/release/rake_tasks.rb

@@ -1,5 +1,46 @@
 require 'puppet_blacksmith/rake_tasks'
 
+class GCGConfig
+  def self.user=(user)
+    @user = user
+  end
+
+  def self.user
+    @user || project.split(%r{[-/]}).first
+  end
+
+  def self.project=(project)
+    @project = project
+  end
+
+  def self.project
+    @project || metadata['name']
+  end
+
+  def self.metadata
+    require 'puppet_blacksmith'
+    @metadata ||= Blacksmith::Modulefile.new.metadata
+  end
+
+  def self.tag_pattern=(tag_pattern)
+    @tag_pattern = tag_pattern
+  end
+
+  def self.tag_pattern
+    @tag_pattern || 'v%s'
+  end
+
+  def self.future_release
+    if metadata['version'].match?(/^\d+\.\d+.\d+$/)
+      format(tag_pattern, metadata['version'])
+    else
+      # Not formatted like a release, might be a pre-release and the future
+      # changes should better be under an "unreleased" section.
+      nil
+    end
+  end
+end
+
 desc 'Release via GitHub Actions'
 task :release do
   Blacksmith::RakeTask.new do |t|
@@ -12,7 +53,7 @@
   m = Blacksmith::Modulefile.new
   v = m.version
   raise "Refusing to release an RC or build-release (#{v}).\n" +
-        "Please set a semver *release* version." unless v =~ /^\d+\.\d+.\d+$/
+        "Please set a semver *release* version." unless v.match?(/^\d+\.\d+.\d+$/)
 
   # validate that the REFERENCE.md is up2date, if it exists
   Rake::Task['strings:validate:reference'].invoke if File.exist?('REFERENCE.md')
@@ -52,3 +93,82 @@
     fail "Unable to find a CHANGELOG.md entry for the #{v} release."
   end
 end
+
+namespace :release do
+  desc "Prepare a release"
+  task prepare: ['release:porcelain:changelog'] do
+    v = Blacksmith::Modulefile.new.version
+    Rake::Task["strings:generate:reference"].invoke if File.exist?('REFERENCE.md')
+    puts <<~MESSAGE
+
+      Please review these changes and commit them to a new branch:
+
+          git checkout -b release-#{v}
+          git commit -m "Release #{v}"
+
+      Then open a Pull-Request and wait for it to be reviewed and merged).
+    MESSAGE
+  end
+
+  namespace :porcelain do
+    begin
+      require 'github_changelog_generator/task'
+    rescue LoadError
+      desc "Dummy"
+      task :changelog do
+        puts "Skipping CHANGELOG.md generation.  Ensure github_changelog_generator is present if you expected it to be generated."
+      end
+    else
+      task :changelog do
+        # This is taken from lib/github_changelog_generator/task
+        # The generator cannot be used because we want to lazyly evaluate
+        # GCGConfig.user which might be overrider in the module Rakefile.
+        options = GitHubChangelogGenerator::Parser.default_options
+        options[:user] = GCGConfig.user
+        options[:project] = GCGConfig.project
+        options[:future_release] = GCGConfig.future_release
+        options[:header] = <<~HEADER.chomp
+          # Changelog
+
+          All notable changes to this project will be documented in this file.
+          Each new release typically also includes the latest modulesync defaults.
+          These should not affect the functionality of the module.
+        HEADER
+        options[:exclude_labels] = %w{duplicate question invalid wontfix wont-fix modulesync skip-changelog}
+        generator = GitHubChangelogGenerator::Generator.new(options)
+        log = generator.compound_changelog
+        output_filename = options[:output].to_s
+
+        # Workaround for https://github.com/github-changelog-generator/github-changelog-generator/issues/715
+        require 'rbconfig'
+        unless RbConfig::CONFIG['host_os'].match?(/windows/)
+          puts 'Fixing line endings...'
+          log.gsub!("\r\n", "\n")
+        end
+
+        File.write(output_filename, log)
+        puts "Generated log placed in #{File.absolute_path(output_filename)}"
+      end
+    end
+  end
+end
+
+# For backward compatibility
+task :changelog do
+  fail <<-ERROR
+  The "changelog" task is deprecated.
+
+  Prefer "release:prepare" which manage all pre-release steps, or directly run
+  the "release:porcelain:changelog" task.
+  ERROR
+end
+
+# For backward compatibility
+task :reference do
+  fail <<-ERROR
+  The "reference" task is deprecated.
+
+  Prefer "release:prepare" which manage all pre-release steps, or directly run
+  the "strings:generate:reference" task.
+  ERROR
+end