pr_releasenotes 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 950d6b6e778e173335598ed4574806b6bbd3db28575eccf5a3c40d33fac844c7
-  data.tar.gz: 9cd54bffe0f6d5ea60c3058f7e3cba1e7b09f29fe14da8f532398f24937f5ce0
+  metadata.gz: 78e490c7b05492ae9c389da01992071a95f386cd79e58775ca150207ed343217
+  data.tar.gz: 4d076be623487de18e41bd0d65267333c2925d18f5f70d4b256f14c14ab6bb8f
 SHA512:
-  metadata.gz: fb18ff14b3a0a87bbe379d4a8c4b5abedd6ece5d660d147af49b8caddbd3ee18c81a6d0dad566111a71a5939086ae313bdd215da48c13cb3ceff19799bc076a4
-  data.tar.gz: 2f12d003a12abdb59025ea5d1e200b16625548d85c141d5ba18f7d804df47e7a2c96316e63e7e2b9c028550949d8dc883532e5ac7ce498b36dfe2763040757c0
+  metadata.gz: 02ada146643812fc9c0bb24610ab7b093c7c70560451a2922bce31fb4861bbcffbacdb922fc9edcb4866e71857a3a2dc195a769871bc044dc5446a1289d4df3a
+  data.tar.gz: 85a5b2df377cc5974d2a834110da4bca1bf62c18aad92077825cc4994b111c44d8cab34eddf4f4f3c9d1f9d5b75026b2dff54834465bf36c1f8a11c7b3c690cf

data/README.md

@@ -10,11 +10,11 @@ will generate release notes from your latest release tag to the tip of the maste
 
 ## Why this tool vs others
 
-There are quite a few online tools for generating release notes based on github history, but all the ones I've found rely on commit messages. This makes them inflexible, since it would require rewriting commit history in order to make any changes to the generated notes.
+There are quite a few online tools for generating release notes based on github history, but all the ones I've found rely on commit messages. This makes them inflexible, since it would require rewriting commit history in order to make any changes to the generated notes. In addition, using commit messages forces irrelevant information such as `fixed typo`, `reverted incorrect commit`, and `updated tests/docs` into the release notes.
 
-This tool uses the pull request descriptions, so the release notes for any version can be updated at any time by simply updating the corresponding pull request's description and rerunning this tool.
+This tool uses pull request descriptions, so the release notes for any version can be updated at any time by simply updating the corresponding pull request's description and rerunning this tool. In addition, pull request descriptions can have a separate brief and focused section to expose only the necessary information into the release notes. 
 
-Secondly, this tool provides the additional option to post the release notes back to the github releases page.
+Finally, this tool provides the additional option to post the release notes back to the github releases page.
 
 ## Installation
 
@@ -34,28 +34,26 @@ Or install it yourself as:
 
 ## Usage
 
-The minimum configuration necessary to run the tool is the repo, github token and a start release tag:
+The minimum configuration necessary to run the tool is the repo, github token and a starting tag or commit sha:
 
-    $ pr_releasenotes --repo <user/repo> --token <token> --start <latest_tagged_release>
+    $ pr_releasenotes --repo <user/repo> --token <token> --start <start_tag|sha>
 
-Additional options can be specified either by passing a yaml configuration to the included executable:
+Additional options can be specified either by passing a yaml configuration to the executable:
 
-    $ pr_releasenotes --config <config.yaml> --token <token> --start <start_version> --end <end_version> --branch <non-default branch>
+    $ pr_releasenotes --config <config.yaml> --token <token> --start <start_tag|sha> --end <end_tag|sha> --branch <non-default branch>
 
 or by invoking the gem directly from ruby code:
 
 ```ruby
 require 'pr_releasenotes'
 
-include PrReleasenotes
-
 PrReleasenotes.configure do |config|
   config.repo('user/repo')
   config.token('github_token')
   config.parse_args(ARGV)
 end
 
-ReleaseNotes.new.run
+PrReleasenotes.run
 ```
 
 Get a brief usage summary by running
