keepachangelog_manager 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 77a5bbc658a38412711067bc833cbd9d46b2bef2
+  data.tar.gz: c4ab817a80b97bb93938e1b20f53ea5cc4a5870c
+SHA512:
+  metadata.gz: 60d59c8034fa8ae6e546575859bfcd625a40977839eb9c71aa18f9c7e576a6ac83e9a1e45de7ae95ff092d108c35e796ba9ba47ed39c54f1d8a8c20d0c1d1c15
+  data.tar.gz: 04e47a37894d997698388616629f05640e01f2da4e5a1575f2523eb060d2c9e4d8de628ab4f555f635c04e7da0ecc9a8225e5cd4cbeda164e651c95a7bb5373d

data/.yardopts

@@ -0,0 +1 @@
+lib/keepachangelog.rb lib/**/*.rb

data/README.md

@@ -0,0 +1,96 @@
+
+# `keepachangelog_manager` Ruby gem for your CHANGELOG.md
+[![Gem Version](https://badge.fury.io/rb/keepachangelog_manager.svg)](https://rubygems.org/gems/keepachangelog_manager)
+[![Documentation](http://img.shields.io/badge/docs-rdoc.info-blue.svg)](http://www.rubydoc.info/gems/keepachangelog_manager/0.0.1)
+[![Build Status](http://badges.herokuapp.com/travis/ianfixes/keepachangelog_manager_gem?label=build&branch=master)](https://travis-ci.org/ianfixes/keepachangelog_manager_gem)
+
+If you follow the [Keep A Changelog](http://keepachangelog.com) `CHANGELOG.md` style, this gem automates the process of updating the file for a release.
+
+Before:
+```markdown
+# Change Log
+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/).
+
+## [Unreleased]
+### Added
+
+### Changed
+* Everything
+
+### Deprecated
+
+### Removed
+
+### Fixed
+
+### Security
+
+
+## [0.0.1] - 2018-12-19
+### Added
+* Initial stuff
+
+
+[Unreleased]: https://github.com/ianfixes/keepachangelog_manager_gem/compare/v0.0.1...HEAD
+[0.0.1]: https://github.com/ianfixes/keepachangelog_manager_gem/compare/v0.0.0...v0.0.1
+```
+
+After running `bundle exec keepachangelog_release.md --increment-minor`:
+
+```markdown
+# Change Log
+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/).
+
+## [Unreleased]
+### Added
+
+### Changed
+
+### Deprecated
+
+### Removed
+
+### Fixed
+
+### Security
+
+
+## [0.1.0] - 2019-01-23
+### Changed
+* Everything
+
+
+## [0.0.1] - 2018-12-19
+### Added
+* Initial stuff
+
+
+[Unreleased]: https://github.com/ianfixes/keepachangelog_manager_gem/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/ianfixes/keepachangelog_manager_gem/compare/v0.0.1...v0.1.0
+[0.0.1]: https://github.com/ianfixes/keepachangelog_manager_gem/compare/v0.0.0...v0.0.1
+```
+
+
+## Installation In Your GitHub Project
+
+Add the following to your `Gemfile`:
+
+```ruby
+source 'https://rubygems.org'
+gem 'keepachangelog'
+```
+
+## Author
+
+This gem was written by Ian Katz (ianfixes@gmail.com) in 2019.  It's released under the Apache 2.0 license.
+
+
+## See Also
+
+* [Contributing](CONTRIBUTING.md)

data/bin/keepachangelog_manager.rb

@@ -0,0 +1,54 @@
+#!/usr/bin/env ruby
+require 'keepachangelog_manager'
+require 'optparse'
+
+# Use some basic parsing to allow command-line overrides of config
+class Parser
+  def self.parse(options)
+    parsed_config = {}
+
+    opt_parser = OptionParser.new do |opts|
+      opts.banner = "Usage: #{File.basename(__FILE__)} <ONLY ONE of the following options>"
+
+      opts.on("--major=VERSION", "Upgrade major version to VERSION") do |p|
+        parsed_config[:abs_major] = p
+      end
+
+      opts.on("--minor=VERSION", "Upgrade minor version to VERSION") do |p|
+        parsed_config[:abs_minor] = p
+      end
+
+      opts.on("--patch=VERSION", "Upgrade patch version to VERSION") do |p|
+        parsed_config[:abs_patch] = p
+      end
+
+      opts.on("--increment-major", "Increment major version") do |v|
+        parsed_config[:inc_major] = v
+      end
+
+      opts.on("--increment-minor", "Increment minor version") do |v|
+        parsed_config[:inc_minor] = v
+      end
+
+      opts.on("--increment-patch", "Increment patch version") do |v|
+        parsed_config[:inc_patch] = v
+      end
+
+      opts.on("-h", "--help", "Prints this help") do
+        puts opts
+        exit
+      end
+    end
+
+    opt_parser.parse!(options)
+    parsed_config
+  end
+end
+
+# Read in command line options and make them read-only
+@cli_options = (Parser.parse ARGV).freeze
+Parser.parse %w[--help] if @cli_options.empty?
+
+repo = KeepAChangelogManager::Repo.new(`git rev-parse --show-toplevel`.strip)
+new_version = repo.changelog.update(@cli_options)
+puts new_version

data/lib/keepachangelog_manager.rb

@@ -0,0 +1,9 @@
+require "keepachangelog_manager/version"
+require "keepachangelog_manager/repo"
+require "keepachangelog_manager/exceptions"
+
+# KeepAChangelogManager updates the sections of CHANGELOG.md according to keepachangelog.org rules
+# @author Ian Katz <ianfixes@gmail.com>
+module KeepAChangelogManager
+
+end

data/lib/keepachangelog_manager/changelog.rb

@@ -0,0 +1,352 @@
+require 'semver'
+require 'git/remote/parser'
+require 'date'
+
+UNRELEASED = "Unreleased".freeze
+DEFAULT_VERSION = "0.0.0".freeze
+SECTION_ORDER = [:added, :changed, :deprecated, :removed, :fixed, :security].freeze
+SECTION_NAME = {
+  added: "Added",
+  changed: "Changed",
+  deprecated: "Deprecated",
+  removed: "Removed",
+  fixed: "Fixed",
+  security: "Security",
+}.freeze
+
+module KeepAChangelogManager
+
+  # Handles all things related to a CHANGELOG.md
+  class Changelog
+
+    # Data Structure of a Changelog document:
+    # * Header (array of lines -- just the text, the title is predefined)
+    # * Release hash: key = semver (or :unreleased)
+    #   * Date string (optional)
+    #   * Section hash (order = )
+    #     * array of lines
+    class ChangeData
+      # @return Array<String>
+      attr_accessor :header
+
+      # @return Hash
+      attr_accessor :releases
+
+      def initialize(header, releases)
+        @header = header
+        @releases = releases
+      end
+
+      # validate an attempted change to a version -- make sure no versions decrease
+      #
+      # @param version SemVer
+      # @param dimension Symbol
+      # @param newval Int
+      def validate(version, dimension, newval)
+        oldval = version.send(dimension)
+        raise ArgumentError, "Tried to set #{dimension} to #{newval}, which isn't greater than #{oldval}" unless newval > oldval
+      end
+
+      # Default "unreleased" structure
+      #
+      # @return Hash
+      def self.bare_unreleased_data
+        {
+          sections: Hash[SECTION_ORDER.map { |i| [i, []] }]
+        }
+      end
+
+      # content of a fresh (empty) changelog
+      #
+      # @return String
+      def self.bare
+        header_lines = [
+          "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/).",
+        ]
+        ChangeData.new(header_lines, UNRELEASED => self.bare_unreleased_data)
+      end
+
+      # Update a changelog by transforming Unreleased into a release
+      #
+      # Only one argument at a time should be supplied, all others nil
+      #
+      # @param inc_patch boolean whether to increment the patch version
+      # @param abs_patch int an absolute value for the patch version
+      # @param inc_minor boolean whether to increment the minor version
+      # @param abs_minor int an absolute value for the minor version
+      # @param inc_major boolean whether to increment the major version
+      # @param abs_major int an absolute value for the major version
+      # @return String the new version
+      def update(inc_patch: nil, abs_patch: nil,
+                 inc_minor: nil, abs_minor: nil,
+                 inc_major: nil, abs_major: nil)
+        num_args_supplied = binding.local_variables.count { |p| !binding.local_variable_get(p).nil? }
+        raise ArgumentError, "Only one update option should be specified" unless 1 == num_args_supplied
+
+        version = @releases.keys.reject { |k| k == UNRELEASED }.map { |k| SemVer.parse(k) }.max
+        version = SemVer.parse("0.0.0") if version.nil?
+
+        if !inc_patch.nil?
+          version.patch += 1
+        elsif !abs_patch.nil?
+          validate(version, :patch, abs_patch)
+          version.patch = abs_patch
+        elsif !inc_minor.nil?
+          version.minor += 1
+          version.patch = 0
+        elsif !abs_minor.nil?
+          validate(version, :minor, abs_minor)
+          version.minor = abs_minor
+          version.patch = 0
+        elsif !inc_major.nil?
+          version.major += 1
+          version.minor = 0
+          version.patch = 0
+        elsif !abs_major.nil?
+          validate(version, :major, abs_major)
+          version.major = abs_major
+          version.minor = 0
+          version.patch = 0
+        end
+
+        new_version = version.format("%M.%m.%p")
+        @releases[new_version] = @releases[UNRELEASED]
+        @releases[new_version][:date] = Date.today.strftime("%Y-%m-%d")
+        @releases[UNRELEASED] = self.class.bare_unreleased_data
+
+        new_version
+      end
+    end
+
+    # @return KeepAChangelog::Repo the repository
+    attr_accessor :repo
+
+    # @param path String path to CHANGELOG.md (or where it should be)
+    def initialize(repo)
+      @repo = repo
+    end
+
+    # Removes empty entries from the end of an array
+    #
+    # Works very much like string chomp
+    #
+    # @param lines Array<String>
+    # @return Array<String>
+    def array_chomp(lines)
+      return [] if lines.empty?
+      return [] if lines.all?(&:empty?)
+
+      last_entry = lines.rindex { |l| !l.strip.empty? }
+      lines[0..last_entry]
+    end
+
+    # whether the changelog exists in its supposed path
+    #
+    # @return boolean
+    def exist?
+      File.exist? @repo.changelog_path
+    end
+
+    # Create an empty CHANGELOG.md for this repo
+    #
+    # keepachangelog.com CHANGELOG.md syntax assumes git _and_ github.com
+    # so use that to our advantage: assume git repo exists.
+    #
+    # @return String
+    def create(force = false)
+      return if File.exist(@repo.changelog_path) && !force
+
+      File.open(@repo.changelog_path, 'w') { |file| file.write(bare_changelog) }
+    end
+
+    # Update a changelog in-place by transforming Unreleased into a release
+    #
+    # @see ChangeData.update
+    # @return String the new version
+    def update(**kwargs)
+      content = File.open(@repo.changelog_path, "r").read
+      data = parse(content)
+      new_version = data.update(**kwargs)
+      File.open(@repo.changelog_path, 'w') { |file| file.write(render(data)) }
+      new_version
+    end
+
+    # content of a fresh (empty) changelog
+    #
+    # @return String
+    def bare
+      render(ChangeData.bare)
+    end
+
+    # Sort section versions into a reverse-chronological array, unreleased first
+    #
+    # @param sections Hash the input
+    # @return Array<String> the sorted version strings
+    def version_order(releases)
+      # order sections in reverse chronological, unreleased on top
+      releases.keys.sort do |a, b|
+        next  0 if a == b
+        next -1 if a == UNRELEASED
+        next  1 if b == UNRELEASED
+
+        SemVer.parse(b) <=> SemVer.parse(a)
+      end
+    end
+
+    # Render the data structure to text
+    #
+    # @param data ChangeData
+    # @return String
+    def render(data)
+      render_lines(data).join("\n") + "\n"
+    end
+
+    # Render the data structure to an array of strings
+    #
+    # Output Structure of a Changelog document:
+    # * Header ("Change Log" and the text under it, up to the first '## ')
+    # * Release versions, reverse chronological, starting with 'unreleased'
+    #   * Version (or unreleased) as a link to the diff
+    #   * Date (optional)
+    #   * Sections
+    #     * Added
+    #     * Changed
+    #     * Deprecated
+    #     * Removed
+    #     * Fixed
+    #     * Security
+    # * Diff URLs
+    #
+    # Assumes the "Unreleased" section is fleshed out, even if blank
+    #
+    # @param data ChangeData
+    # @return Array<String>
+    def render_lines(data)
+      # header
+      out_lines = ["# Change Log"] + data.header
+      out_lines << ""
+      out_lines << ""
+
+      # releases
+      versions = version_order(data.releases)
+      versions.each do |v|
+        release = data.releases[v]
+        out_lines << "## [#{v}]" + (v == UNRELEASED || release[:date].nil? ? "" : " - #{release[:date]}")
+
+        SECTION_ORDER.each do |s|
+          next unless release[:sections].key? s
+          next if release[:sections][s].empty? && v != UNRELEASED
+
+          section = release[:sections][s]
+          out_lines << "### #{SECTION_NAME[s]}"
+          out_lines += section
+          out_lines << ""
+        end
+        out_lines << ""
+      end
+
+      # links.  unreleased will come first and may be the only one
+      versions.each_with_index do |v, i|
+        next_index = i + 1
+        this_version = v == UNRELEASED ? "HEAD" : "v#{v}"
+        prev_version = next_index < versions.length ? versions[next_index] : DEFAULT_VERSION
+        out_lines << "[#{v}]: https://github.com/#{@repo.owner}/#{@repo.name}/compare/v#{prev_version}...#{this_version}"
+      end
+
+      out_lines
+    end
+
+    # Parse an existing changelog (by path)
+    #
+    # @param changelog_text String path
+    # @return ChangeData
+    def parse_file(path)
+      parse(File.open(path, "r").read)
+    end
+
+    # Parse an existing changelog (delivered as a string)
+    #
+    # @param changelog_text String input
+    # @return ChangeData
+    def parse(changelog_text)
+      # allowable transitions
+      next_states = {
+        initial: [:header],
+        header: [:header, :release],
+        release: [:section],
+        section: [:section, :section_body, :release, :links],
+        section_body: [:section_body, :release, :links]
+      }
+      state = :initial
+
+      # signals for transitions, plus capture groups for params
+      transitions = {
+        header: /^# Change/,
+        release: /^## \[([^\]]+)\]( - (.*))?/,
+        section: /^### ([A-Z][a-z]+)/,
+        links: /^\[Unreleased\]: https:\/\/github\.com\//,
+      }
+
+      # parser state data
+      header_lines = []
+      releases = {}
+      last_version = nil
+      last_section = nil
+
+      changelog_text.lines.each do |l|
+        # find the regex that matches, no transition if no match
+        want_state, regex = transitions.find(proc { [nil, nil] }) { |_s, re| re.match(l) }
+        good_transition = want_state.nil? || next_states[state].include?(want_state)
+        raise ChangelogParseFail, "Changing to #{want_state} from #{state}" unless good_transition
+
+        want_param = regex.match(l) unless regex.nil?
+
+        # do any pre-transition bookkeeping
+        case want_state
+        when :initial
+          raise ChangelogParseFail, "Tried to transition back to initial state"
+        when :header
+          # nothing to do
+        when :release
+          version = want_param[1]
+          date = want_param[3]
+          releases[version] = { sections: {}, date: date }
+          last_version = version
+          last_section = nil
+        when :section
+          section_name = want_param[1]
+          section = SECTION_NAME.key(section_name)
+          raise ChangelogParseFail, "Unknown section name: '#{section_name}'" if section.nil?
+
+          releases[last_version][:sections][section] = []
+          last_section = section
+        when :links
+          break
+        else
+          # line is just a normal line.  decide where we are and start appending
+
+          case state
+          when :header
+            header_lines << l.chomp
+          when :section
+            releases[last_version][:sections][last_section] << l.chomp
+          end
+        end
+        state = want_state unless want_state.nil?
+      end
+
+      releases.each do |version, release|
+        release[:sections].each do |section, lines|
+          releases[version][:sections][section] = array_chomp(lines)
+        end
+      end
+
+      ChangeData.new(array_chomp(header_lines), releases)
+    end
+
+  end # class
+
+end # module

data/lib/keepachangelog_manager/exceptions.rb

@@ -0,0 +1,10 @@
+module KeepAChangelogManager
+  # If the code in question is not actually a git repository
+  class NoGitRepo < RuntimeError; end
+
+  # If the remote doesn't seem sane
+  class BadGitRepoUrl < RuntimeError; end
+
+  # If an existing changelog doesn't seem sane
+  class ChangelogParseFail < RuntimeError; end
+end

data/lib/keepachangelog_manager/repo.rb

@@ -0,0 +1,75 @@
+require "keepachangelog_manager/exceptions"
+require 'keepachangelog_manager/changelog'
+
+module KeepAChangelogManager
+
+  # Handles all things related to a repository and its filesystem
+  class Repo
+
+    # @return String the repository root
+    attr_accessor :root
+
+    # Create a new Repo representing git repository, given its path
+    #
+    # @param root String path to root directory of repository
+    def initialize(root)
+      @root = root
+    end
+
+    # Get the repository name.  It is assumed to be the name of the repo root directory
+    #
+    # keepachangelog.com CHANGELOG.md syntax assumes git _and_ github.com
+    # so use that to our advantage: assume git repo exists.
+    #
+    # @return String
+    def name
+      File.basename(@root)
+    end
+
+    # The git remote origin url
+    #
+    # @return String
+    def origin_url
+      `git remote get-url origin`
+    end
+
+    # Extract the owner from a git URL
+    #
+    # @param url String the URL (git:// or https://)
+    # @return String
+    def _owner_from_git_url(url)
+      parsed = Git::Remote::Parser.new.parse(url)
+      raise BadGitRepoUrl, "Could not parse '#{url}' as a git url" if parsed.nil?
+
+      parsed.owner
+    end
+
+    # Get the repo owner
+    #
+    # Assumes an "origin" url!
+    #
+    # @return String
+    def owner
+      Dir.chdir(@root) do
+        url = origin_url
+        raise NoGitRepo, "Could not find a git repo in '#{@root}'" if url.empty?
+
+        _owner_from_git_url(url)
+      end
+    end
+
+    # the path to the CHANGELOG.md file
+    #
+    # @return String
+    def changelog_path
+      File.join(@root, "CHANGELOG.md")
+    end
+
+    # A changelog object
+    #
+    # @return KeepAChangelog::Changelog
+    def changelog
+      Changelog.new(self)
+    end
+  end
+end

data/lib/keepachangelog_manager/version.rb

@@ -0,0 +1,3 @@
+module KeepAChangelogManager
+  VERSION = "0.0.1".freeze
+end

metadata

@@ -0,0 +1,151 @@
+--- !ruby/object:Gem::Specification
+name: keepachangelog_manager
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Ian Katz
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2019-01-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: git-remote-parser
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: semver2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+- !ruby/object:Gem::Dependency
+  name: fakefs
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.18.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.18.1
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.59.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.59.2
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.11
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.11
+description: ''
+email:
+- ianfixes@gmail.com
+executables:
+- keepachangelog_manager.rb
+extensions: []
+extra_rdoc_files: []
+files:
+- ".yardopts"
+- README.md
+- bin/keepachangelog_manager.rb
+- lib/keepachangelog_manager.rb
+- lib/keepachangelog_manager/changelog.rb
+- lib/keepachangelog_manager/exceptions.rb
+- lib/keepachangelog_manager/repo.rb
+- lib/keepachangelog_manager/version.rb
+homepage: http://github.com/ianfixes/keepachangelog_manager_gem
+licenses:
+- Apache-2.0
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.2.3
+signing_key: 
+specification_version: 4
+summary: CHANGELOG.md (keepachangelog.com style) section updater for automated releasing
+test_files: []