github_changelog_generator 1.15.0.pre.alpha → 1.16.0

data/Rakefile

@@ -9,12 +9,11 @@ require "fileutils"
 require "overcommit"
 
 RuboCop::RakeTask.new
-RSpec::Core::RakeTask.new(:rspec)
+RSpec::Core::RakeTask.new
 
 desc "When releasing the gem, re-fetch latest cacert.pem from curl.haxx.se. Developer task."
 task :update_ssl_ca_file do
-  `pushd lib/github_changelog_generator/ssl_certs && curl --remote-name --time-cond cacert.pem https://curl.haxx.se/ca/cacert.pem && popd`
+  `pushd lib/github_changelog_generator/ssl_certs && curl --remote-name --time-cond cacert.pem https://curl.se/ca/cacert.pem && popd`
 end
 
-task checks: %i[rubocop rspec]
-task default: %i[rubocop rspec]
+task default: %i[rubocop spec]

data/bin/git-generate-changelog

@@ -1,4 +1,4 @@
-#! /usr/bin/env ruby
+#!/usr/bin/env ruby
 # frozen_string_literal: true
 
 require_relative "../lib/github_changelog_generator"

data/lib/github_changelog_generator.rb

@@ -22,22 +22,26 @@ require "github_changelog_generator/reader"
 module GitHubChangelogGenerator
   # Main class and entry point for this script.
   class ChangelogGenerator
-    # Class, responsible for whole change log generation cycle
+    # Class, responsible for whole changelog generation cycle
     # @return initialised instance of ChangelogGenerator
     def initialize
       @options = Parser.parse_options
       @generator = Generator.new @options
     end
 
-    # The entry point of this script to generate change log
+    # The entry point of this script to generate changelog
     # @raise (ChangelogGeneratorError) Is thrown when one of specified tags was not found in list of tags.
     def run
       log = @generator.compound_changelog
 
-      output_filename = @options[:output].to_s
-      File.open(output_filename, "wb") { |file| file.write(log) }
-      puts "Done!"
-      puts "Generated log placed in #{Dir.pwd}/#{output_filename}"
+      if @options.write_to_file?
+        output_filename = @options[:output].to_s
+        File.open(output_filename, "wb") { |file| file.write(log) }
+        puts "Done!"
+        puts "Generated log placed in #{Dir.pwd}/#{output_filename}"
+      else
+        puts log
+      end
     end
   end
 end