@@ -65,6 +63,27 @@ Get a brief usage summary by running
 
 See the [examples folder](examples) for some sample yaml configuration files.
 
+### Running as part of a release build
+
+This tool can be invoked right after a release build to automatically add release notes to a newly created release.
+
+#### Regular releases
+
+For regular releases where a previous release already exists, and a new release is being created, this tool can be invoked after the release is built by using the following form:
+
+    $ pr_releasenotes --repo <user/repo> --token <token> --end <current_release_tag>
+    
+The tool will set the start_tag to the latest tagged release prior to the current one and generate release notes from that release to the current one.
+
+#### Initial release
+
+For the initial release from a repo, there is no previous release, so the tool must be run with an explicit start sha or tag:
+
+    $ pr_releasenotes --repo <user/repo> --token <token> --start <commit_sha> --end <current_release_tag>
+ 
+Both the `--start` and `--end` parameters support sha values as well as tags, so release notes can be generated between any two tags or commits.
+
+
 ### Github token permissions
 
 This tool does require a github token since it accesses the github api. However any token created should have only as many, or rather as few, permissions as needed.

data/examples/custom_config.yaml

@@ -4,7 +4,7 @@
 #
 
 # Name of your repo in user/repo format
-repo:
+# repo:
 
 # Release notes parsing options. Note that comments will always get stripped
 
@@ -14,6 +14,7 @@ relnotes_group: 1 # group to capture from the regex
 
 # Enable categorization
 categorize: true
+relnotes_hdr_prefix: '### '
 
 # Update to your own jira server
 jira_baseurl: 'https://issues.apache.org/jira/browse/'

data/examples/default_config.yaml

@@ -1,5 +1,6 @@
 #
-# Sample configuration containing default configuration values
+# Sample configuration containing default values.
+# At least one of the following options must be uncommented to use this configuration file
 #
 
 # Name of your repo in user/repo format. Defaults to nil and must be overridden in the yaml or on the cmd line.
@@ -8,19 +9,19 @@
 # Release notes will be pulled from PRs merged to this branch. Defaults to master.
 # branch: master
 
-# Version range from which release notes should be gathered
+# Tag range from which release notes should be gathered
 
-# Extract pull requests starting from this version. Defaults to nil for latest published release. Override if
+# Extract pull requests starting from this tag. Defaults to nil for latest published release. Override if
 # there are no published releases yet.
 # Note: Although this parameter is listed here for completeness, this will likely be specified on the cmd line
 # since its value will vary with each release.
-# start_version:
+# start_tag:
 
 # Defaults to nil for latest commit. nil will also skip the creation of a github release
-# end_version:
+# end_tag:
 
 # If all your tags have a common prefix, add that here, and use just the varying suffix as the 
-# start/end version arguments. Defaults to blank.
+# start/end tag arguments. Defaults to blank.
 # tag_prefix: 
 
 # Short sha uniqueness threshold. Shas shorter than this may collide with other commits. When searching for
@@ -37,7 +38,9 @@
 
 # Release notes parsing options. Note that comments will always get stripped
 
-# By default, the entire PR description will be used.
+# By default, only the PR titles will be used, so match nothing from the description
+# relnotes_regex: '/.\A/'
+# To use the entire PR description instead
 # relnotes_regex: '/.*/m'
 
 # group to capture from the above regex
@@ -56,7 +59,7 @@
 # category_default: '<!--99-->Other'
 
 # Add a prefix to the release notes items
-# relnotes_hdr_prefix: '### '
+# relnotes_hdr_prefix: '* '
 
 
 # Optional jira url to auto link all strings matching a jira ticket pattern

data/exe/pr_releasenotes

@@ -2,10 +2,8 @@
 
 require 'pr_releasenotes'
 
-include PrReleasenotes
-
 PrReleasenotes.configure do |config|
   config.parse_args(ARGV)
 end
 
-ReleaseNotes.new.run
+PrReleasenotes.run

data/lib/pr_releasenotes/configuration.rb

@@ -21,7 +21,7 @@ module PrReleasenotes
     require 'to_regexp'
     require "pr_releasenotes/version"
 
