revision 1.1.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 94dfd966e2e44d185a37be41bb1fe745455f0e6d
+  data.tar.gz: cf971a767a20dbc24696adff7bbf634e821e8ea0
+SHA512:
+  metadata.gz: 7e5ec6a596855ad4f50c5ee1307c9cfac3e4c7fe4918f6e4c03b00879c8e7824caa1675bea87d9ac4b0601b165bf6f6b8e1dd2c7e5e95b31e3f6450fe759d994
+  data.tar.gz: 6b71b8ed50740a488904d66b35e52bdcfb14dd5ec5bfcd71cef1cd387e94cdbfd8816584a60fec3342e6133820c108a53cf299dc6964e03207b205fa28a08440

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status
+Gemfile.lock
+
+README.html

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.4.2
+before_install: gem install bundler -v 1.16.0

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+#git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in revision.gemspec
+gemspec

data/README.org

@@ -0,0 +1,269 @@
+#+TITLE: Revision management gem
+#+AUTHOR: Cormac Cannon
+#+EMAIL: cormac.cannon@neuromoddevices.com
+#+LANGUAGE: en
+
+# Generic properties
+# :eval never-export
+# ... Prevent auto evaluation of blocks on export. Evaluate them interactively instead
+# :results verbatim
+# ... Output results verbatim rather than autodetecting (which usually ends up tabular). Override per script using :results tabular
+#+PROPERTY: header-args :results verbatim :noweb yes :exports both :eval never-export
+# #+PROPERTY: header-args :results verbatim :noweb yes :exports both
+
+# HTML EXPORT SETUP
+
+# 1. Auto-export to html on save (N.B. This doesn't work?)
+#    This can be done per-session by calling 'toggle-org-html-export-on-save'
+# Local variables:
+# eval: (add-hook 'after-save-hook 'org-html-export-to-html t t)
+# End:
+
+# 2. Apply a theme
+#+SETUPFILE: org-themes/theme-bigblow.setup
+# or alternatively #+SETUPFILE: theme-readtheorg.setup
+
+* Overview
+
+  This gem automates revision management for source projects. The tool is language agnostic (used for C, ruby and matlab projects, to date -- though you're
+  probably better off using bundler for ruby projects). It supports per-project configuration using a yaml-format file called =releasables.yaml= located at
+  the project root.
+
+  It currently supports the following functionality
+  - Manage 3-component revision IDs embedded natively in source file
+  - Embeds/updates/extracts changelog in source file header/footer comments
+  - Automatically prompts for a changelog entry each time a revision identifier is incremented
+  - Optionally commits and tags changes to a git repo after an update to the revision ID
+  - Builds and archives projects in zip format (including release notes and arbitrary release artefacts defined
+
+* Installation
+
+  #+BEGIN_NOTE
+  The gem hasn't been uploaded to rubygems.org as yet.
+  #+END_NOTE
+
+** From rubygems.org
+
+   #+BEGIN_SRC sh
+     gem install revision
+   #+END_SRC
+
+** From source
+
+*** Checkout
+
+    #+BEGIN_SRC sh
+      gem install bundler
+      git clone git@git.nmd.ie:gem/revision
+      cd revision
+    #+END_SRC
+
+*** Install
+
+    #+BEGIN_SRC sh
+      bundle install
+      bundle exec rake install
+    #+END_SRC
+
+    #+RESULTS:
+    #+begin_example
+    Using rake 10.5.0
+    Using bundler 1.16.0
+    Using coderay 1.1.2
+    Using diff-lcs 1.3
+    Using git 1.3.0
+    Using method_source 0.9.0
+    Using pry 0.11.3
+    Using rubyzip 1.2.1
+    Using thor 0.19.4
+    Using revision 1.0.0 from source at `.`
+    Using rspec-support 3.7.0
+    Using rspec-core 3.7.0
+    Using rspec-expectations 3.7.0
+    Using rspec-mocks 3.7.0
+    Using rspec 3.7.0
+    Bundle complete! 5 Gemfile dependencies, 15 gems now installed.
+    Use `bundle info [gemname]` to see where a bundled gem is installed.
+    revision 1.0.0 built to pkg/revision-1.0.0.gem.
+    revision (1.0.0) installed.
+    #+end_example
+
+* Usage
+
+** Supported Commands
+   Run the executable with no arguments to get usage instructions in your console window...
+
+   #+BEGIN_SRC sh
+     revision
+   #+END_SRC
+
+   #+RESULTS:
+   #+begin_example
+   Loading releasable definitions from /home/cormacc/nextcloud/nmd/gem/revision/releasables.yaml ...
+   Commands:
+     revision archive         # Archive releasables
+     revision changelog       # Display change log on stdout
+     revision help [COMMAND]  # Describe available commands or one specific command
+     revision info            # Display info for all defined releasables
+     revision major           # Increment major revision index
+     revision minor           # Increment minor revision index
+     revision patch           # Increment patch revision index
+     revision tag             # Commit the current revision to a local git repo ...
+
+   Options:
+     [--dryrun], [--no-dryrun]
+     [--id=ID]
+
+   #+end_example
+
+   #+BEGIN_NOTE
+   The tool can be run from any subfolder of a project root -- it will traverse the tree until it finds
+   an ancestor containing =releasables.yaml= OR can go no further (in which case it throws an error).
+   #+END_NOTE
+
+*** Operating on multiple releasables
+
+    A single =releasables.yaml= file can define multiple releasables, either implicitly (via inclusion) or explicitly
+    (see [[Configuration]] section below for examples). In this context, the ~info~ and ~archive~ commands
+    will operate on all defined releasables, whereas the remaining commands will require the releasable
+    to be specified using the ~--id=~ option, e.g.
+
+    #+BEGIN_SRC sh
+      revision minor --id=firmware
+    #+END_SRC
+
+** Configuration
+
+    YAML syntax is used for the configuration file. The [[Syntax]] and [[Examples]] sections below should provide sufficient
+    introduction to the limit subset of language features required to use this tool, however further info
+    may be found at the following links:
+
+    - http://docs.ansible.com/ansible/latest/YAMLSyntax.html
+    - http://www.yaml.org/start.html
+
+*** Syntax
+
+    The =releasables.yaml= file should contain a top level ~:releasables~ node.
+    Under this, you can create a list (or YAML /sequence/) of releasable definitions.
+
+    Each sequence item begins with a ~-~ and contains either a link to a folder containing its own =releasables.yaml=
+    defining one or more releasables ...
+
+    #+BEGIN_SRC yaml
+      - :folder: relative/path/to/a/releasable/folder
+    #+END_SRC
+
+    ... or a single inline releasable definition.
+
+    #+BEGIN_NOTE
+    The lines beginning with '#' are explanatory comments
+    #+END_NOTE
+
+    #+BEGIN_SRC yaml
+      - :id: my_releasable
+        :revision:
+          # Source file containing the revision identifier
+          # This will also include changelog entries, embedded as comments
+          :src: lib/revision/version.rb
+          # Regex matching the source revision identifier. Must contain the following named capture groups
+          # - major, minor, patch :: Numeric (uint) sequences representing the three revision ID components
+          # - sep1, sep2 :: the characters separating the revision components
+          # - prefix, postfix :: sufficient syntactic context to match the revision ID uniquely
+          # N.B. this regex matches the version ID from the standard bundler gem skeleton,
+          # e.g. VERSION = "1.1.0"
+          :regex: (?<prefix>VERSION = ")(?<major>\d+)(?<sep1>\.)(?<minor>\d+)(?<sep2>\.)(?<patch>\d+)(?<postfix>")
+          # Comment char for the project language -- prefixed to each line of changelog entries
+          # Quotes only necessary here to prevent # being interpreted as the beginning of a YAML comment
+          :comment_prefix: "#"
+        # Sequence of build steps -- each item should be a valid shell command, prefixed with the YAML sequence item token, '- '
+        :build_steps:
+          - bundle exec rake install
+        # Sequence defining the files (build artefacts) to package in the release archive.
+        # Each artefact definition must include a :src: key/value pair.
+        # An optional :dest: value may be provided to rename the file during packaging, or just (as in the first entry below)
+        # to flatten the folder structure.
+        # Any <VER> (or <REV>) in the :src: or :dest: placeholders wil be replaced with the current revision ID
+        # The revision archive will also include the revision history extracted as a text file
+        :artefacts:
+          # A binary artefact -- the
+          - :src: pkg/revision-<VER>.gem
+            :dest: revision-<VER>.gem
+          # This document -- the :dest: value defaults to duplicating :src: if not specified
+          - :src: README.org
+    #+END_SRC
+
+**** TODO (or at least consider) add support for overridable defaults
+     e.g. via a =.releasables= configuration file in the user home dir.
+     Though this would be bad for collaborative development as the config file would live outside source control.
+     Possibly useful to support inclusion of a controlled configuration file instead? Primarily to define
+     a revision regex and comment prefix for a group of related releasables....
+
+*** Examples
+**** C project
+
+     #+BEGIN_NOTE
+     The ~:regex:~ and ~:comment_prefix:~ keys are absent in the C example below. This project started life as
+     managing some embedded C projects, and the default values reflect this.
+     #+END_NOTE
+
+     #+BEGIN_SRC yaml
+        :releasables:
+          - :id: mbt_cd_firmware
+            :revision:
+              :src: src/FirmwareRevision.c
+            :build_steps:
+              - make --jobs=8 -f Makefile CONF=bootloadable
+            :artefacts:
+              - :src: dist/bootloadable/production/firmware.production.hex
+                :dest: mbt_cd_firmware_v<REV>.bootloadable.hex
+              - :src: dist/default/production/firmware.production.hex
+                :dest: mbt_cd_firmware_v<REV>.standalone.hex
+     #+END_SRC
+
+**** Ruby project
+
+    #+BEGIN_SRC yaml
+        :releasables:
+          - :id: revision
+            :revision:
+              :src: lib/revision/version.rb
+              :regex: (?<prefix>VERSION = ")(?<major>\d+)(?<sep1>\.)(?<minor>\d+)(?<sep2>\.)(?<patch>\d+)(?<postfix>")
+              :comment_prefix: "#"
+            :build_steps:
+              - bundle exec rake install
+            :artefacts:
+              - :src: pkg/revision-<VER>.gem
+    #+END_SRC
+
+*** Heirarchical project
+    Rather than defining the releasable parameters inline, a =releasables.yaml= list entry can contain a (relative or absolute) link to another folder containing it's own =releasables.yaml=.
+
+    i.e assuming the earlier examples were in folders =examples/c= and =examples/ruby= relative to a common root, a separate =releasables.yaml=
+    at that root could include them as follows...
+
+    #+BEGIN_SRC yaml
+        :releasables:
+          - :folder: examples/c
+          - :folder: examples/ruby
+    #+END_SRC
+
+**** TODO consider supporting a higher-level aggregate revision ID
+
+    #+BEGIN_SRC yaml
+      :revision:
+        :src: release_log.txt
+      :releasables:
+        - :folder: examples/c
+        - :folder: examples/ruby
+    #+END_SRC
+
+* Development
+
+  After checking out the repo, run =bin/setup= to install dependencies. Then, run =rake spec= to run the tests. You can also run =bin/console= for an interactive prompt that will allow you to experiment.
+
+  To install this gem onto your local machine, run =bundle exec rake install=. To release a new version, update the version number in =version.rb=, and then run =bundle exec rake release=, which will create a git tag for the version, push git commits and tags, and push the =.gem= file to [rubygems.org](https://rubygems.org).
+
+
+* Contributing
+
+  Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/revision.

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "revision"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/exe/revision

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require 'revision'
+
+Revision::CLI.start(ARGV)

data/lib/revision/cli.rb

@@ -0,0 +1,101 @@
+require 'thor'
+
+require_relative 'releasable'
+require_relative 'info'
+require_relative 'errors'
+
+module Revision
+  class CLI < Thor
+    class_option :dryrun, :type => :boolean, :default =>false
+    class_option :id, :default => nil #Initialized after loading definition
+
+    def initialize(*args)
+      super
+      #TODO Update this to traverse up the folder heirarchy until we find a releasables.yaml
+      wd = Dir.getwd
+      loop do
+        begin
+          @releasables = Releasable.from_folder(wd)
+          break
+        rescue Errors::NoDefinition
+          break if wd == File.expand_path('..',wd)
+          puts "No releasable found in #{wd}, trying parent..."
+          wd = File.expand_path('..',wd)
+          next
+        end
+      end
+      raise 'No definition file found in this directory or its ancestors' if @releasables.nil? || @releasables.empty?
+      @id = options[:id] || @releasables.keys[0]
+    end
+
+    desc "info", 'Display info for all defined releasables'
+    def info
+      puts "Found #{@releasables.values.length} releasables"
+      puts ''
+      puts @releasables.values.map {|r| r.to_s}.join("\n\n")
+      puts ''
+      puts "Default releasable ID: #{@id}"
+    end
+
+    desc "patch", "Increment patch revision index"
+    def patch
+      do_increment('patch')
+    end
+
+    desc "minor", "Increment minor revision index"
+    def minor
+      do_increment('minor')
+    end
+
+    desc "major", "Increment major revision index"
+    def major
+      do_increment('major')
+    end
+
+    desc "archive", "Archive releasables"
+    def archive
+      selected = options[:id].nil? ? @releasables.values : [@releasables[options[:id]]]
+      puts "Archiving #{selected.length} releasables..."
+      selected.each do |r|
+        r.build
+        r.archive
+      end
+    end
+
+    desc "changelog", "Display change log on stdout"
+    def changelog
+      select_one.output_changelog($stdout)
+    end
+
+    desc "tag", "Commit the current revision to a local git repo and add a version tag"
+    def tag
+      select_one.tag
+    end
+
+    private
+
+    def select_one
+      raise "Please specify one of #{@releasables.keys}" if options[:id].nil? && @releasables.keys.length > 1
+      @releasables[@id]
+    end
+
+    def do_increment(type)
+      r = select_one
+      increment_method = "#{type}_increment!"
+      say "Incrementing #{r.revision} to #{r.revision.public_send(increment_method)}"
+      options[:dryrun] ? r.revision.write_to_file : r.revision.write!
+      say ""
+      say "The automatic commit / tag step assumes you're only checking in changes to existing files"
+      say "You can answer 'n' at the prompt and use 'revision tag' to generate a commit with the latest changelog entry and an associated tag after manually adding any new files to the repo"
+      say ""
+      if ask("Commit changes to existing files and add a Git tag (y/N)?").upcase=='Y'
+        r.tag
+        if ask("Push changes/tag to origin (Y/n)?").upcase=='N' || !r.push
+          say "To push from the command line, type 'git push --tags' at a shell prompt"
+        end
+      end
+    end
+
+  end
+
+end

data/lib/revision/errors.rb

@@ -0,0 +1,10 @@
+module Revision
+  module Errors
+    class Base < StandardError; end
+    class NoDefinition < Base
+      def initialize(root)
+        super("No definition file (#{Releasable::CONFIG_FILE_NAME}) found at root #{root}")
+      end
+    end
+  end
+end

data/lib/revision/info.rb

@@ -0,0 +1,137 @@
+require_relative 'releasable'
+require_relative 'string_case'
+
+
+class Revision::Info
+  DEFAULT_REGEX = /(?<prefix>\s*Info\s+const\s+\S+_REVISION\s*=\s*\{\s*\{\s*)(?<major>\d+)(?<sep1>\s*,\s*)(?<minor>\d+)(?<sep2>\s*,\s*)(?<patch>\d+)(?<postfix>\s*\}\s*\};\s*)/
+  DEFAULT_COMMENT_PREFIX = ' *'.freeze
+  CHANGELOG_START_TAG = '<BEGIN CHANGELOG>'.freeze
+  CHANGELOG_END_TAG = '<END CHANGELOG>'.freeze
+  CHANGELOG_START = /.*#{CHANGELOG_START_TAG}.*/
+  CHANGELOG_END = /.*#{CHANGELOG_END_TAG}.*/
+
+  attr_accessor :major, :minor, :patch
+  attr_accessor :src
+  attr_accessor :regex
+  attr_accessor :comment_prefix
+
+  def initialize(file, regex: nil, comment_prefix: nil)
+    @src=file
+    @regex = regex.nil? ? DEFAULT_REGEX : /#{regex}/
+    @comment_prefix = comment_prefix || DEFAULT_COMMENT_PREFIX
+    matched = false
+    File.open(@src).each_line do |line|
+      if line =~ @regex
+        @major = Regexp.last_match[:major].to_i
+        @minor = Regexp.last_match[:minor].to_i
+        @patch = Regexp.last_match[:patch].to_i
+        matched = true
+        break
+      end
+    end
+    raise "Failed to match against #{@regex}" unless matched
+  end
+
+  def patch_increment!
+    @patch += 1
+    self
+  end
+
+  def minor_increment!
+    @minor += 1
+    @patch = 0
+    self
+  end
+
+  def major_increment!
+    @major += 1
+    @minor = 0
+    @patch = 0
+    self
+  end
+
+  def new_changelog_placeholder
+    placeholder = [@comment_prefix,CHANGELOG_START_TAG,CHANGELOG_END_TAG].join("\n#{@comment_prefix} ")
+    # Handle C block comments as a special case for legacy project support
+    # Could generalise the comment definition, but feels like unnecessary complexity...
+    if @src =~ /\.(c|cpp|h|hpp)$/ && !@comment_prefix =~ /#{Regexp.escape('//')}/
+      placeholder = "/**\n${placeholder}\n*/"
+    end
+    placeholder + "\n"
+  end
+
+  def write(output_file_name)
+
+    ref_info = self.class.new(@src, regex: @regex)
+    raise 'No revision identifiers incremented' if ref_info.to_s == self.to_s
+
+    entry = get_changelog_entry
+
+    text = File.read(@src)
+    text.gsub!(@regex) { |match| "#{$~[:prefix]}#{@major}#{$~[:sep1]}#{@minor}#{$~[:sep2]}#{@patch}#{$~[:postfix]}" }
+
+    #Insert start/end tags if not present
+    text += new_changelog unless text.match(CHANGELOG_START)
+
+    text.gsub!(CHANGELOG_START) { |match| [match, format_changelog_entry(entry)].join("\n") }
+
+    File.open(output_file_name, 'w') { |f| f.write(text) }
+  end
+
+  def write!
+    write(@src)
+  end
+
+  def to_s
+    "#{@major}.#{@minor}.#{@patch}"
+  end
+
+  def strip_comment_prefix(line)
+    line.gsub(/^\s*#{Regexp.escape(@comment_prefix)}\s?/,'')
+  end
+
+  def changelog
+    in_changelog = false
+    File.open(@src).each_line do |line|
+      if in_changelog
+        break if line =~ CHANGELOG_END
+        yield strip_comment_prefix(line.chomp)
+      else
+        in_changelog = line =~ CHANGELOG_START
+      end
+    end
+  end
+
+  def last_changelog_entry
+    in_entry = false
+    lines = []
+    changelog do |line|
+      if line.length > 0
+        in_entry = true
+        lines << line
+      else
+        break if in_entry
+      end
+    end
+    lines
+  end
+
+  # Prefixes the entry with an empty line, then prefixes each line with comment chars
+  # and converts the line entries to a single string
+  def format_changelog_entry(entry_lines)
+    entry_lines.unshift('').map { |line| "#{@comment_prefix} #{line}"}.join("\n")
+  end
+
+  def get_changelog_entry
+    entry_lines = []
+    entry_lines << "Version #{self} (#{Time.now.strftime("%d %b %Y")})"
+    puts('Changelog entry (one item per line / empty line to end)')
+    puts('N.B. Git commit entry will use revision ID and first line of entry')
+    while line = $stdin.readline.strip
+      break if line.length == 0
+      entry_lines << "- #{line}"
+    end
+    entry_lines
+  end
+
+end

data/lib/revision/releasable.rb

@@ -0,0 +1,152 @@
+require 'pathname'
+require 'yaml'
+require 'zip'
+require 'git'
+
+module Revision
+
+  class Releasable
+
+    BUILD_DIR_BASE_NAME = "dist"
+    BUILD_CONFIGURATION_DEFAULT = "default"
+    BUILD_TARGET_DEFAULT = "production"
+    # RELATIVE_PATH_TO_BOOTLOADER = File.join("..","bootloader")
+    RELATIVE_PATH_TO_BOOTLOADER = "bootloader"
+
+    CONFIG_FILE_NAME = 'releasables.yaml'.freeze
+
+    REVISION_PLACEHOLDER = /<REV>|<VER>/
+
+    attr_reader :root, :id, :revision, :build_steps, :artefacts
+
+    # Load a file in yaml format containing one or more releasable definitions
+    # @param root [String] An optional root directory argument
+    # @return [Hash] Contents of the yaml file
+    def self.load_definitions(root: nil)
+      root ||= Dir.getwd
+      config_file = File.join(root, CONFIG_FILE_NAME)
+      raise Errors::NoDefinition.new(root) unless File.exist?(config_file)
+      puts "Loading releasable definitions from #{config_file} ..."
+      YAML.load_file(config_file)
+    end
+
+    # Instantiate the Releasables defined in releasables.yaml
+    def self.from_folder(root = Dir.getwd)
+      config = load_definitions(:root=>root)
+
+      releasables = {}
+      config[:releasables].each do |config_entry|
+        if config_entry[:folder]
+          #Load entries from a nested releasable definition file
+          releasables = releasables.merge(from_folder(File.join(root, config_entry[:folder])))
+        else
+          r = new(root: root, config: config_entry)
+          releasables[r.id] = r
+        end
+      end
+      releasables
+    end
+
+    def initialize(root: nil, config: {})
+
+      root ||= Dir.getwd
+      @root = Pathname.new(root).realpath
+      @id = config[:id] || File.basename(@root)
+      @revision = Info.new(File.join(@root,config[:revision][:src]), regex: config[:revision][:regex], comment_prefix: config[:revision][:comment_prefix])
+      @build_steps = config[:build_steps]
+      @artefacts = config[:artefacts]
+      @artefacts.each { |a| a[:dest] ||= a[:src] }
+    end
+
+    def to_s
+      <<~EOT
+      #{@id} v#{@revision} @ #{@root}
+
+        Build pipeline:
+        - #{@build_steps.join("\n  - ")}
+
+        Build artefacts:
+        #{artefacts.map{ |a| "- #{a[:src]}\n    => #{a[:dest]}" }.join("\n")}
+      EOT
+    end
+
+    def build
+      puts "Executing #{@build_steps.length} build steps..."
+      Dir.chdir(@root) do
+        @build_steps.each_with_index do |step, index|
+          puts "... (#{index+1}/#{@build_steps.length}) #{step}"
+          system(step)
+          puts "WARNING: build step #{index}: #{step} exit status #{$?.exitstatus}" unless $?.exitstatus.zero?
+        end
+      end
+    end
+
+    def tag
+      Dir.chdir(@root) do
+        tag_id = "v#{revision}"
+        changelog_entry = @revision.last_changelog_entry
+        #Insert a blank line between the revision header and release notes, as per git commit best practice
+        commit_lines = ["#{tag_id} #{changelog_entry[1]}", '']
+        if changelog_entry.length > 2
+          commit_lines << "Also..."
+          commit_lines += changelog_entry[2..-1]
+        end
+        commit_message = commit_lines.join("\n")
+        g = Git.init
+        puts "Committing..."
+        puts commit_message
+        g.commit_all(commit_message)
+        puts "Tagging as #{tag_id}"
+        g.add_tag(tag_id)
+      end
+    end
+
+    def push
+      pushed = false
+      Dir.chdir(@root) do
+        g = Git.init
+        begin
+          g.push('origin', g.current_branch, tags: true)
+          pushed = true
+        rescue GitExecuteError => e
+          puts "ERROR :: Cannot push to origin :: #{e}"
+        end
+      end
+      pushed
+    end
+
+    def archive_name
+      "#{@id}_v#{@revision}.zip"
+    end
+
+    def changelog_name
+      "#{@id}_revision_history_v#{@revision}.txt"
+    end
+
+    def archive
+      puts "Packaging #{@artefacts.length} build artefacts as #{archive_name}..."
+      if File.exist?(archive_name)
+        puts "... deleting existing archive"
+        File.delete(archive_name)
+      end
+      Zip::File.open(archive_name, Zip::File::CREATE) do |zipfile|
+        @artefacts.each_with_index do |a, index|
+          src = a[:src].gsub(REVISION_PLACEHOLDER, @revision.to_s)
+          dest = a[:dest].gsub(REVISION_PLACEHOLDER, @revision.to_s)
+          puts "... (#{index+1}/#{@artefacts.length}) #{src} => #{dest}"
+          zipfile.add(dest, File.join(@root, src))
+        end
+        puts "... embedding revision history as #{changelog_name} "
+        zipfile.get_output_stream(changelog_name) { |os| output_changelog(os)}
+      end
+    end
+
+    def output_changelog(output_stream)
+      output_stream.puts "Revision history for #{@id} version #{@revision}"
+      output_stream.puts ""
+      @revision.changelog {|line| output_stream.puts(line)}
+    end
+
+  end
+
+end

data/lib/revision/string_case.rb

@@ -0,0 +1,36 @@
+class String
+  # ruby mutation methods have the expectation to return self if a mutation occurred, nil otherwise. (see http://www.ruby-doc.org/core-1.9.3/String.html#method-i-gsub-21)
+  def to_underscore!
+    gsub!(/::/, '/')
+    gsub!(/([A-Z]+)([A-Z][a-z])/,'\1_\2')
+    gsub!(/([a-z\d])([A-Z])/,'\1_\2')
+    tr!("-", "_")
+  end
+
+  ##
+  # Converts _SnakeCase_ to _snake_case_
+  def to_snake_case!
+    to_underscore!
+    downcase!
+  end
+
+  ##
+  # Converts _ScreamingSnakeCase to _SCREAMING_SNAKE_CASE_
+  def to_screaming_snake_case!
+    to_underscore!
+    upcase!
+  end
+
+  def to_underscore
+    dup.tap { |s| s.to_underscore! }
+  end
+
+  def to_snake_case
+    dup.tap { |s| s.to_snake_case! }
+  end
+
+  def to_screaming_snake_case
+    dup.tap { |s| s.to_screaming_snake_case! }
+  end
+
+end

data/lib/revision/version.rb

@@ -0,0 +1,45 @@
+# Defines the revision ID for the revision gem
+module Revision
+  VERSION = "1.1.4"
+end
+
+# <BEGIN CHANGELOG>
+# 
+# Version 1.1.4 (14 Dec 2017)
+# - Minor message body reformatting
+# 
+# Version 1.1.3 (14 Dec 2017)
+# - Eliminated duplication of version ID in commit message body
+# 
+# Version 1.1.2 (14 Dec 2017)
+# - Removed redundant ':: ' from commit message headline
+# 
+# Version 1.1.1 (14 Dec 2017)
+# - Added git connection failure handling
+# - Revision commit message now includes first line of changelog entry
+# - Updated configuration syntax for consistency (:revision: :file: -> :revision: :src:)
+# 
+# Version 1.1.0 (13 Dec 2017)
+# - Updated to optionally push tags to the repo
+# 
+# Version 1.0.1 (13 Dec 2017)
+# - Corrected revision placeholder handling when archiving build artefacts
+# - Added proper high-level usage documentation
+# 
+# Version 1.0.0 (12 Dec 2017)
+# - First fully functional release with new config file
+# 
+# Version 0.1.4 (12 Dec 2017)
+# - boo
+# - hoo
+# - hoo
+# 
+# Version 0.1.3 (12 Dec 2017)
+# - boo
+# 
+# Version 0.1.2 (12 Dec 2017)
+# - wahoo!
+# 
+# Version 0.1.1 (12 Dec 2017)
+# - Wahey!
+# <END CHANGELOG>

data/lib/revision.rb

@@ -0,0 +1,6 @@
+require "revision/version"
+
+module Revision
+  require 'revision/cli'
+  require 'revision/errors'
+end

data/releasables.yaml

@@ -0,0 +1,10 @@
+:releasables:
+  - :id: revision
+    :revision:
+      :src: lib/revision/version.rb
+      :regex: (?<prefix>VERSION = ")(?<major>\d+)(?<sep1>\.)(?<minor>\d+)(?<sep2>\.)(?<patch>\d+)(?<postfix>")
+      :comment_prefix: "#"
+    :build_steps:
+      - bundle exec rake install
+    :artefacts:
+      - :src: pkg/revision-<VER>.gem

data/revision.gemspec

@@ -0,0 +1,40 @@
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "revision/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "revision"
+  spec.version       = Revision::VERSION
+  spec.authors       = ["Cormac Cannon"]
+  spec.email         = ["cormac.cannon@neuromoddevices.com"]
+
+  spec.summary       = %q{Language-agnostic revision management tool}
+  spec.description   = %q{Updates project revision identifiers in software source files and associated change log. Can also build and package project archives as a zip and optionally commit, tag and push to a Git repo.}
+#  spec.homepage      = "TBC"
+
+  # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
+  # to allow pushing to a single host or delete this section to allow pushing to any host.
+  # if spec.respond_to?(:metadata)
+  #   spec.metadata["allowed_push_host"] = "http://gems.nmd.ie"
+  # else
+  #   raise "RubyGems 2.0 or newer is required to protect against " \
+  #     "public gem pushes."
+  # end
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^#{spec.bindir}/}) { |f| File.basename(f) }
+
+  spec.require_paths = ["lib"]
+
+  spec.add_runtime_dependency 'thor', '~> 0.19.1'
+  spec.add_runtime_dependency 'rubyzip'
+  spec.add_runtime_dependency 'git'
+
+  spec.add_development_dependency "bundler", "~> 1.16"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "pry"
+end

metadata

@@ -0,0 +1,162 @@
+--- !ruby/object:Gem::Specification
+name: revision
+version: !ruby/object:Gem::Version
+  version: 1.1.4
+platform: ruby
+authors:
+- Cormac Cannon
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2017-12-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.19.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.19.1
+- !ruby/object:Gem::Dependency
+  name: rubyzip
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: git
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !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: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Updates project revision identifiers in software source files and associated
+  change log. Can also build and package project archives as a zip and optionally
+  commit, tag and push to a Git repo.
+email:
+- cormac.cannon@neuromoddevices.com
+executables:
+- revision
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- Gemfile
+- README.org
+- Rakefile
+- bin/console
+- bin/setup
+- exe/revision
+- lib/revision.rb
+- lib/revision/cli.rb
+- lib/revision/errors.rb
+- lib/revision/info.rb
+- lib/revision/releasable.rb
+- lib/revision/string_case.rb
+- lib/revision/version.rb
+- releasables.yaml
+- revision.gemspec
+homepage: 
+licenses: []
+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.6.13
+signing_key: 
+specification_version: 4
+summary: Language-agnostic revision management tool
+test_files: []