data/lib/github_changelog_generator/generator/entry.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+require "github_changelog_generator/generator/section"
+
+module GitHubChangelogGenerator
+  # This class generates the content for a single changelog entry. An entry is
+  # generally either for a specific tagged release or the collection of
+  # unreleased changes.
+  #
+  # An entry is comprised of header text followed by a series of sections
+  # relating to the entry.
+  #
+  # @see GitHubChangelogGenerator::Generator
+  # @see GitHubChangelogGenerator::Section
+  class Entry
+    attr_reader :content
+
+    def initialize(options = Options.new({}))
+      @content = ""
+      @options = Options.new(options)
+    end
+
+    # Generates log entry with header and body
+    #
+    # @param [Array] pull_requests List or PR's in new section
+    # @param [Array] issues List of issues in new section
+    # @param [String] newer_tag_name Name of the newer tag. Could be nil for `Unreleased` section.
+    # @param [String] newer_tag_link Name of the newer tag. Could be "HEAD" for `Unreleased` section.
+    # @param [Time] newer_tag_time Time of the newer tag
+    # @param [Hash, nil] older_tag_name Older tag, used for the links. Could be nil for last tag.
+    # @return [String] Ready and parsed section content.
+    def generate_entry_for_tag(pull_requests, issues, newer_tag_name, newer_tag_link, newer_tag_time, older_tag_name) # rubocop:disable Metrics/ParameterLists
+      github_site = @options[:github_site] || "https://github.com"
+      project_url = "#{github_site}/#{@options[:user]}/#{@options[:project]}"
+
+      create_sections
+
+      @content = generate_header(newer_tag_name, newer_tag_link, newer_tag_time, older_tag_name, project_url)
+      @content += generate_body(pull_requests, issues)
+      @content
+    end
+
+    def line_labels_for(issue)
+      labels = if @options[:issue_line_labels] == ["ALL"]
+                 issue["labels"]
+               else
+                 issue["labels"].select { |label| @options[:issue_line_labels].include?(label["name"]) }
+               end
+      labels.map { |label| " \[[#{label['name']}](#{label['url'].sub('api.github.com/repos', 'github.com')})\]" }.join("")
+    end
+
+    private
+
+    # Creates section objects for this entry.
+    # @return [Nil]
+    def create_sections
+      @sections = if @options.configure_sections?
+                    parse_sections(@options[:configure_sections])
+                  elsif @options.add_sections?
+                    default_sections.concat parse_sections(@options[:add_sections])
+                  else
+                    default_sections
+                  end
+      nil
+    end
+
+    # Turns the argument from the commandline of --configure-sections or
+    # --add-sections into an array of Section objects.
+    #
+    # @param [String, Hash] sections_desc Either string or hash describing sections
+    # @return [Array] Parsed section objects.
+    def parse_sections(sections_desc)
+      require "json"
+
+      sections_desc = sections_desc.to_json if sections_desc.class == Hash
+
+      begin
+        sections_json = JSON.parse(sections_desc)
+      rescue JSON::ParserError => e
+        raise "There was a problem parsing your JSON string for sections: #{e}"
+      end
+
+      sections_json.collect do |name, v|
+        Section.new(name: name.to_s, prefix: v["prefix"], labels: v["labels"], body_only: v["body_only"], options: @options)
+      end
+    end
+
+    # Generates header text for an entry.
+    #
+    # @param [String] newer_tag_name The name of a newer tag
+    # @param [String] newer_tag_link Used for URL generation. Could be same as #newer_tag_name or some specific value, like HEAD
+    # @param [Time] newer_tag_time Time when the newer tag was created
+    # @param [String] older_tag_name The name of an older tag; used for URLs.
+    # @param [String] project_url URL for the current project.
+    # @return [String] Header text content.
+    def generate_header(newer_tag_name, newer_tag_link, newer_tag_time, older_tag_name, project_url)
+      header = ""
+
+      # Generate date string:
+      time_string = newer_tag_time.strftime(@options[:date_format])
+
+      # Generate tag name and link
+      release_url = if @options[:release_url]
+                      format(@options[:release_url], newer_tag_link)
+                    else
+                      "#{project_url}/tree/#{newer_tag_link}"
+                    end
+      header += if newer_tag_name.equal?(@options[:unreleased_label])
+                  "## [#{newer_tag_name}](#{release_url})\n\n"
+                else
+                  "## [#{newer_tag_name}](#{release_url}) (#{time_string})\n\n"
+                end
+
+      if @options[:compare_link] && older_tag_name
+        # Generate compare link
+        header += "[Full Changelog](#{project_url}/compare/#{older_tag_name}...#{newer_tag_link})\n\n"
+      end
+
+      header
+    end
+
+    # Generates complete body text for a tag (without a header)
+    #
+    # @param [Array] pull_requests
+    # @param [Array] issues
+    # @return [String] Content generated from sections of sorted issues & PRs.
+    def generate_body(pull_requests, issues)
+      sort_into_sections(pull_requests, issues)
+      @sections.map(&:generate_content).join
+    end
+
+    # Default sections to used when --configure-sections is not set.
+    #
+    # @return [Array] Section objects.
+    def default_sections
+      [
+        Section.new(name: "summary", prefix: @options[:summary_prefix], labels: @options[:summary_labels], options: @options, body_only: true),
+        Section.new(name: "breaking", prefix: @options[:breaking_prefix], labels: @options[:breaking_labels], options: @options),
+        Section.new(name: "enhancements", prefix: @options[:enhancement_prefix], labels: @options[:enhancement_labels], options: @options),
+        Section.new(name: "bugs", prefix: @options[:bug_prefix], labels: @options[:bug_labels], options: @options),
+        Section.new(name: "deprecated", prefix: @options[:deprecated_prefix], labels: @options[:deprecated_labels], options: @options),
+        Section.new(name: "removed", prefix: @options[:removed_prefix], labels: @options[:removed_labels], options: @options),
+        Section.new(name: "security", prefix: @options[:security_prefix], labels: @options[:security_labels], options: @options)
+      ]
+    end
+
+    # Sorts issues and PRs into entry sections by labels and lack of labels.
+    #
+    # @param [Array] pull_requests
+    # @param [Array] issues
+    # @return [Nil]
+    def sort_into_sections(pull_requests, issues)
+      if @options[:issues]
+        unmapped_issues = sort_labeled_issues(issues)
+        add_unmapped_section(unmapped_issues)
+      end
+      if @options[:pulls]
+        unmapped_pull_requests = sort_labeled_issues(pull_requests)
+        add_unmapped_section(unmapped_pull_requests)
+      end
+      nil
+    end
+
+    # Iterates through sections and sorts labeled issues into them based on
+    # the label mapping. Returns any unmapped or unlabeled issues.
+    #
+    # @param [Array] issues Issues or pull requests.
+    # @return [Array] Issues that were not mapped into any sections.
+    def sort_labeled_issues(issues)
+      sorted_issues = []
+      issues.each do |issue|
+        label_names = issue["labels"].collect { |l| l["name"] }
+
+        # Add PRs in the order of the @sections array. This will either be the
+        # default sections followed by any --add-sections sections in
+        # user-defined order, or --configure-sections in user-defined order.
+        # Ignore the order of the issue labels from github which cannot be
+        # controled by the user.
+        @sections.each do |section|
+          unless (section.labels & label_names).empty?
+            section.issues << issue
+            sorted_issues << issue
+            break
+          end
+        end
+      end
+      issues - sorted_issues
+    end
+
+    # Creates a section for issues/PRs with no labels or no mapped labels.
+    #
+    # @param [Array] issues
+    # @return [Nil]
+    def add_unmapped_section(issues)
+      unless issues.empty?
+        # Distinguish between issues and pull requests
+        if issues.first.key?("pull_request")
+          name = "merged"
+          prefix = @options[:merge_prefix]
+          add_wo_labels = @options[:add_pr_wo_labels]
+        else
+          name = "issues"
+          prefix = @options[:issue_prefix]
+          add_wo_labels = @options[:add_issues_wo_labels]
+        end
+        add_issues = if add_wo_labels
+                       issues
+                     else
+                       # Only add unmapped issues
+                       issues.select { |issue| issue["labels"].any? }
+                     end
+        merged = Section.new(name: name, prefix: prefix, labels: [], issues: add_issues, options: @options) unless add_issues.empty?
+        @sections << merged
+      end
+      nil
+    end
+  end
+end