-    attr_accessor :repo, :token, :tag_prefix, :min_sha_size, :start_version, :end_version,
+    attr_accessor :repo, :token, :tag_prefix, :min_sha_size, :start_tag, :end_tag,
                   :branch, :include_all_prs, :github_release, :relnotes_group,
                   :categorize, :category_prefix, :category_default, :relnotes_hdr_prefix,
                   :jira_baseurl, :auto_paginate, :log
@@ -39,9 +39,9 @@ module PrReleasenotes
       @tag_prefix = ''
       # Short sha uniqueness threshold. Shas shorter than this may collide with other commits
       @min_sha_size = 7
-      # Version range from which release notes should be gathered
-      @start_version = nil  # nil for latest released version
-      @end_version = nil    # nil for latest commit. nil will skip the creation of a github release
+      # Tag range from which release notes should be gathered
+      @start_tag = nil  # nil for latest released tag
+      @end_tag = nil    # nil for latest commit. nil will skip the creation of a github release
       # Release notes will be pulled from PRs merged to this branch
       @branch = 'master'
       # Whether to include even PRs without explicit release notes
@@ -50,8 +50,8 @@ module PrReleasenotes
       @github_release = false
 
       # Release notes parsing options. Note that comments will always get stripped
-      # Use .* with group 0 to use the entire PR description as the notes
-      @relnotes_regex = /.*/m
+      # By default, only the PR titles will be used, so match nothing from the description
+      @relnotes_regex = /.\A/
       @relnotes_group = 0 # group to capture from the regex
 
       # Set categorization options
@@ -60,7 +60,7 @@ module PrReleasenotes
       # PRs without categories will get included into this default category
       @category_default = '<!--99-->Other'
       # Add a prefix to the release notes items
-      @relnotes_hdr_prefix = '### '
+      @relnotes_hdr_prefix = '* '
 
       # Optional jira url to auto link all strings matching a jira ticket pattern
       # Set to nil to skip auto link
@@ -88,13 +88,17 @@ module PrReleasenotes
 
         opts.separator ''
         opts.on('-c', '--config <config.yaml>', 'Yaml configuration') do |config|
-          YAML.load_file(config).each do |k, v|
-            begin
-              # Try calling public setter for this option
-              public_send("#{k}=",  v)
-            rescue NoMethodError => e
-              raise "#{e.message} caused by (#{config}) Invalid key '#{k}'"
+          begin
+            YAML.load_file(config).each do |k, v|
+              begin
+                # Try calling public setter for this option
+                public_send("#{k}=",  v)
+              rescue NoMethodError => e
+                raise "#{e.message} caused by (#{config}) Invalid key '#{k}'"
+              end
             end
+          rescue StandardError => e
+            raise "Unable to parse #{config} caused by #{e.message}"
           end
         end
 
@@ -107,11 +111,11 @@ module PrReleasenotes
         end
 
         opts.separator ''
-        opts.on('-s', '--start  <version>', 'Get release notes from this version tag. (Default: latest release)') do |version|
-          @start_version = version
+        opts.on('-s', '--start  <tag|sha>', 'Get release notes starting from this tag or sha. (Default: latest release)') do |tag|
+          @start_tag = tag
         end
-        opts.on('-e', '--end    <version>', 'Get release notes till this version tag. (Default: latest commit, skips creating github release)') do |version|
-          @end_version = version
+        opts.on('-e', '--end    <tag|sha>', 'Get release notes till this tag or sha. (Default: latest commit, skips creating github release)') do |tag|
+          @end_tag = tag
         end
         opts.on('-b', '--branch <branchname>', 'Use pull requests to this branch. (Default: master)') do |branch|
           @branch = branch
@@ -138,6 +142,10 @@ module PrReleasenotes
       end
 
       opt_parser.parse!(args)
+      if @github_release && @end_tag.nil?
+        log.error "Cannot post to github without an end tag. Specify an end_tag or skip posting to github."
+        exit 1
+      end
     end
 
   end

data/lib/pr_releasenotes/version.rb

@@ -1,3 +1,3 @@
 module PrReleasenotes
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/lib/pr_releasenotes.rb

