This gem automates revision management for source projects. The tool is language agnostic (used for C, ruby, python and matlab projects, to date – though you’re probably better off using bundler for ruby projects). It supports per-project configuration using a yaml-format file called releasables.yaml located at the project root.

It currently supports the following functionality

• Manage 3-component revision IDs embedded natively in source file
• Embeds/updates/extracts changelog in source file header/footer comments
• Automatically prompts for a changelog entry each time a revision identifier is incremented
• Optionally commits and tags changes to a git repo after an update to the revision ID
• Builds and archives projects in zip format (including release notes and arbitrary release artefacts defined
• Deploys build artefacts to one or more defined (local or remote) filesystem locations
• Automatically generates md5sums when archiving or deploying build artefacts

Hacked on sporadically to allow me to tag, archive and deploy projects in multiple languages in a consistent fashion.

Ruby / Rubygems installed

gem install revision

git clone git@github.com:cormacc/revision

gem install bundler
git clone git@github.com:cormacc/revision
cd revision

bundle install
bundle exec rake install

Run the executable with no arguments to get usage instructions in your console window…

revision

A single releasables.yaml file can define multiple releasables, either implicitly (via inclusion) or explicitly (see Configuration section below for examples). In this context, the info and archive commands will operate on all defined releasables, whereas the remaining commands will require the releasable to be specified using the --id= option, e.g.

revision minor --id=firmware

YAML syntax is used for the configuration file. The Syntax and Examples sections below should provide sufficient introduction to the limit subset of language features required to use this tool, however further info may be found at the following links:

• http://docs.ansible.com/ansible/latest/YAMLSyntax.html
• http://www.yaml.org/start.html

The releasables.yaml file should contain a top level :releasables node. Under this, you can create a list (or YAML sequence) of releasable definitions.

Each sequence item begins with a - and contains either a link to a folder containing its own releasables.yaml defining one or more releasables …

- :folder: relative/path/to/a/releasable/folder

… or a single inline releasable definition.

:releasables
- :id: my_releasable
  :revision:
    # Source file containing the revision identifier
    # This will also include changelog entries, embedded as comments
    :src: lib/revision/version.rb
    # Regex matching the source revision identifier. Must contain the following named capture groups
    # - major, minor, patch :: Numeric (uint) sequences representing the three revision ID components
    # - sep1, sep2 :: the characters separating the revision components
    # - prefix, postfix :: sufficient syntactic context to match the revision ID uniquely
    # N.B. this regex matches the version ID from the standard bundler gem skeleton,
    # e.g. VERSION = "1.1.0"
    :regex: (?<prefix>VERSION = ")(?<major>\d+)(?<sep1>\.)(?<minor>\d+)(?<sep2>\.)(?<patch>\d+)(?<postfix>")
    # Comment char for the project language -- prefixed to each line of changelog entries
    # Quotes only necessary here to prevent # being interpreted as the beginning of a YAML comment
    :comment_prefix: "#"
    # Sequence of build steps -- each item should be a valid shell command, prefixed with the YAML sequence item token, '- '
    :build_steps:
      - bundle exec rake install
      # Sequence defining the files (build artefacts) to package in the release archive.
      # Each artefact definition must include a :src: key/value pair.
      # An optional :dest: value may be provided to rename the file during packaging, or just (as in the first entry below)
      # to flatten the folder structure.
      # Any <VER> (or <REV>) in the :src: or :dest: placeholders wil be replaced with the current revision ID
      # The revision archive will also include the revision history extracted as a text file
    :artefacts:
      # A binary artefact
      - :src: pkg/revision-<VER>.gem
        :dest: revision-<VER>.gem
      # ':dest:' defaults to the string specified for ':src:' if not specified explicitly
      # sha512 checksums are generated by default for each artefact -- the ':chk:' option allows this to be disabled per-artefact
      - :src: README.org
        :chk: false

e.g. via a .releasables configuration file in the user home dir. Though this would be bad for collaborative development as the config file would live outside source control. Possibly useful to support inclusion of a controlled configuration file instead? Primarily to define a revision regex and comment prefix for a group of related releasables….

:releasables:
  - :id: mbt_cd_firmware
    :revision:
      :src: src/FirmwareRevision.c
    :build_steps:
      - make --jobs=8 -f Makefile CONF=bootloadable
    :artefacts:
      - :src: dist/bootloadable/production/firmware.production.hex
        :dest: mbt_cd_firmware_v<REV>.bootloadable.hex
      - :src: dist/default/production/firmware.production.hex
        :dest: mbt_cd_firmware_v<REV>.standalone.hex

:releasables:
- :id: revision
  :revision:
    :src: lib/revision/version.rb
    :regex: (?<prefix>VERSION = ")(?<major>\d+)(?<sep1>\.)(?<minor>\d+)(?<sep2>\.)(?<patch>\d+)(?<postfix>")
    :comment_prefix: "#"
  :build_steps:
    - bundle exec rake install
  :artefacts:
    - :src: pkg/revision-<VER>.gem

Rather than defining the releasable parameters inline, a releasables.yaml list entry can contain a (relative or absolute) link to another folder containing it’s own releasables.yaml.

i.e assuming the earlier examples were in folders examples/c and examples/ruby relative to a common root, a separate releasables.yaml at that root could include them as follows…

:releasables:
  - :folder: examples/c
  - :folder: examples/ruby

:revision:
  :src: release_log.txt
  :releasables:
    - :folder: examples/c
    - :folder: examples/ruby

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem from source on your local machine, run bundle exec rake install from the repository root.

You can do this using the gem, by entering one of the following commands at the repository root

You’ll be prompted to rebuild the gem, commit changes to the git repo and add a revision tag to the commit.

Alternatively, manually update the version number in version.rb and rebuild/install locally using bundle exec rake install

bundle exec rake release, will create a git tag for the version (if not, push git commits and tags, and push the .gem file to [rubygems.org](https://rubygems.org).

Bug reports and pull requests are welcome on GitHub at https://github.com/cormacc/revision.