data/lib/github_changelog_generator/generator/generator.rb

@@ -1,20 +1,38 @@
 # frozen_string_literal: true
 
-require_relative "../octo_fetcher"
-require_relative "generator_generation"
-require_relative "generator_fetcher"
-require_relative "generator_processor"
-require_relative "generator_tags"
+require "github_changelog_generator/octo_fetcher"
+require "github_changelog_generator/generator/generator_fetcher"
+require "github_changelog_generator/generator/generator_processor"
+require "github_changelog_generator/generator/generator_tags"
+require "github_changelog_generator/generator/entry"
+require "github_changelog_generator/generator/section"
 
 module GitHubChangelogGenerator
   # Default error for ChangelogGenerator
   class ChangelogGeneratorError < StandardError
   end
 
+  # This class is the high-level code for gathering issues and PRs for a github
+  # repository and generating a CHANGELOG.md file. A changelog is made up of a
+  # series of "entries" of all tagged releases, plus an extra entry for the
+  # unreleased changes. Entries are made up of various organizational
+  # "sections," and sections contain the github issues and PRs.
+  #
+  # So the changelog contains entries, entries contain sections, and sections
+  # contain issues and PRs.
+  #
+  # @see GitHubChangelogGenerator::Entry
+  # @see GitHubChangelogGenerator::Section
   class Generator
-    attr_accessor :options, :filtered_tags, :github, :tag_section_mapping, :sorted_tags
+    attr_accessor :options, :filtered_tags, :tag_section_mapping, :sorted_tags
 