@@ -4,6 +4,10 @@ require "pr_releasenotes/configuration"
 # post to github releases
 module PrReleasenotes
 
+  def self.run
+    ReleaseNotes.new.run
+  end
+
   class ReleaseNotes
 
     require 'octokit'
@@ -25,76 +29,100 @@ module PrReleasenotes
     end
 
     def run
-      # Infer start version if necessary
-      set_start_version
-      log.info "Retrieving release notes between #{config.start_version} and #{config.end_version.nil? ? 'now' : config.end_version} on branch #{config.branch}"
-      # Get commits between versions
-      commits_for_versions = get_commits_for_versions
+      # Infer start tag if necessary
+      set_start_tag
+      log.info "Retrieving release notes between #{config.start_tag} and #{config.end_tag.nil? ? 'now' : config.end_tag} on branch #{config.branch}"
+      # First get a list of all tags on github
+      get_all_tags
+      # Get commits between start and end tags
+      commits_for_tags = get_commits_for_tags
       # Get merged PRs for those commits
-      prs = get_prs_for_commits(commits_for_versions)
+      prs = get_prs_for_commits(commits_for_tags)
       # Get release notes from those PRs
       notes_by_pr = get_releasenotes_for_prs(prs)
       # Convert to a single string
       notes_str = get_notes_str(notes_by_pr)
-      log.info "Release Notes:\n\n#{notes_str}"
       # Optionally post to github as a new or updated release
-      post_to_github(notes_str) if config.github_release
+      if config.github_release
+        post_to_github(notes_str)
+      else
+        log.info "Release Notes:\n\n#{notes_str}"
+      end
     end
 
-    def set_start_version
-      if config.start_version.nil?
-        # If start version isn't set, try to infer from the latest github release
+    def get_all_tags
+      @all_tags = git_client.tags(config.repo)
+    end
+
+    def set_start_tag
+      if config.start_tag.nil?
+        # If start tag isn't set, try to infer from the latest github release
+
+        # First get the current tag or branch
+        tag_or_branch = config.end_tag.nil? ? config.branch : config.end_tag
         begin
           releases = git_client.releases(config.repo)
                          .sort_by { |release| release[:created_at]}.reverse # order by create date, newest first
           release = releases.find { |release|
             unless release[:draft]
-              # is a pre-release or published release, so check if this release is an ancestor of the current branch
-              # "diverged" indicates it was on a different branch & "ahead" indicates it's after the
-              # specified end_version, so neither can be used as a start_version
-              # "behind" indicates it's an ancestor and can be used as a start_version,
-              git_client.compare(config.repo, config.branch, release[:tag_name])[:status] == 'behind'
+              # is a pre-release or published release, so check if this release is an ancestor of the end_tag
+              # or the current branch
+
+              # "diverged" indicates it was on a different branch & "behind" indicates it's after the
+              # specified end_tag, so neither can be used as a start_tag
+              # "ahead" indicates it's an ancestor and can be used as a start_tag
+              git_client.compare(config.repo, release[:tag_name], tag_or_branch)[:status] == 'ahead'
             end
           }
-          config.start_version = release[:tag_name].sub /#{config.tag_prefix}/, ''
+          config.start_tag = release[:tag_name].sub /#{config.tag_prefix}/, ''
+        rescue Octokit::Unauthorized => e
+          throw e
         rescue StandardError
-          log.error "No published releases found in #{config.repo} for branch #{config.branch}. Specify a start version explicitly."
+          log.error "No published releases found in #{config.repo} on or before #{tag_or_branch}. Either publish a release first, or specify a start tag or commit sha explicitly."
           exit 1
         end
       end
     end
 
