create_github_release 0.2.0 → 0.3.0

data/lib/create_github_release/backtick_debug.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module CreateGithubRelease
+  # Include this module to output debug information for backticks
+  #
+  # The class this module is included in must have a `backtick_debug?` method.
+  #
+  # @example Using this module to debug backticks
+  #    class Foo
+  #      include CreateGithubRelease::BacktickDebug
+  #
+  #      def backtick_debug?; true; end
+  #
+  #      def bar
+  #        `echo foo`
+  #      end
+  #    end
+  #
+  #    Foo.new.bar #=>
+  #    COMMAND
+  #      echo foo
+  #    OUTPUT
+  #      foo
+  #    EXITSTATUS
+  #      0
+  #
+  # @api public
+  #
+  module BacktickDebug
+    # Calls `super` and shows the command and its result if `backtick_debug?` is true
+    #
+    # The command, it's output, and it's exit status are output to stdout via `puts`.
+    #
+    # The including class is expected to have a `backtick_debug?` method.
+    #
+    # @example
+    #   including_class.new.send('`'.to_sym, 'echo foo') #=>
+    #    COMMAND
+    #      echo foo
+    #    OUTPUT
+    #      foo
+    #    EXITSTATUS
+    #      0
+    #
+    # @example A command that fails
+    #   including_class.new.send('`'.to_sym, 'echo foo; exit 1') #=>
+    #    COMMAND
+    #      echo foo
+    #    OUTPUT
+    #      foo
+    #    EXITSTATUS
+    #      1
+    #
+    # @param command [String] the command to execute
+    #
+    # @return [String] the output of the command
+    #
+    def `(command)
+      puts "COMMAND\n  #{command}" if backtick_debug?
+      super.tap do |output|
+        if backtick_debug?
+          puts "OUTPUT\n"
+          output.lines { |l| puts "  #{l.chomp}" }
+          puts "EXITSTATUS\n  #{$CHILD_STATUS.exitstatus}\n"
+        end
+      end
+    end
+  end
+end

data/lib/create_github_release/change.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module CreateGithubRelease
+  # The release information needed to generate a changelog
+  #
+  # @api public
+  #
+  class Change
+    # Create a new release object
+    #
+    # @example
+    #   sha = 'f5e69d6'
+    #   subject = 'Release v1.0.0'
+    #
+    #   change = CreateGithubRelease::Change.new(sha, subject)
+    #   change.sha # => 'f5e69d6'
+    #   change.subject # => 'Release v1.0.0'
+    #
+    # @param sha [String] The sha of the change
+    # @param subject [String] The subject (aka description) of the change
+    #
+    def initialize(sha, subject)
+      @sha = sha
+      @subject = subject
+    end
+
+    # The commit sha of the change
+    #
+    # @example
+    #   sha = 'f5e69d6'
+    #   subject = 'Release v1.0.0'
+    #
+    #   change = CreateGithubRelease::Change.new(sha, subject))
+    #   change.sha # => 'f5e69d6'
+    #
+    # @return [String] The commit sha of the change
+    attr_reader :sha
+
+    # The subject (aka description) of the change
+    #
+    # @example
+    #   sha = 'f5e69d6'
+    #   subject = 'Release v1.0.0'
+    #
+    #   change = CreateGithubRelease::Change.new(sha, subject))
+    #   change.subject # => 'Release v1.0.0'
+    #
+    # @return [String] The subject (aka description) of the change
+    attr_reader :subject
+
+    # Compare two changes to see if they refer to the same change
+    #
+    # Two changes are equal if their `sha` and `subject` attributes are equal.
+    #
+    # @example
+    #   change1 = CreateGithubRelease::Change.new('f5e69d6', 'Release v1.0.0')
+    #   change2 = CreateGithubRelease::Change.new('f5e69d6', 'Release v1.0.0')
+    #   change3 = CreateGithubRelease::Change.new('9387be0', 'Release v1.0.0')
+    #   change4 = CreateGithubRelease::Change.new('f5e69d6', 'Release v2.0.0')
+    #   change5 = CreateGithubRelease::Change.new('9387be0', 'Release v2.0.0')
+    #   change1 == change2 #=> true
+    #   change1 == change3 #=> false
+    #   change1 == change4 #=> false
+    #   change1 == change5 #=> false
+    #
+    # @param other [CreateGithubRelease::Change] The other change to compare this change to
+    #
+    # @return [Boolean] true if the two changes are equal, false otherwise
+    def ==(other)
+      self.class == other.class && sha == other.sha && subject == other.subject
+    end
+  end
+end

data/lib/create_github_release/changelog.rb

@@ -22,16 +22,13 @@ module CreateGithubRelease
     #     * 07a1167 Release v0.1.0 (#1)
     #   EXISTING_CHANGELOG
     #
-    #   new_release_tag = 'v1.0.0'
-    #   new_release_date = Date.parse('2022-11-10')
-    #   new_release_description = <<~RELEASE
-    #     * f5e69d6 Release v1.0.0 (#4)
-    #     * 8fe479b Update documentation for initial GA release (#3)
-    #   RELEASE
+    #   next_release_description = <<~next_release_DESCRIPTION
+    #     ## v1.0.0 (2022-11-10)
     #
-    #   new_release = CreateGithubRelease::Release.new(new_release_tag, new_release_date, new_release_description)
+    #     * f5e69d6 Release v1.0.0 (#4)
+    #   next_release_DESCRIPTION
     #
-    #   changelog = CreateGithubRelease::Changelog.new(existing_changelog, new_release)
+    #   changelog = CreateGithubRelease::Changelog.new(existing_changelog, next_release_description)
     #
     #   expected_new_changelog = <<~CHANGELOG
     #     # Change Log
@@ -41,7 +38,6 @@ module CreateGithubRelease
     #     ## v1.0.0 (2022-11-10)
     #
     #     * f5e69d6 Release v1.0.0 (#4)
-    #     * 8fe479b Update documentation for initial GA release (#3)
     #
     #     ## v0.1.0 (2022-10-31)
     #
@@ -50,15 +46,15 @@ module CreateGithubRelease
     #
     #   changelog.front_matter # =>  "# Change Log\n\nList of changes in each release of this project."
     #   changelog.body # => "## v0.1.0 (2022-10-31)\n\n* 07a1167 Release v0.1.0 (#1)"
-    #   changelog.new_release # => #<CreateGithubRelease::Release:0x000000010761aac8 ...>
+    #   changelog.next_release_description # => "## v1.0.0 (2022-11-10)\n\n..."
     #   changelog.to_s == expected_new_changelog # => true
     #
     # @param existing_changelog [String] Contents of the changelog as a string
-    # @param new_release [CreateGihubRelease::Release] The new release to add to the changelog
+    # @param next_release_description [String] The description of the next release to add to the changelog
     #
-    def initialize(existing_changelog, new_release)
+    def initialize(existing_changelog, next_release_description)
       @existing_changelog = existing_changelog
-      @new_release = new_release
+      @next_release_description = next_release_description
 
       @lines = existing_changelog.lines.map(&:chomp)
     end
@@ -75,9 +71,9 @@ module CreateGithubRelease
     #     ...
     #   CHANGELOG
     #
-    #   new_release = CreateGithubRelease::Release.new('v0.1.0', Date.today, '...')
+    #   next_release_description = '## v1.0.0\n\n* 8374b31 Add FizzBuzz'
     #
-    #   changelog = CreateGithubRelease::Changelog.new(changelog_text, new_release)
+    #   changelog = CreateGithubRelease::Changelog.new(changelog_text, next_release_description)
     #   changelog.front_matter # => "This is the front matter\n"
     #
     # @example Changelog without front matter
@@ -86,26 +82,26 @@ module CreateGithubRelease
     #     ...
     #   CHANGELOG
     #
-    #   new_release = CreateGithubRelease::Release.new('v0.1.0', Date.today, '...')
+    #   next_release_description = '## v1.0.0\n\n* 8374b31 Add FizzBuzz'
     #
-    #   changelog = CreateGithubRelease::Changelog.new(changelog_text, new_release)
+    #   changelog = CreateGithubRelease::Changelog.new(changelog_text, next_release_description)
     #   changelog.front_matter # => ""
     #
     # @example An empty changelog
     #   changelog_text = <<~CHANGELOG
     #   CHANGELOG
     #
-    #   new_release = CreateGithubRelease::Release.new('v0.1.0', Date.today, '...')
+    #   next_release_description = '## v1.0.0\n\n* 8374b31 Add FizzBuzz'
     #
-    #   changelog = CreateGithubRelease::Changelog.new(changelog_text, new_release)
+    #   changelog = CreateGithubRelease::Changelog.new(changelog_text, next_release_description)
     #   changelog.front_matter # => ""
     #
     # @example An empty changelog
     #   changelog_text = ""
     #
-    #   new_release = CreateGithubRelease::Release.new('v0.1.0', Date.today, '...')
+    #   next_release_description = '## v1.0.0\n\n* 8374b31 Add FizzBuzz'
     #
-    #   changelog = CreateGithubRelease::Changelog.new(changelog_text, new_release)
+    #   changelog = CreateGithubRelease::Changelog.new(changelog_text, next_release_description)
     #   changelog.front_matter # => ""
     #
     # @return [String] The front matter of the changelog
@@ -124,9 +120,9 @@ module CreateGithubRelease
     #     ...
     #   CHANGELOG
     #
-    #   new_release = CreateGithubRelease::Release.new('v0.1.0', Date.today, '...')
+    #   next_release_description = '## v1.0.0\n\n* 8374b31 Add FizzBuzz'
     #
-    #   changelog = CreateGithubRelease::Changelog.new(changelog_text, new_release)
+    #   changelog = CreateGithubRelease::Changelog.new(changelog_text, next_release_description)
     #   changelog.body # => "## v0.1.0\n..."
     #
     # @example Changelog without front matter
@@ -135,9 +131,9 @@ module CreateGithubRelease
     #     ...
     #   CHANGELOG
     #
-    #   new_release = CreateGithubRelease::Release.new('v0.1.0', Date.today, '...')
+    #   next_release_description = '## v1.0.0\n\n* 8374b31 Add FizzBuzz'
     #
-    #   changelog = CreateGithubRelease::Changelog.new(changelog_text, new_release)
+    #   changelog = CreateGithubRelease::Changelog.new(changelog_text, next_release_description)
     #   changelog.body # => "## v0.1.0\n..."
     #
     # @example Changelog without a body
@@ -145,26 +141,26 @@ module CreateGithubRelease
     #     This is the front matter
     #   CHANGELOG
     #
-    #   new_release = CreateGithubRelease::Release.new('v0.1.0', Date.today, '...')
+    #   next_release_description = '## v1.0.0\n\n* 8374b31 Add FizzBuzz'
     #
-    #   changelog = CreateGithubRelease::Changelog.new(changelog_text, new_release)
+    #   changelog = CreateGithubRelease::Changelog.new(changelog_text, next_release_description)
     #   changelog.body # => ""
     #
     # @example An empty changelog (new line only)
     #   changelog_text = <<~CHANGELOG
     #   CHANGELOG
     #
-    #   new_release = CreateGithubRelease::Release.new('v0.1.0', Date.today, '...')
+    #   next_release_description = '## v1.0.0\n\n* 8374b31 Add FizzBuzz'
     #
-    #   changelog = CreateGithubRelease::Changelog.new(changelog_text, new_release)
+    #   changelog = CreateGithubRelease::Changelog.new(changelog_text, next_release_description)
     #   changelog.body # => ""
     #
     # @example An empty changelog (empty string)
     #   changelog_text = ""
     #
-    #   new_release = CreateGithubRelease::Release.new('v0.1.0', Date.today, '...')
+    #   next_release_description = '## v1.0.0\n\n* 8374b31 Add FizzBuzz'
     #
-    #   changelog = CreateGithubRelease::Changelog.new(changelog_text, new_release)
+    #   changelog = CreateGithubRelease::Changelog.new(changelog_text, next_release_description)
     #   changelog.body # => ""
     #
     # @return [String] The body of the existing changelog
@@ -184,16 +180,14 @@ module CreateGithubRelease
     #
     attr_reader :existing_changelog
 
-    # The new release to add to the changelog
+    # The description of the new release to add to the changelog
     #
     # @example
-    #   changelog.new_release.tag # => 'v1.0.0'
-    #   changelog.new_release.date # => #<Date: 2018-06-30>
-    #   changelog.new_release.description # => "[Full Changelog](...)..."
+    #   changelog.next_release_description # => "# v1.0.0 - 2018-06-30\n\n[Full Changelog](...)..."
     #
-    # @return [CreateGithubRelease::Release] The new release to add to the changelog
+    # @return [String] The description of the new release to add to the changelog
     #
-    attr_reader :new_release
+    attr_reader :next_release_description
 
     # The changelog with the new release
     #
@@ -204,9 +198,7 @@ module CreateGithubRelease
     #     ...
     #   CHANGELOG
     #
-    #   new_release = CreateGithubRelease::Release.new(
-    #     'v1.0.0', Date.parse('2022-11-08'), '...release description...'
-    #   )
+    #   next_release_description = '## v1.0.0\n\n* 8374b31 Add FizzBuzz'
     #
     #   expected_changelog = <<~CHANGELOG
     #     This is the front matter
@@ -218,7 +210,7 @@ module CreateGithubRelease
     #     ...
     #   CHANGELOG
     #
-    #   changelog = CreateGithubRelease::Changelog.new(changelog_text, new_release)
+    #   changelog = CreateGithubRelease::Changelog.new(changelog_text, next_release_description)
     #
     #   changelog.to_s == expected_changelog # => true
     #
@@ -228,9 +220,7 @@ module CreateGithubRelease
     #     ...
     #   CHANGELOG
     #
-    #   new_release = CreateGithubRelease::Release.new(
-    #     'v1.0.0', Date.parse('2022-11-08'), '...release description...'
-    #   )
+    #   next_release_description = '## v1.0.0\n\n* 8374b31 Add FizzBuzz'
     #
     #   expected_changelog = <<~CHANGELOG
     #     ## v1.0.0 (2022-11-08)
@@ -240,7 +230,7 @@ module CreateGithubRelease
     #     ...
     #   CHANGELOG
     #
-    #   changelog = CreateGithubRelease::Changelog.new(changelog_text, new_release)
+    #   changelog = CreateGithubRelease::Changelog.new(changelog_text, next_release_description)
     #
     #   changelog.to_s == expected_changelog # => true
     #
@@ -249,9 +239,7 @@ module CreateGithubRelease
     #     This is the front matter
     #   CHANGELOG
     #
-    #   new_release = CreateGithubRelease::Release.new(
-    #     'v1.0.0', Date.parse('2022-11-08'), '...release description...'
-    #   )
+    #   next_release_description = '## v1.0.0\n\n* 8374b31 Add FizzBuzz'
     #
     #   expected_changelog = <<~CHANGELOG
     #     This is the front matter
@@ -260,7 +248,7 @@ module CreateGithubRelease
     #     ...release description...
     #   CHANGELOG
     #
-    #   changelog = CreateGithubRelease::Changelog.new(changelog_text, new_release)
+    #   changelog = CreateGithubRelease::Changelog.new(changelog_text, next_release_description)
     #
     #   changelog.to_s == expected_changelog # => true
     #
@@ -271,9 +259,7 @@ module CreateGithubRelease
     #     ...
     #   CHANGELOG
     #
-    #   new_release = CreateGithubRelease::Release.new(
-    #     'v1.0.0', Date.parse('2022-11-08'), ''
-    #   )
+    #   next_release_description = '## v1.0.0\n\n* 8374b31 Add FizzBuzz'
     #
     #   expected_changelog = <<~CHANGELOG
     #     This is the front matter
@@ -284,23 +270,32 @@ module CreateGithubRelease
     #     ...
     #   CHANGELOG
     #
-    #   changelog = CreateGithubRelease::Changelog.new(changelog_text, new_release)
+    #   changelog = CreateGithubRelease::Changelog.new(changelog_text, next_release_description)
     #
     #   changelog.to_s == expected_changelog # => true
     #
     # @return [String] The changelog with the new release details
     #
     def to_s
-      String.new.tap do |changelog|
-        changelog << "#{front_matter}\n\n" unless front_matter.empty?
-        changelog << release_header
-        changelog << release_description
-        changelog << "\n#{body}\n" unless body.empty?
-      end
+      formatted_front_matter + next_release_description + formatted_body
     end
 
     private
 
+    # The front matter formatted to insert into the changelog
+    # @return [String] The front matter formatted to insert into the changelog
+    # @api private
+    def formatted_front_matter
+      front_matter.empty? ? '' : "#{front_matter}\n\n"
+    end
+
+    # The body formatted to insert into the changelog
+    # @return [String] The body formatted to insert into the changelog
+    # @api private
+    def formatted_body
+      body.empty? ? '' : "\n#{body}\n"
+    end
+
     # The index of the line in @lines where the front matter begins
     # @return [Integer] The index of the line in @lines where the front matter begins
     # @api private
@@ -345,20 +340,6 @@ module CreateGithubRelease
         end
     end
 
-    # The release header to output in the changelog
-    # @return [String] The release header to output in the changelog
-    # @api private
-    def release_header
-      "## #{new_release.tag} (#{new_release.date.strftime('%Y-%m-%d')})\n"
-    end
-
-    # The release description to output in the changelog
-    # @return [String] The release description to output in the changelog
-    # @api private
-    def release_description
-      new_release.description.empty? ? '' : "\n#{new_release.description.chomp}\n"
-    end
-
     # Line number where the body of the changelog starts
     # @return [Integer] Line number where the body of the changelog starts
     # @api private