Relaton Monorepo

Monorepo for the Relaton family of Ruby gems: a database, registry, cache, and plugin ecosystem for bibliographic references to technical standards.

GitHub repo: https://github.com/relaton/relaton. The relaton/relaton-db repo is the upstream history source for gems/relaton/ (renamed upstream); subtree imports pull from it via monorepo_importer.rb.

Layout

gems/
├── relaton/             # central DB (Relaton::Db) + runtime deps on every flavor
├── relaton-core/        # foundational utilities
├── relaton-index/       # index file support
├── relaton-logger/      # logging helpers
├── relaton-bib/         # bibliographic item model (lutaml-model)
├── relaton-cli/         # command-line interface (optional, NOT a `relaton` dep)
└── relaton-<flavor>/    # 28 flavor plugins: iso, ietf, nist, ieee, gb, …
lib/relaton/version.rb   # master MAJOR.MINOR for the monorepo
Gemfile                  # auto-discovers all gems in gems/
Rakefile                 # per-gem and aggregate tasks
release-order.json       # dep-aware release sequence
monorepo_importer.rb     # subtree import script for adding/refreshing gems

Quick start

bundle install
bundle exec rake test:all              # run every gem's spec suite
bundle exec rake test:relaton_iso      # run a single gem's specs
bundle exec rake test:failed           # re-run only previously failed specs
bundle exec rake test:failed:relaton_iso  # re-run the next failing spec for one gem
bundle exec rake version:show          # show master + per-gem versions
bundle exec rake -T                    # all available tasks

Versioning model

Shared MAJOR.MINOR across all gems, driven by lib/relaton/version.rb (Relaton::MONOREPO_VERSION).
Independent PATCH per gem — bump one gem’s patch without bumping peers.
Inter-gem dependencies pinned with ~> MAJOR.MINOR (any patch within the current minor is acceptable).

bundle exec rake version:check                      # enforce MAJOR.MINOR sync
bundle exec rake "version:bump[minor]"              # bump master MAJOR.MINOR, sync all
bundle exec rake "version:bump_patch[relaton-iso]"  # bump one gem's PATCH only

Working on a single gem

Each gems/<gem>/ is a normal Ruby gem (with its own Gemfile, Rakefile, spec/, gemspec). You can also work inside it directly:

cd gems/relaton-iso
rm -f Gemfile.lock
bundle
bundle exec rake

The per-gem Gemfile uses path: "../<sibling>" for cross-gem deps, so local changes are picked up without reinstalling.

`Relaton::Db` namespace

In this monorepo the legacy top-level classes have moved under Relaton::Db:

Old	New
`Relaton::DbCache`	`Relaton::Db::Cache`
`Relaton::Registry`	`Relaton::Db::Registry`
`Relaton::Configuration`	`Relaton::Db::Configuration`
`Relaton::WorkersPool`	`Relaton::Db::WorkersPool`
`Relaton::Util`	`Relaton::Db::Util`
`Relaton::VERSION`	`Relaton::Db::VERSION`
`Relaton.configure`	`Relaton::Db.configure`

Relaton::Db itself (the main DB class) is unchanged. There are no backward-compat aliases — downstream code must update to the new names.

Importing a new gem

The monorepo_importer.rb script subtree-imports a gem from its individual GitHub repo into gems/<name>/, preserving the upstream history as git objects.

# Import all known gems (idempotent — pulls into existing dirs)
ruby monorepo_importer.rb

# Import one
ruby monorepo_importer.rb relaton-iso

# Override the source branch
SOURCE_BRANCH=main ruby monorepo_importer.rb relaton-iso

To add a brand-new gem, append its name to GEMS in monorepo_importer.rb and re-run; or scaffold a fresh gems/<name>/ directory directly. Either way, add the gem to release-order.json in the right position based on its dependencies.

Release process

bundle exec rake test:all passes locally.
Trigger the release workflow on GitHub Actions:
- version_type = minor|major bumps the shared MAJOR.MINOR and tags a new monorepo version.
- version_type = skip releases gems at their current per-gem PATCH versions without bumping the master.
Gems push to RubyGems in dep-aware order (see release-order.json): logger → core → index → bib → flavor plugins → iso-dependent flavors → doi → relaton (depends on every flavor) → relaton-cli (depends on relaton).

Required repo secrets:

RELATON_CI_PAT_TOKEN — personal access token for repo dispatches.
RELATON_CI_RUBYGEMS_API_KEY — RubyGems API key with push rights for every gem.

Gems in this monorepo

Foundational: relaton-logger, relaton-core, relaton-index, relaton-bib.

Main: relaton — the central DB (Relaton::Db API, registry, cache) plus runtime deps on every flavor plugin. gem install relaton gives you the full multi-flavor setup in one step.

CLI: relaton-cli (optional; NOT a relaton runtime dep).

Flavor plugins (28): relaton-3gpp, relaton-bipm, relaton-bsi, relaton-calconnect, relaton-ccsds, relaton-cen, relaton-cie, relaton-doi, relaton-ecma, relaton-etsi, relaton-gb, relaton-iana, relaton-iec, relaton-ieee, relaton-ietf, relaton-iho, relaton-isbn, relaton-iso, relaton-itu, relaton-jis, relaton-nist, relaton-oasis, relaton-ogc, relaton-omg, relaton-plateau, relaton-un, relaton-w3c, relaton-xsf.

History

Each gem was subtree-imported from its individual relaton/<gem> GitHub repo with the original commits preserved as objects in this repo’s .git/. File history follows across the import boundary via:

git log --follow -- gems/<gem>/path/to/file.rb
git blame -CCC gems/<gem>/path/to/file.rb

GitHub’s web UI also traces history across the import for most files.

License

BSD-2-Clause. Each gem may carry its own LICENSE file with the same terms.

relaton

Runtime