-    def get_date_for_version(tags, version)
-      # From the tags, find the tag for the specified version and get its sha
-      tagname = "#{config.tag_prefix}#{version}"
-      tag = tags.select {|tag| tag.name == tagname }.shift
-      tag.nil? and log.error "No commit found with tag name #{tagname}\n" and exit 1
-      tag_sha = tag[:commit][:sha]
+    def get_date_for_tag(tags, tag_str)
+      tagname = "#{config.tag_prefix}#{tag_str}"
+      unless tags.empty?
+        # From existing tags, find the tag for the specified tag_str and get its sha
+        tag = tags.select {|tag| tag.name == tagname }.shift
+        sha = tag[:commit][:sha] unless tag.nil?
+      end
+
+      unless sha
+        # No tags exist, or specified tag_str wasn't found. Try treating the tag_str as a commit sha
+        sha = tag_str
+      end
 
-      # get the commit for that sha, and the date for that commit.
-      commit = git_client.commit( config.repo, tag_sha )
+      begin
+        # get the commit for that sha, and the date for that commit.
+        commit = git_client.commit( config.repo, sha )
+      rescue Octokit::Error
+        log.error "No commit found with tag name #{tagname} or sha #{tag_str}\n" and exit 1
+      end
       commit[:commit][:author][:date]
     end
 
-    def get_commits_for_versions
+    def get_commits_for_tags
 
       # The github api does not directly support getting a list of commits since a tag was applied.
       # To work around this, we instead:
 
-      # get a list of tags
-      tags = git_client.tags(config.repo)
-      # get the corresponding date for the tag corresponding to the start version
-      start_date = get_date_for_version tags, config.start_version
-      if config.end_version.nil?
+      # get the corresponding date for the tag corresponding to the start tag
+      start_date = get_date_for_tag @all_tags, config.start_tag
+      if config.end_tag.nil?
         # and get a list of commits since the start_date on the configured branch
-        commits = git_client.commits_since( config.repo, start_date, config.branch)
-        log.info "Got #{commits.length} commits on #{config.branch} between #{config.start_version}(#{start_date}) and now"
+        commits = git_client.commits_since config.repo, start_date, config.branch
+        log.info "Got #{commits.length} commits on #{config.branch} between #{config.start_tag}(#{start_date}) and now"
       else
-        # and for the end version if not nil
-        end_date = get_date_for_version tags, config.end_version
+        # and the date for the end tag if not nil
+        end_date = get_date_for_tag @all_tags, config.end_tag
         # and get a list of commits between the start/end dates on the configured branch
-        commits = git_client.commits_between( config.repo, start_date, end_date, config.branch)
-        log.info "Got #{commits.length} commits on #{config.branch} between #{config.start_version}(#{start_date}) and #{config.end_version}(#{end_date})"
+        commits = git_client.commits_between config.repo, start_date, end_date, config.branch
+        log.info "Got #{commits.length} commits on #{config.branch} between #{config.start_tag}(#{start_date}) and #{config.end_tag}(#{end_date})"
       end
       log.debug "Commits: " + commits.map(&:sha).join(',')
       commits
