short_version

A versioning scheme that uses only major and minor version numbers.

Features

Based on SemanticVersion from the standard library it is comparable with and convertible to SemanticVersion and has an optional extension that adds convenience functionality to SemanticVersion. Last, it has a converter for easy use with JSON::Serializable.

Installation

1. Add the dependency to your shard.yml

dependencies:
  short_version:
    github: mraffonso/short_version

2. Run shards install

Usage

Require the library.

require "short_version"

Create a ShortVersion.

ShortVersion.new(1, 1)
# => ShortVersion(@major=1, @minor=1)

ShortVersion.new(major: 2, minor: 3)
# => ShortVersion(@major=2, @minor=3)

OR parse from another format: String or SemanticVersion.

ShortVersion.parse("1.1")
# => ShortVersion(@major=1, @minor=1)

semver = SemanticVersion.new(1, 1, 2)
ShortVersion.parse(semver)
# => ShortVersion(@major=1, @minor=1)

Convert ShortVersion to SemanticVersion. Note: By default patch version is 0 unless otherwise specified.

shortver = ShortVersion.parse("1.1")

shortver.to_semver # Default patch version is 0
# => SemanticVersion(@major=1, @minor=1, @patch=0, ...)

shortver.to_semver(1) # Specify patch version
# => SemanticVersion(@major=1, @minor=1, @patch=1, ...)

Compare ShortVersion <=> ShortVersion.

ShortVersion.parse("1.2") < ShortVersion.parse("1.3") # => true
ShortVersion.parse("1.2") == ShortVersion.parse("1.2") # => true
ShortVersion.parse("1.2") > ShortVersion.parse("1.1") # => true

Compare ShortVersion <=> SemanticVersion.

ShortVersion.parse("1.2") < SemanticVersion.parse("1.3.0") # => true
ShortVersion.parse("1.2") == SemanticVersion.parse("1.2.3") # => true
ShortVersion.parse("1.2") > SemanticVersion.parse("1.1.19") # => true

ShortVersionConverter (Optional)

Converter to be used with JSON::Serializable to serialize a ShortVersion.

Require the converter.

require "short_version/converter"

Convert a SemanticVersion to ShortVersion.

Add the converter to the JSON::Field decorator.

struct Example
  include JSON::Serializable

  def initialize(@short_version)
  end

  @[JSON::Field(converter: ShortVersionConverter)]
  property short_version : ShortVersion
end

Parse json string and convert to ShortVersion.

example = Example.from_json("{\"short_version\":\"1.2\"}")
example.short_version # => ShortVersion(@major=1, @minor=2)

Convert ShortVersion to json string.

shortver = ShortVersion.parse("1.0")
example = Example.new(short_version: shortver)
example.to_json # => "{\"short_version\":\"1.0\"}"

SemanticVersion Extension (Optional)

Extending SemanticVersion is unnecessary but it adds some nice conveniences and may allow your code to flow more naturally.

Note: It extends the SemanticVersion Struct from the standard library by adding a to_shortver instance method and Comparable(ShortVersion) functionality.

Require the extension.

require "short_version/extensions/semantic_version"

Convert a SemanticVersion to ShortVersion.

semver = SemanticVersion.parse("1.2.3")
semver.to_shortver # => ShortVersion(@major=1, @minor=2)

# Without the extension
ShortVersion.parse(semver) # => ShortVersion(@major=1, @minor=2)

SemanticVersion parse ShortVersion.

shortver = ShortVersion.new(1, 2)
semver = SemanticVersion.parse(shortver)
semver # => SemanticVersion(@major=1, @minor=2, @patch=0, ...)

# Without the extension
ShortVersion.parse(semver) # => ShortVersion(@major=1, @minor=2)

Compare SemanticVersion <=> ShortVersion.

SemanticVersion.parse("1.2.3") < ShortVersion.parse("1.3") # => true
SemanticVersion.parse("1.2.3") == ShortVersion.parse("1.2") # => true
SemanticVersion.parse("1.2.3") > ShortVersion.parse("1.1") # => true

# Without the extension comparison must be reversed
ShortVersion.parse("1.1") < SemanticVersion.parse("1.2.3") # => true
ShortVersion.parse("1.2") == SemanticVersion.parse("1.2.3") # => true
ShortVersion.parse("1.3") > SemanticVersion.parse("1.2.3") # => true

Releasing

Creating a realease is just tagging a git commit. The ./script/tag shell script should be used for creating tags.

The current release workflow is:

• update the version specified in shard.yml
• commit with the message "Bump version to x.x.x"
• push to main
• run the tag script with no arguments ./script/tag
• confirm tag creation

And that's it, a release is created.

Contributing

1. Fork it (https://github.com/mraffonso/short_version/fork)
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

Contributors

• Mario Affonso - creator and maintainer