Metanorma Version Registry

Static version registry for Metanorma across multiple package sources.

Purpose

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

• Gemfile (Docker) - Gemfile/Gemfile.lock.archived files extracted from Docker Hub images

• Snap - Snapcraft snap packages with revision tracking

• Homebrew - macOS Homebrew formula versions from GitHub tags

• Chocolatey - Windows Chocolatey packages

• Binary (packed-mn) - Pre-compiled binaries from GitHub releases

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

Reading version data directly

The version data is stored in YAML files under data/ directory. You can read these files directly:

# View all Gemfile versions
cat data/gemfile/versions.yaml

# View all Snap versions with revisions
cat data/snap/versions.yaml

# View all Homebrew versions
cat data/homebrew/versions.yaml

# View all Chocolatey versions
cat data/chocolatey/versions.yaml

# View all Binary (packed-mn) versions
cat data/binary/versions.yaml

Parsing YAML with yq

# Get the latest version from each source
yq '.metadata.latest_version' data/gemfile/versions.yaml
yq '.metadata.latest_version' data/snap/versions.yaml
yq '.metadata.latest_version' data/homebrew/versions.yaml
yq '.metadata.latest_version' data/chocolatey/versions.yaml
yq '.metadata.latest_version' data/binary/versions.yaml

# Get version count
yq '.metadata.count' data/gemfile/versions.yaml

# Get all version numbers
yq '.versions[].version' data/gemfile/versions.yaml

# Get specific version info (Snap example with revision)
yq '.versions[] | select(.version == "1.14.4")' data/snap/versions.yaml

# Get platforms for a binary version
yq '.versions[] | select(.version == "1.14.4") | .platforms' data/binary/versions.yaml

Parsing YAML with Ruby

require 'yaml'

# Load Gemfile versions
data = YAML.load_file('data/gemfile/versions.yaml')
puts "Latest: #{data['metadata']['latest_version']}"
puts "Count: #{data['metadata']['count']}"

# Find specific version
version_1_14_4 = data['versions'].find { |v| v['version'] == '1.14.4' }

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.

Historical Gemfile lock archive

This repository stores Gemfile and Gemfile.lock.archived 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.

License

This repository is available as open source under the terms of the {file-license}[MIT License].

Copyright

Copyright (c) 2025 Ribose Inc.