Metanorma Version Register

Static version register for Metanorma across multiple package sources.

Purpose

This repository serves as a read-only version register for Metanorma, storing version metadata and Gemfile archives from various distribution channels:

Gemfile (Docker)

Gemfile/Gemfile.lock.archived files extracted from metanorma/metanorma Docker images for each version (built at metanorma-docker using Gemfiles)

Snap

Snapcraft snap packages with revision tracking (built at metanorma-snap wrapping packed-mn binaries)

Homebrew

macOS Homebrew formula versions from GitHub tags (built at homebrew-metanorma wrapping packed-mn binaries)

Chocolatey

Windows Chocolatey packages (built at chocolatey-metanorma wrapping packed-mn binaries)

Binary (packed-mn)

Pre-compiled binaries from GitHub releases at packed-mn

This enables actions-mn and mnenv to provide version selection across all platforms.

Related repositories

mnenv

Metanorma version manager CLI (installation, version switching, shim management)

actions-mn

GitHub Actions for setting up Metanorma

Data structure

Version data is stored in YAML files under data/:

data/
├── gemfile/
│   ├── versions.yaml          # Gemfile version metadata
│   └── v1.14.4/               # Gemfile extraction per version
│       ├── Gemfile
│       └── Gemfile.lock.archived
├── snap/
│   └── versions.yaml          # Snap versions with revision data
├── homebrew/
│   └── versions.yaml          # Homebrew versions from tags
├── chocolatey/
│   └── versions.yaml          # Chocolatey versions
└── binary/
    └── versions.yaml          # Binary (packed-mn) versions with platform info

Version object structure

Each version object in YAML contains:

version: "1.14.4"
published_at: "2025-01-15T10:30:00Z"
parsed_at: "2025-01-15T10:30:00Z"

Additional fields per source:

• Gemfile - gemfile_exists, gemfile_path, gemfile_lock_path

• Snap - revision, arch, channel

• Homebrew - tag_name, commit_sha

• Chocolatey - package_name, is_pre_release

• Binary - tag_name, html_url, platforms (array with name, arch, variant, format, filename)

Usage

Using Gemfile files for a version

To install the exact gems from a specific Metanorma Docker version:

# Clone this repository
git clone https://github.com/metanorma/versions.git

# Copy the files for your desired version
cp versions/data/gemfile/v1.14.4/Gemfile /path/to/your/project/
cp versions/data/gemfile/v1.14.4/Gemfile.lock.archived /path/to/your/project/Gemfile.lock

# Install the exact gems
cd /path/to/your/project
bundle install

Finding the Docker image version

The Docker image tag corresponds to the metanorma-cli version:

# Check the Gemfile to see the metanorma-cli version
grep "metanorma-cli" data/gemfile/v1.14.4/Gemfile
# Output: gem "metanorma-cli", "= 1.14.4"

# Pull the corresponding Docker image
docker pull metanorma/metanorma:1.14.4

Data updates

Version data is automatically updated via GitHub Actions workflows:

• fetch-gemfile.yml - Extracts Gemfiles from Docker Hub

• fetch-snap.yml - Fetches Snap versions from Snapcraft API

• fetch-homebrew.yml - Fetches Homebrew versions from GitHub tags

• fetch-chocolatey.yml - Fetches Chocolatey versions from Chocolatey API

• fetch-binary.yml - Fetches Binary (packed-mn) versions from GitHub releases

These workflows run on schedule and can also be triggered manually.

Note

All version data sources can be completely rebuilt by re-running the corresponding workflow with the revamp option, with the fetch-snap.yml workflow the exception because Snapcraft does not provide historical revision data through its public API (which this repository uses). The full rebuild of the Snap versions data source is only possible by using the private Snapcraft API, which is not currently implemented in the workflow.

Historical Gemfile lock archive

This repository stores Gemfile and Gemfile.lock files extracted from Docker Hub: metanorma/metanorma Docker containers for each version of Metanorma.

When deploying or using Metanorma, you may need to install the exact same gem versions that are used in a specific Docker container release. This repository provides the Gemfile and Gemfile.lock.archived files for each version of the metanorma/metanorma Docker image, allowing you to replicate the exact gem dependency set.

Note	The Gemfile.lock files from the Docker images are renamed with the .archived suffix to avoid GitHub issuing security alerts for outdated gems.

Copyright and license

Copyright Ribose.

This repository is available as open source under the terms of the Ribose 3-clause BSD license.