VersionInfo

Current status

Build Status Gem Version

Install

VersionInfo is at https://rubygems.org/gems/version_info, so:

gem install version_info

Usage

VersionInfo is a powerful and lightweight gem to manage version data in your Ruby projects or gems. And is very user friendly thanks to rake / thor tasks:

First, include VersionInfo in your main project module (or class):

    require 'version_info'

    module MyProject
      VERSION = "1.5.0"

      include VersionInfo
      VERSION.file_name = __FILE__ 
    end

Then use rake/thor tasks:

rake vinfo:minor

=> version changed to 1.6.0

Please, note here VersionInfo is included after the constant VERSION, if you don't like this also works

    module MyProject
      include VersionInfo
      self.VERSION = "1.5.0"
      VERSION.file_name = __FILE__ 
    end

Please note here you are invoking a singleton method and not using a constant. When included VersionInfo does a bit of magic and then you can use both the method and the constant:

    MyProject.VERSION  # it works
    MyProject::VERSION # also works

One more sample:

    Gem::Specification.new do |s|
      s.name        = "my_gem"
      s.version     = MyGem::VERSION
      s.platform    = Gem::Platform::RUBY

After VersionInfo is included, the singleton method and the constant returns a object of class VersionInfo::Data. You can use some methods from it, (#bump, #to_s, #tag, etc.). Also you get another singleton method to easy assignment:

    MyProject.VERSION= "2.0.2"  # also works

Features

  • rake & thor tasks avaiables to yaml file creation, bump segments and show info

  • can define custom segments to build your version tag with the tipical structure X.X.X.X.

  • can use a custom tag format: do you want a tag like "1-3-1pre"?. No problem!.

  • can include any custom info in your version data.

  • good rspec tests

  • Flexible formats for stored your version data:

  1. Using a text file. Content of your version.rb file:
   VersionInfo.file_format= :text    
   module MyProject
     include VersionInfo
     VERSION.file_name = /some_path/your_version_file #convenient but optional for this format
   end

The file is created "on demand". For example, you can invoke the task vinfo:show The version data file is named by default VERSION and looks like.

2.2.3
   author: jcangas
   email: [email protected]
  1. Using a yaml file, as a hash. Content of your version.rb file:
   VersionInfo.file_format= :yaml    
   module MyProject
     include VersionInfo
     VERSION.file_name = /some_path/your_file.yaml #convenient but optional for this format
   end

The file is created "on demand". For example, you can invoke the task vinfo:show The version data file is named by default VERSION and looks like.

--- 
    major: 1
    minor: 1
    patch: 4
    author: jcangas
  1. Using a ruby source (default). Content of your version.rb file:
   module MyProject
     include VersionInfo
     self.VERSION = "1.5.0"
     VERSION.file_name = __FILE__ # required for this format
   end

You write this file. and no version data file is needed: VERSION const is already here (you see it, isn't?)

Pleae, feel free to contact me about bugs/features

Rake / Thor tasks

Put in your rake or thor file:

    VersionInfo::install_tasks(:target => MyProject) # pass here the thing where you included VersionInfo

And you get a few tasks with a namespace vinfo:

rake -T
=>
rake vinfo:file  # Show version file format & name
rake vinfo:inspect  # Show complete version info
rake vinfo:major  # Bumps version segment MAJOR
rake vinfo:minor  # Bumps version segment MINOR
rake vinfo:patch  # Bumps version segment PATCH
rake vinfo:show   # Show current version tag and create version_info.yml if missing


thor list
=>

vinfo
-----
rake vinfo:file  # Show version file format & name
thor vinfo:bump SEGMENT=patch  # bumps segment: [major, minor, patch, build]...
thor vinfo:inspect             # Show complete version info
thor vinfo:show                # Show version tag and create version_info.yml...

Note all tasks works with any version format file!!. So is very easy to migrate for one to the other.

Bonus: Custom segments and tag format.

You can override the default segments

   VersionInfo.segments = [:a, :b, :c]
   module MyProject
     include VersionInfo
   end

Note this must be done before include VersionInfo.

Also, tag format can be redefined. VersionInfo uses simple sprintf in order to build the tag string. Here is the code:

    def tag
      tag_format % to_hash
    end

By default, tag_format, returns a simple sprintf format string, using the segment names, expecting their values are numbers:

   def tag_format
     @tag_format ||= VersionInfo.segments.map { |k| "%<#{k}>d"}.join('.')
   end

So tag_format return some like "%<major>d.%<minor>d%<patch>d".

If your VersionInfo yaml file is like:

    --- 
    major: 2
    minor: 1
    patch: 53
    buildflag: pre

You can change the tag format in this way

    MyProject::VERSION.buildflag = 'pre'
    MyProject::VERSION.tag_format = MyProject::VERSION.tag_format + "--%<buildflag>s"
    puts MyProject::VERSION.tag # => '2.1.53--pre'