Allow alternate version to be specified from command line

doc/dev/releasing.md

@@ -2,8 +2,47 @@
 
 The project maintainers are responsible for bumping the version number, regenerating auto-generated documentation, tagging the release, and uploading to rubygems.
 
-0. Ensure that all changes have been merged to master.
+## Local testing
+
+To test the new version of `octocatalog-diff` in the Puppet repository:
+
+0. In the Puppet checkout, start a new branch based off master.
+0. In the `octocatalog-diff` checkout:
+  - Ensure that the desired branch is checked out.
+  - Choose a unique internal version number which has never been used in CI. A good guideline is that if you're planning to release a version `0.6.0` then for these tests, use `0.6.0a`, `0.6.0b`, ...
+  - Build the gem using your internal version number:
+
+    ```
+    OCTOCATALOG_DIFF_VERSION=0.6.0a rake gem:force-build
+    ```
+  - Run the task to install the gem into your Puppet checkout:
+
+    ```
+    OCTOCATALOG_DIFF_VERSION=0.6.0a rake gem:localinstall
+    ```
+
+0. Back in the Puppet checkout, ensure that the changes are as expected (updates to Gemfile / Gemfile.lock, addition of new gem). Push the change and build appropriate CI job(s) to validate the changes.
+
+## Merging
+
 0. If necessary, complete a Pull Request to update the [version file](/.version).
+0. If necessary, auto-generate the build documentation.
+
+  ```
+  rake doc:build
+  ```
+
+0. Ensure that CI tests are all passing.
+0. Merge and delete the branch.
+
+## Releasing
+
+Generally, a new release will correspond to a merge to master of one or more Pull Requests.
+
+0. Ensure that all changes associated with the release have been merged to master.
+  - Merge all Pull Requests associated with release.
+  - If necessary, complete a Pull Request to update the [change log](/doc/CHANGELOG.md).
+  - If necessary (for significant changes), complete a Pull Request to update the top-level README file.
 0. Ensure the the master branch is checked out on your system.
 0. Run the release procedure:
 
@@ -13,7 +52,6 @@ The project maintainers are responsible for bumping the version number, regenera
 
 This rake task handles the following:
 
-- Auto-generates the [options reference](/doc/optionsref.md) (`rake doc:build`)
 - Build the gem file (`rake gem:build`)
 - Tag the release in the repository (`rake gem:tag`)
 - Upload the gem file to rubygems (`rake gem:push`)

octocatalog-diff.gemspec

@@ -6,7 +6,7 @@ Gem::Specification.new do |s|
   s.required_ruby_version = '>= 2.0.0'
 
   s.name        = 'octocatalog-diff'
-  s.version     = OctocatalogDiff::Version::VERSION
+  s.version     = ENV['OCTOCATALOG_DIFF_VERSION'] || OctocatalogDiff::Version::VERSION
   s.license     = 'MIT'
   s.authors     = ['GitHub, Inc.', 'Kevin Paulisse']
   s.email       = 'opensource+octocatalog-diff@github.com'

rake/gem.rb

@@ -6,8 +6,17 @@
 module OctocatalogDiff
   # A class to contain methods and constants for cleaner code
   class Gem
+    # Override version number from the environment
+    def self.version
+      version = ENV['OCTOCATALOG_DIFF_VERSION'] || OctocatalogDiff::Version::VERSION
+      unless version == OctocatalogDiff::Version::VERSION
+        warn "WARNING: Using version #{version}, not #{OctocatalogDiff::Version::VERSION}"
+      end
+      version
+    end
+
     BASEDIR = File.expand_path('..', File.dirname(__FILE__)).freeze
-    VERSION = OctocatalogDiff::Version::VERSION
+    VERSION = version.freeze
     GEMFILE = "octocatalog-diff-#{VERSION}.gem".freeze
     PKGDIR = File.join(BASEDIR, 'pkg').freeze
     OUTFILE = File.join(BASEDIR, GEMFILE).freeze
@@ -34,12 +43,15 @@ def self.build(target = GEMFILE)
 
     # Push the gem to rubygems
     def self.push
+      raise 'Cannot push version that does not match .version file' unless version == OctocatalogDiff::Version::VERSION
       raise "The gem file doesn't exist: #{FINAL_GEMFILE}" unless File.file?(FINAL_GEMFILE)
       exec_command("gem push #{Shellwords.escape(FINAL_GEMFILE)}")
     end
 
     # Tag the release on GitHub
     def self.tag
+      raise 'Cannot tag version that does not match .version file' unless version == OctocatalogDiff::Version::VERSION
+
       # Make sure we have not released this version before
       exec_command('git fetch -t origin')
       tags = exec_command('git tag -l').split(/\n/)
@@ -77,8 +89,12 @@ def self.exec_command(command)
 
   task 'force-build' do
     branch = OctocatalogDiff::Gem.branch
-    warn "WARNING: Force-building from non-master branch #{branch}" unless branch == 'master'
-    OctocatalogDiff::Gem.build("octocatalog-diff-#{OctocatalogDiff::Gem::VERSION}-#{branch}.gem")
+    unless branch == 'master'
+      warn "WARNING: Force-building from non-master branch #{branch}"
+    end
+
+    version = OctocatalogDiff::Gem.version
+    OctocatalogDiff::Gem.build("octocatalog-diff-#{version}-#{branch}.gem")
   end
 
   task 'push' do
@@ -127,7 +143,7 @@ def self.exec_command(command)
 
     # Make sure the gem has been built
     branch = OctocatalogDiff::Gem.branch
-    version = OctocatalogDiff::Gem::VERSION
+    version = OctocatalogDiff::Gem.version
     gemfile = if branch == 'master'
       OctocatalogDiff::Gem::FINAL_GEMFILE
     else