-    # A Generator responsible for all logic, related with change log generation from ready-to-parse issues
+    CREDIT_LINE = <<~CREDIT
+      \\* *This Changelog was automatically generated \
+      by [github_changelog_generator]\
+      (https://github.com/github-changelog-generator/github-changelog-generator)*
+    CREDIT
+
+    # A Generator responsible for all logic, related with changelog generation from ready-to-parse issues
     #
     # Example:
     #   generator = GitHubChangelogGenerator::Generator.new
@@ -23,133 +41,137 @@ module GitHubChangelogGenerator
       @options        = options
       @tag_times_hash = {}
       @fetcher        = GitHubChangelogGenerator::OctoFetcher.new(options)
+      @sections       = []
     end
 
-    def fetch_issues_and_pr
-      issues, pull_requests = @fetcher.fetch_closed_issues_and_pr
-
-      @pull_requests = options[:pulls] ? get_filtered_pull_requests(pull_requests) : []
-
-      @issues = options[:issues] ? get_filtered_issues(issues) : []
-
-      fetch_events_for_issues_and_pr
-      detect_actual_closed_dates(@issues + @pull_requests)
+    # Main function to start changelog generation
+    #
+    # @return [String] Generated changelog file
+    def compound_changelog
+      @options.load_custom_ruby_files
+
+      Sync do
+        fetch_and_filter_tags
+        fetch_issues_and_pr
+
+        log = if @options[:unreleased_only]
+                generate_entry_between_tags(@filtered_tags[0], nil)
+              else
+                generate_entries_for_all_tags
+              end
+        log += File.read(@options[:base]) if File.file?(@options[:base])
+        log = remove_old_fixed_string(log)
+        log = insert_fixed_string(log)
+        @log = log
+      end
     end
 
-    ENCAPSULATED_CHARACTERS = %w(< > * _ \( \) [ ] #)
+    private
 
-    # Encapsulate characters to make Markdown look as expected.
-    #
-    # @param [String] string
-    # @return [String] encapsulated input string
-    def encapsulate_string(string)
-      string = string.gsub('\\', '\\\\')
+    # Generate log only between 2 specified tags
+    # @param [String] older_tag all issues before this tag date will be excluded. May be nil, if it's first tag
+    # @param [String] newer_tag all issue after this tag will be excluded. May be nil for unreleased section
+    def generate_entry_between_tags(older_tag, newer_tag)
+      filtered_issues, filtered_pull_requests = filter_issues_for_tags(newer_tag, older_tag)
 
-      ENCAPSULATED_CHARACTERS.each do |char|
-        string = string.gsub(char, "\\#{char}")
+      if newer_tag.nil? && filtered_issues.empty? && filtered_pull_requests.empty?
+        # do not generate empty unreleased section
+        return ""
       end
 
-      string
-    end
-
-    # Generates log for section with header and body
-    #
-    # @param [Array] pull_requests List or PR's in new section
-    # @param [Array] issues List of issues in new section
-    # @param [String] newer_tag Name of the newer tag. Could be nil for `Unreleased` section
-    # @param [Hash, nil] older_tag Older tag, used for the links. Could be nil for last tag.
-    # @return [String] Ready and parsed section
-    def create_log_for_tag(pull_requests, issues, newer_tag, older_tag = nil)
       newer_tag_link, newer_tag_name, newer_tag_time = detect_link_tag_time(newer_tag)
 
-      github_site = options[:github_site] || "https://github.com"
-      project_url = "#{github_site}/#{options[:user]}/#{options[:project]}"
-
       # If the older tag is nil, go back in time from the latest tag and find
       # the SHA for the first commit.
       older_tag_name =
         if older_tag.nil?
-          @fetcher.commits_before(newer_tag_time).last["sha"]
+          @fetcher.oldest_commit["sha"]
         else
           older_tag["name"]
         end
 
-      log = generate_header(newer_tag_name, newer_tag_link, newer_tag_time, older_tag_name, project_url)
+      Entry.new(options).generate_entry_for_tag(filtered_pull_requests, filtered_issues, newer_tag_name, newer_tag_link, newer_tag_time, older_tag_name)
+    end
 
-      if options[:issues]
-        # Generate issues:
-        log += issues_to_log(issues, pull_requests)
+    # Filters issues and pull requests based on, respectively, `actual_date`
+    # and `merged_at` timestamp fields. `actual_date` is the detected form of
+    # `closed_at` based on merge event SHA commit times.
+    #
+    # @return [Array] filtered issues and pull requests
+    def filter_issues_for_tags(newer_tag, older_tag)
+      filtered_pull_requests = filter_by_tag(@pull_requests, newer_tag)
+      filtered_issues        = delete_by_time(@issues, "actual_date", older_tag, newer_tag)
+
+      newer_tag_name = newer_tag.nil? ? nil : newer_tag["name"]
+
+      if options[:filter_issues_by_milestone]
+        # delete excess irrelevant issues (according milestones). Issue #22.
+        filtered_issues = filter_by_milestone(filtered_issues, newer_tag_name, @issues)
+        filtered_pull_requests = filter_by_milestone(filtered_pull_requests, newer_tag_name, @pull_requests)
       end
+      [filtered_issues, filtered_pull_requests]
+    end
+
+    # The full cycle of generation for whole project
+    # @return [String] All entries in the changelog
+    def generate_entries_for_all_tags
+      puts "Generating entry..." if options[:verbose]
 
-      if options[:pulls] && options[:add_pr_wo_labels]
-        # Generate pull requests:
-        log += generate_sub_section(pull_requests, options[:merge_prefix])
+      entries = generate_unreleased_entry
+
+      @tag_section_mapping.each_pair do |_tag_section, left_right_tags|
+        older_tag, newer_tag = left_right_tags
+        entries += generate_entry_between_tags(older_tag, newer_tag)
       end
 
-      log
+      entries
     end
 
-    # Generate ready-to-paste log from list of issues and pull requests.
-    #
-    # @param [Array] issues
-    # @param [Array] pull_requests
-    # @return [String] generated log for issues
-    def issues_to_log(issues, pull_requests)
-      log = ""
-      bugs_a, enhancement_a, issues_a = parse_by_sections(issues, pull_requests)
-
-      log += generate_sub_section(enhancement_a, options[:enhancement_prefix])
-      log += generate_sub_section(bugs_a, options[:bug_prefix])
-      log += generate_sub_section(issues_a, options[:issue_prefix])
-      log
+    def generate_unreleased_entry
+      entry = ""
+      if options[:unreleased]
+        start_tag        = @filtered_tags[0] || @sorted_tags.last
+        unreleased_entry = generate_entry_between_tags(start_tag, nil)
+        entry           += unreleased_entry if unreleased_entry
+      end
+      entry
     end
 
-    # This method sort issues by types
-    # (bugs, features, or just closed issues) by labels
+    # Fetches @pull_requests and @issues and filters them based on options.
     #
-    # @param [Array] issues
-    # @param [Array] pull_requests
-    # @return [Array] tuple of filtered arrays: (Bugs, Enhancements Issues)
-    def parse_by_sections(issues, pull_requests)
-      issues_a = []
-      enhancement_a = []
-      bugs_a = []
-
-      issues.each do |dict|
-        added = false
-        dict["labels"].each do |label|
-          if options[:bug_labels].include?(label["name"])
-            bugs_a.push(dict)
-            added = true
-            next
-          end
-          if options[:enhancement_labels].include?(label["name"])
-            enhancement_a.push(dict)
-            added = true
-            next
-          end
-        end
-        issues_a.push(dict) unless added
-      end
+    # @return [Nil] No return.
+    def fetch_issues_and_pr
+      issues, pull_requests = @fetcher.fetch_closed_issues_and_pr
 
-      added_pull_requests = []
-      pull_requests.each do |pr|
-        pr["labels"].each do |label|
-          if options[:bug_labels].include?(label["name"])
-            bugs_a.push(pr)
-            added_pull_requests.push(pr)
-            next
-          end
-          if options[:enhancement_labels].include?(label["name"])
-            enhancement_a.push(pr)
-            added_pull_requests.push(pr)
-            next
-          end
-        end
-      end
-      added_pull_requests.each { |p| pull_requests.delete(p) }
+      @pull_requests = options[:pulls] ? get_filtered_pull_requests(pull_requests) : []
+
+      @issues = options[:issues] ? get_filtered_issues(issues) : []
 
-      [bugs_a, enhancement_a, issues_a]
+      fetch_events_for_issues_and_pr
+      detect_actual_closed_dates(@issues + @pull_requests)
+      add_first_occurring_tag_to_prs(@sorted_tags, @pull_requests)
+      nil
+    end
+
+    # Remove the previously assigned fixed message.
+    # @param log [String] Old lines are fixed
+    def remove_old_fixed_string(log)
+      log.gsub!(/#{Regexp.escape(@options[:frontmatter])}/, "") if @options[:frontmatter]
+      log.gsub!(/#{Regexp.escape(@options[:header])}\n{,2}/, "")
+      log.gsub!(/\n{,2}#{Regexp.escape(CREDIT_LINE)}/, "") # Remove old credit lines
+      log
+    end
+
+    # Add template messages to given string. Previously added
+    # messages of the same wording are removed.
+    # @param log [String]
+    def insert_fixed_string(log)
+      ins = ""
+      ins += @options[:frontmatter] if @options[:frontmatter]
+      ins += "#{@options[:header]}\n\n"
+      log.insert(0, ins)
+      log += "\n\n#{CREDIT_LINE}"
+      log
     end
   end
 end