Metasploit::Version

Metasploit::Version allows your gem to declare the pieces of its semantic version as constant and for your VERSION String to be automatically derived from those constants. Shared examples are available to test that the PRERELEASE String matches the expected pattern of using the branch relative name and being undefined on master.

Installation

Add this line to your application's Gemfile:

gem 'metasploit-version'

And then execute:

$ bundle

Or install it yourself as:

$ gem install metasploit-version

Usage

Gem version.rb

Your gem's version.rb file should have a Version Module that defines the parts of the semantic version and extend Metasploit::Version::Full. Then, VERSION in your gem's top-level namespace Module can be set to Version.full

module MyNamespace
  module MyGem
    # Holds components of {VERSION} as defined by {http://semver.org/spec/v2.0.0.html semantic versioning v2.0.0}.
    module Version
      #
      # CONSTANTS
      #

      # The major version number
      MAJOR = 0

      # The minor version number, scoped to the {MAJOR} version number.
      MINOR = 0

      # The patch number, scoped to the {MINOR} version number.
      PATCH = 1

      # The prerelease version, scoped to the {PATCH} version number.
      PRERELEASE = '<relative-name>'
      
      #
      # Module Methods
      #

      # The full version string, including the {MyNamespace::MyGem::Version::MAJOR},
      # {MyNamespace::MyGem::Version::MINOR}, {MyNamespace::MyGem::Version::PATCH}, and optionally, the
      # `MyNamespace::MyGem::Version::PRERELEASE` in the
      # {http://semver.org/spec/v2.0.0.html semantic versioning v2.0.0} format.
      #
      # @return [String] '{MyNamespace::MyGem::Version::MAJOR}.{MyNamespace::MyGem::Version::MINOR}.{MyNamespace::MyGem::Version::PATCH}'
      #   on master.  '{MyNamespace::MyGem::Version::MAJOR}.{MyNamespace::MyGem::Version::MINOR}.{MyNamespace::MyGem::Version::PATCH}-PRERELEASE'
      #   on any branch other than master.
      def self.full
        version = "#{MAJOR}.#{MINOR}.#{PATCH}"

        if defined? PRERELEASE
          version = "#{version}-#{PRERELEASE}"
        end

        version
      end

      # The full gem version string, including the {MyNamespace::MyGem::Version::MAJOR},
      # {MyNamespace::MyGem::Version::MINOR}, {MyNamespace::MyGem::Version::PATCH}, and optionally, the
      # `MyNamespace::MyGem::Version::PRERELEASE` in the
      # {http://guides.rubygems.org/specification-reference/#version RubyGems versioning} format.
      #
      # @return [String] '{MyNamespace::MyGem::Version::MAJOR}.{MyNamespace::MyGem::Version::MINOR}.{MyNamespace::MyGem::Version::PATCH}'
      #   on master.  '{MyNamespace::MyGem::Version::MAJOR}.{MyNamespace::MyGem::Version::MINOR}.{MyNamespace::MyGem::Version::PATCH}.PRERELEASE'
      #   on any branch other than master.
      def self.gem
        full.gsub('-', '.pre.')
      end
    end

    # (see Version.gem)
    GEM_VERSION = Version.gem

    # (see Version.full)
    VERSION = Version.full
  end
end

On a branch such the relative name is the portion after the branch type as in bug/<relative-name>, chore/<relative-name>, feature/<relative-name>, or staging/<relative-name>. On master, the gem is assumed to no longer be in prerelease, so PRERELEASE should not be defined. If it is defined, the 'Metasploit::Version Version Module' shared example will fail.

spec_helper.rb

In your spec_helper.rb, require the shared examples from metasploit-version.

# Use find_all_by_name instead of find_by_name as find_all_by_name will return pre-release versions
gem_specification = Gem::Specification.find_all_by_name('metasploit-version').first

Dir[File.join(gem_specification.gem_dir, 'spec', 'support', '**', '*.rb')].each do |f|
  require f
end

Gem namespace spec

The spec for your gem's namespace Module should use the 'Metasploit::Version VERSION constant' shared example.

require 'spec_helper'

describe MyNamespace::MyGem do
  it_should_behave_like 'Metasploit::Version VERSION constant'
  it_should_behave_like 'Metasploit::Version GEM_VERSION constant'
end

Gem Version spec

The spec for your gem's Version Module defined in the version.rb file should use the 'Metasploit::Version Version Module' shared example.

require 'spec_helper'

describe MyNamespace::MyGem::Version do
  it_should_behave_like 'Metasploit::Version Version Module'
end

Contributing

See CONTRIBUTING.md