Project

lapidist

0.0
No release in over 3 years
Low commit activity in last 3 years
There's a lot of open issues
lapidistmetanorma/lapidistHomepageDocumentationSource CodeBug TrackerWiki
Synchronized gem releases
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Popularity
Downloads
4,206
Stars
1
Forks
0
Watchers
12
 Releases
Current version
0.1.1
Total releases
2
First release
2019-09-12
Latest release
2019-09-12
 Issues
Open Issues
6
Closed Issues
8
Total Issues
14
Issue Closure Rate
57%
 Pull Requests
Open Pull Requests
0
Closed Pull Requests
0
Merged Pull Requests
12
Pull Request Acceptance Rate
100%
 Development
Primary Language
Ruby
Average date of last 50 commits
2020-06-05
Reverse Dependencies
0

 Dependencies

Development

bundler
~> 2.0
rake
~> 10.0
rspec
~> 3.0

Runtime

gem-release
>= 0
 Project Readme

Lapidist: synchronized gem releases

tests

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

root gem

a gem that is no other software is dependent on

dependent gem

a gem that other gems depend on

leaf 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

Requirements

  • hub must be installed

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

Flow

Start release process

It all starts with the start subcommand.

Note
 If you wish to run the Git version of lapidist, use bundler and a Gemfile; you will want to replace the command lapidist with lapidist for all steps below.

Go to the release repository:

lapidist start -p .. -b 'feature/some-feature' -g isodoc,metanorma-iso,metanorma,metanorma-cli
-p

path to .gitmodules file

-b

branch name for feature, the same name will be used across all gems

-g

comma-separated list of gems which will be included in feature (if missed default all gems included)

Finally this command will ask you to push changes to remote.

Under the hood this command does the following:

  • use bundler to set local path to gems

  • generate Gemfile.devel to keep CI “green”

Updating code and integrated testing

  1. Go to your release repository.

Note
 If you have missed some gem, you can run lapidist start …​ for it separately but keep branch name the same.

  1. Do the necessary work in the submodule’d gem in the gem net (within the release repository) i.e. isodoc or metanorma-iso.

  2. Run a script that performs tests on all the gems at once using the newly created feature branches:

lapidist rake -p .. -b 'feature/some-feature'

  1. If you want Travis and Appveyor to test for you, and/or if you want to create PRs, run a script that pushes gems with the feature branches:

lapidist push -p .. -b 'feature/some-feature'

  1. When all the gems pass locally, create PRs for feature/some-feature → master

  2. Before merge finish feature with:

lapidist finish -p .. -b 'feature/some-feature'

  1. (alt) this will lead for short time breaks on CI till gems will be actually released

    1. Merge PRs by hand or by script (into master or a release branch)

Releasing

When all PRs merged, run a script to:

  1. Re-run tests against master (or release) branch to ensure integration of PRs has not introduced problems, and that any external gem releases you are not responsible for have been taken into account (e.g. metanorma stack depending on relaton stack). This test set will involve a new integration testing branch, forked from master (or release):

lapidist start -p .. -b 'test/date' -g isodoc,metanorma-iso,metanorma,metanorma-cli
lapidist rake -p .. -b 'test/date'
lapidist push -p .. -b 'test/date'
lapidist finish -p .. -b 'test/date'

Any needed fixes will be against this new integration testing branch, and would trigger new PRs.

Once integration testing is done, run a script to:

  1. Update gemspecs dependencies version of recently released gems

  2. Run this to release passed gems:

lapidist release -p .. -v patch -g isodoc,metanorma-iso,metanorma,metanorma-cli

  1. The release command will do:

    1. version bump

    2. commit bump

    3. do tag

    4. push tag to git

    5. build gem

    6. release gem to rubygems.org

Ideally, we want to update the leaf gems first, then the immediately dependent gems, and so forth towards the root gems 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.

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.

Origin of the name

A “lapidist” is someone who cuts, polishes, or engraves gems. Geddit?

Note
 The noun form of “lapidary” is now more popular than “lapidist” in this meaning, but the current usage also conflates the “person” (“the lapidary”), and the relation to gem processing (“a lapidary engraving”).

Release flow diagrams

Slide1
Slide2
Slide3
Slide4
Slide5
Slide6