@@ -128,11 +156,13 @@ module PrReleasenotes
     def get_releasenotes_for_prs(prs)
       notes = prs.reduce([]) { |notes, pr|
         # Get release notes section
-        body = pr[:body].strip.slice(config.relnotes_regex, config.relnotes_group)
-        unless body.nil?
+        unless pr[:body].nil?
           # Release notes exist for this PR, so do some cleanup
-          body.gsub! /^<!--.+?(?=-->)-->/m, '' # strip off (multiline) comments
-          body.gsub! /^\r?\n/, ''             # and empty lines
+          body = pr[:body].strip.slice(config.relnotes_regex, config.relnotes_group)
+          unless body.nil?
+            body.gsub! /^<!--.+?(?=-->)-->/m, '' # strip off (multiline) comments
+            body.gsub! /^\r?\n/, ''             # and empty lines
+          end
         end
         # For PRs without release notes, add just the title
         notes << {:title => pr[:title], :date => pr[:closed_at], :prnum => pr[:number], :body => body}
@@ -146,14 +176,14 @@ module PrReleasenotes
         # Regex: negative lookbehind(?<!...) for jira_prefix or beginning of link markdown,
         # followed by jira ticket pattern, followed by negative lookahead(?!...) for end of
         # link markdown
-        #              |   neg lookbehind    |  | tkt pattern |  |neg lookahead|
+        #              |        neg lookbehind        |  | tkt pattern |  |neg lookahead |
         notes_str.gsub!(/(?<!#{config.jira_baseurl}|\[)\b([A-Z]{2,}-\d+)\b(?![^\[\]]*\]\()/, "[\\1](#{config.jira_baseurl}\\1)")
       end
       notes_str
     end
 
     def get_notes_str(notes_by_pr)
-      notes_str = "Changes since #{config.tag_prefix}#{config.start_version}:\r\n"
+      notes_str = "Changes since #{config.tag_prefix}#{config.start_tag}:\r\n"
       if config.categorize
         # Categorize the notes, using the regex as the category names
         notes = notes_by_pr.reduce({}) { | notes, pr_note |
@@ -192,25 +222,38 @@ module PrReleasenotes
       else
         # No categorization required, use notes as is
         notes_str << notes_by_pr.reduce("") { | str, note |
-          str << "#{config.relnotes_hdr_prefix}#{note[:title]} [##{note[:prnum]}](https://github.com/#{config.repo}/pull/#{note[:prnum]} \"Merged #{note[:date]}\")\r\n#{note[:body]}\r\n"
+          str << "#{config.relnotes_hdr_prefix}#{note[:title]} [##{note[:prnum]}](https://github.com/#{config.repo}/pull/#{note[:prnum]} \"Merged #{note[:date]}\")\r\n"
+          str << "#{note[:body]}\r\n" unless note[:body].nil? || note[:body].empty?
+          str
         }
       end
       jiraize notes_str
     end
 
     def post_to_github(notes_str)
-      unless config.end_version.nil?
-        tag_name = "#{config.tag_prefix}#{config.end_version}"
+      unless config.end_tag.nil?
+        tag_name = "#{config.tag_prefix}#{config.end_tag}"
+        if @all_tags.find { |tag| tag[:name] == tag_name }.nil?
+          raise "#{tag_name} is not a valid end_tag. Releases can only be created or updated for existing end_tags."
+        end
         begin
           release = git_client.release_for_tag(config.repo, tag_name)
           # Found existing release, so update it
-          log.info "Found existing #{release.draft? ? 'draft ' : ''}#{release.prerelease? ? 'pre-' : ''}release with tag #{tag_name} at #{release.html_url} with body: #{release.body}"
-          release = git_client.update_release(release.url, { :name => tag_name, :body => notes_str, :draft => false, :prerelease => true, :target_commitish => config.branch })
-          log.info "Updated pre-release #{release.id} at #{release.html_url} with body #{notes_str}"
+          log.info "Found existing #{release.draft? ? 'draft ' : ''}#{release.prerelease? ? 'pre-' : ''}release with tag #{tag_name} at #{release.html_url}#{release.body.nil? || release.body.empty? ? '' : " with body: #{release.body}"}"
+          begin
+            release = git_client.update_release(release.url, { :name => tag_name, :body => notes_str, :draft => false, :prerelease => true })
+            log.info "Updated pre-release #{release.id} at #{release.html_url} with body\n\n #{notes_str}"
+          rescue Octokit::NotFound
+            raise "Unable to post release to github. Ensure your token has the right permissions."
+          end
         rescue Octokit::NotFound
-          # no existing release, so create a new one
-          release = git_client.create_release(config.repo, tag_name, { :name => tag_name, :body => notes_str, :draft => false, :prerelease => true, :target_commitish => config.branch })
-          log.info "Created pre-release #{release.id} at #{release.html_url} with body #{notes_str}"
+          # no existing release, so try create a new one for this end_tag
+          begin
+            release = git_client.create_release(config.repo, tag_name, { :name => tag_name, :body => notes_str, :draft => false, :prerelease => true })
+            log.info "Created pre-release #{release.id} at #{release.html_url} with body\n\n #{notes_str}"
+          rescue Octokit::NotFound
+            raise "Unable to post release to github. Ensure your token has the right permissions."
+          end
         end
       end
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pr_releasenotes
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - arvindth
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-04-28 00:00:00.000000000 Z
+date: 2019-05-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler