short_version

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

Features

Based on SemanticVersion from the standard library and is comparable with and convertible to SemanticVersion. Includes a SemanticVersion Extension that adds convenience functionality to SemanticVersion. and a ShortVersionConverter for use with JSON::Serializable.

Documentation

• Library API

Installation

1. Add the dependency to your shard.yml

dependencies:
  short_version:
    github: mraffonso/short_version
    version: ~> 0.1.0

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 release is three steps: tag a commit (the current one), push the tag to origin, and create a github release. The ./script/release script was created to automate this and provide a few guard rails.

The current release workflow is:

• Update the version specified in shard.yml
• Update instances of the version in README.md
• Commit with the message "Bump version to x.x.x"
• Push to main
• Run the release script with no arguments ./script/release
• Confirm release 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