Scope

Certain projects are dependent on the interoperability of a web of gems. Changes to dependent gems, especially ones closer to the root, can cause many of the downstream gems to need upgrading.

For example, a release of Metanorma spans over 50 gems. Changes to an underlying gem like metanorma will require all downstream gems to re-run all tests.

This software is created to simplify the release procedure of dependent gems. It provides methods to:

  • Define this dependent web of gems

  • Synchronized gem testing among this dependent web of gems

  • Synchronized release of these gems (with version increments)

Terms and definitions

leaf gem

a gem that is no other software is dependent on

dependent gem

a gem that other gems depend on

root gem

a gem that does not depend on any other gem in the defined gem web

gem net

a coherent set of gems that needs to interoperate and that requires synchronized releasing

caught gem

gem under the release control of the releaser

release repository

git repository or directory used for the releasing process

Features

  1. Integration testing

    • all downstream gems can test against the work-in-progress upstream gems

    • management of Gemfile and gemspec version control

  2. Release process

    • automatic version bumps for gems

    • synchronized pushes of feature branches across gems

    • creation of PRs across gems

    • synchronized release of gems

Usage

Flow

This is a “composite-git-flow” kind of process. Maybe it’s called git gush or git cascade.

The typical scenario is:

  1. A leaf gem needs enhancing

  2. A leaf gem requires a dependent gem to be updated

  3. A dependent gem update means the testing on all its downstream gems needs to be updated

This is how the release flow looks like.

Create a repository with all gem sources

For example, the metanorma-release repository is a Lapidist-compatible release repository.

It contains the source code for all gems in the Metanorma “gem net”, each separated into its own directory at the root-level.

Updating code and integrated testing

  1. Go to the release repository

  2. Run a command to create feature branches in all gems. (TODO: what is the command?)

  3. Do the necessary work in the gem source code directory. (e.g. isodoc and metanorma-iso)

  4. Run a script that performs tests on all the gems at once using the newly created feature branches (TODO: what is the command?)

    1. (alt) if you want Travis to test for you, push the release repository, and Travis will build for you. (assuming the release repository is git managed and/or submoduled, like metanorma-release)

  5. When all the gems pass, run a script to make PRs to every repository. (TODO: what is the command?)

    1. If the feature branch for a gem is empty, the script will ignore it.

  6. Merge PRs by hand or by script (into master or a release branch) (TODO: what is the command?)

Releasing

  1. When a release branch is ready (for all gems), run a script to: (TODO: what is the command?)

    1. Bump version of those gems (VERSION variable in code)

    2. Update the Gemfiles (remove feature branches)

    3. Update gemspecs to lock versions

  2. Issue PRs for those gems to merge their release branches into master. (TODO: what is the command?)

  3. Merge the release PRs by hand or by script. (TODO: what is the command?)

Ideally, we want to update the base gems first, then the immediately dependent gems, and so forth to ensure that the builds always pass.

Installation

$ gem install lapidist

Development

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 onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to [rubygems.org](https://rubygems.org).

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/metanorma/lapidist. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

Code of Conduct

Everyone interacting in the Lapidist project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.