PubID: Interoperable identifiers for information resources

Badges

Core & Meta	Standards Organizations	Regional Standards
pubid	pubid-iso	pubid-cen
pubid-core	pubid-iec	pubid-bsi
	pubid-ieee	pubid-jis
	pubid-nist
	pubid-etsi
	pubid-itu
	pubid-ccsds
	pubid-plateau

Overview

The PubID project promotes the use of interoperable identifiers across various domains, including ISO, IEC, NIST, and more.

The core of PubID is an identifier information model that allows a publisher to build a human- and machine-readable identification scheme for the unique identification of documents, standards, and other resources.

This identification scheme is designed to facilitate interoperability and data exchange between systems and organizations by providing a consistent way to identify, reference and utilize these resources.

A PubID typically incorporates various components, such as a mixture of an organizational prefix, document type, document stage, edition or version number, and other relevant information.

The key feature that a PubID provides is the ability to represent identifiers in a structured format that can be easily parsed and understood by both humans and machines, in a round-trippable manner.

Repository

This repository is a monorepo for the PubID Ruby gems, which implement the PubID identifier data model and its various components.

The PubID Ruby gems implement identifiers from multiple standards organizations, making it easier for developers to work with them in their applications.

This repository contains all the pubid-* gems consolidated into a single monorepo for easier development and maintenance while preserving individual gem releases.

Structure

The monorepo is organized as follows:

.
├── gems/                    # Individual gem directories
│   ├── pubid/              # Meta-gem that includes common gems
│   ├── pubid-core/         # Core functionality
│   ├── pubid-iso/          # ISO identifiers
│   ├── pubid-iec/          # IEC identifiers
│   ├── pubid-nist/         # NIST identifiers
│   └── ...                 # Other pubid-* gems
├── spec/                   # Integration tests
│   └── integration/        # Cross-gem integration tests
├── .github/workflows/      # Shared CI/CD workflows
├── Gemfile                 # Root Gemfile for development
├── Rakefile               # Monorepo management tasks
├── .rubocop.yml           # Shared RuboCop configuration
├── .rspec                 # Shared RSpec configuration
└── LICENSE.txt            # Shared license

Development setup

Clone the repository:
```
git clone <repository-url>
cd pubid
```
Install dependencies:
```
bundle install
```
Run all tests:
```
bundle exec rake test:all
```

Working with individual gems

General

Each gem maintains its own:

pubid-*.gemspec: file for dependencies and metadata
lib/: directory for source code
spec/: directory for gem-specific tests

Each gem has its own individual versioning and release cycle.

Running tests for a specific gem

# Run tests for pubid-core
bundle exec rake test:pubid_core

# Run tests for pubid-iso
bundle exec rake test:pubid_iso

Building and installing gems

# Build a specific gem
bundle exec rake build:pubid_core

# Install a gem locally
bundle exec rake install:pubid_core

# Build all gems
bundle exec rake build:all

Integration testing

The monorepo includes integration tests that verify:

Dependency chains work correctly
Gems can be loaded together without conflicts
Cross-gem functionality works as expected

Run integration tests:

bundle exec rake test:integration

Code quality

RuboCop

Run RuboCop for all gems:

bundle exec rake rubocop:all

Run RuboCop for a specific gem:

bundle exec rake rubocop:pubid_core

All quality checks

Run all tests and quality checks:

bundle exec rake

Release management

The monorepo uses a synchronized versioning system where all gems share the same version number and are released together. This ensures consistency and eliminates version mismatch issues.

Version management

The system uses a master version file (lib/pubid/version.rb) as the single source of truth. All gem version files and dependencies are synchronized to this master version.

# Show current master version
bundle exec rake version:show

# Check if all gems and dependencies are synchronized
bundle exec rake version:check

# Sync master version to all gem version files and dependencies
bundle exec rake version:sync

# Bump version and sync to all gems and dependencies
bundle exec rake version:bump[patch]    # or minor, major

Release order management

The release order is managed through a JSON configuration file (release-order.json) that defines the dependency-aware order for releasing gems:

# Generate release order JSON file
bundle exec rake release:generate_order

# Validate release order
bundle exec rake release:validate_order

# Show current release order
bundle exec rake release:show_order

The release order ensures that dependencies are released before dependent gems (e.g., pubid-core before other gems, main pubid gem last).

Checking release status

bundle exec rake release:status

This shows a monorepo-focused release readiness summary:

Repository git status (clean/dirty working directory)
Master version and synchronization status across all gems
Whether the current master version is tagged
Release readiness assessment with actionable guidance
Quick commands for common release preparation tasks

Synchronized releases

All gems are released together with the same version number to maintain consistency:

Key features:

Master version: Single source of truth in lib/pubid/version.rb
Synchronized versions: All gems use identical version numbers
Dependency synchronization: Cross-gem dependencies use exact versions
Automated management: Rake tasks handle all synchronization

Example of synchronized dependencies:

# In pubid-bsi.gemspec
spec.add_dependency "pubid-core", "= 1.15.0"
spec.add_dependency "pubid-iso", "= 1.15.0"
# All use exact same version

GitHub Actions workflows

Monorepo release workflow

The main release workflow (release.yml) handles coordinated releases:

Trigger: Manual dispatch with options:

version_type: patch, minor, major, or skip
dry_run: Test without actually releasing

Process:

Validates release order and version synchronization
Bumps version using rake tasks (unless skip is selected)
Commits version changes and creates tag (unless skip is selected)
Builds all gems in dependency order
Releases gems to RubyGems with rate limiting
Creates GitHub release with comprehensive release notes (unless skip is selected)

Skip Mode:

When version_type is set to skip, the workflow will:

Use the current version without bumping
Build and push all gems to RubyGems
Skip version bumping, git commits, tagging, and GitHub release creation
Useful for re-releasing gems at the current version or fixing release issues

Benefits:

Atomic releases: All gems released together or none at all
Dependency order: Respects gem dependencies during release
Rate limiting: Prevents RubyGems API rate limit issues
Dry run support: Test releases without publishing

Individual gem testing

The rake workflow tests individual gems separately to ensure isolation and compatibility.

Manual release process

If needed, you can perform releases manually:

Prepare release:

# Check current status
bundle exec rake version:show
bundle exec rake version:check
bundle exec rake release:status

# Ensure synchronization
bundle exec rake version:sync

Bump version:

bundle exec rake version:bump[patch]  # or minor, major

Commit and tag:

git add -A
git commit -m "Bump version to $(bundle exec rake version:show | grep 'Master version:' | cut -d' ' -f3)"
git tag "v$(bundle exec rake version:show | grep 'Master version:' | cut -d' ' -f3)"

Build and release:

bundle exec rake build:all
# Then use individual release tasks or GitHub Actions

Troubleshooting

Version sync issues:

If rake version:check shows mismatched versions:

bundle exec rake version:sync

Release failures:

Check GitHub Actions logs for specific errors
Verify all gems build locally: bundle exec rake build:all
Use dry run to test: Set dry_run: true in workflow
Check RubyGems credentials are configured correctly

Manual recovery:

If a release partially fails:

Check which gems were released on RubyGems.org
Manually release missing gems from their directories
Ensure git tags are pushed: git push origin --tags

Dependency management

Gem dependencies

The gems are organized in a dependency hierarchy:

pubid           # meta-gem including common gems
pubid-core      # foundation gem
├── pubid-iso
│   └── pubid-ieee
├── pubid-iec
├── pubid-nist
├── pubid-cen   # depends on iso, iec, core
├── pubid-bsi   # depends on cen, nist, iso, iec, core
├── pubid-etsi
├── pubid-itu
├── pubid-jis
└── pubid-plateau

Note

Since v1.15.0, all pubid* gems share the same version number, which is synchronized across all gems and tagged to this repository.

For historic information, the last independent versions of pubid-* gems are:

Gem name	Version
pubid	v0.1.1
pubid-core	v0.1.2
pubid-iso	v1.13.0
pubid-ieee	v0.8.0
pubid-iec	v0.2.2
pubid-nist	v0.3.2
pubid-cen	v0.4.2
pubid-bsi	v0.2.4
pubid-etsi	v0.3.4
pubid-itu	v0.1.0
pubid-jis	v0.1.3
pubid-plateau	v0.3.2

Available rake tasks

Testing

rake test:all - Run all gem tests
rake test:integration - Run integration tests
rake test:<gem_name> - Run tests for specific gem

Building

rake build:all - Build all gems
rake build:<gem_name> - Build specific gem

Installation

rake install:all - Install all gems locally
rake install:<gem_name> - Install specific gem locally

Code quality

rake rubocop:all - Run RuboCop for all gems
rake rubocop:<gem_name> - Run RuboCop for specific gem

Version management

rake version:show - Show current master version
rake version:check - Check if all gems and dependencies are synchronized
rake version:sync - Sync master version to all gem version files and dependencies
rake version:bump[type] - Bump version (patch/minor/major) and sync to all gems

Release management

rake release:status - Check release status for all gems
rake release:generate_order - Generate release order JSON file
rake release:validate_order - Validate release order
rake release:show_order - Show current release order
rake release:<gem_name> - Release specific gem

The release status shows individual gem versions from their version files and indicates:

📦 Current version from gemspec
✓/✗ Git working directory status
✓/! Whether current version is tagged
📋 Latest git tag found

Cleanup

rake clean:all - Clean all built files
rake clean:<gem_name> - Clean specific gem’s built files

Quick reference

Common development workflows

Development:

bundle exec rake test:all          # Run all tests
bundle exec rake test:integration  # Run integration tests
bundle exec rake rubocop:all       # Check code quality

Working on a specific gem:

bundle exec rake test:pubid_core     # Test one gem
bundle exec rake rubocop:pubid_core  # Check one gem's style
bundle exec rake build:pubid_core    # Build one gem

Before releasing:

bundle exec rake release:status     # Check all gem versions and status
bundle exec rake test:all           # Ensure all tests pass
bundle exec rake rubocop:all        # Ensure code quality

Release a gem:

bundle exec rake release:pubid_core  # Release specific gem

Contributing

Make changes to the appropriate gem directory
Run tests: bundle exec rake test:all
Run integration tests: bundle exec rake test:integration
Run code quality checks: bundle exec rake rubocop:all
Submit a pull request

Copyright and license

This project is licensed under the BSD 2-Clause License - see the LICENSE.txt file for details.

pubid

Runtime

PubID: Interoperable identifiers for information resources

Badges

Overview

Repository

Structure

Development setup

Working with individual gems

General

Running tests for a specific gem

Building and installing gems

Integration testing

Code quality

RuboCop

All quality checks

Release management

Version management

Release order management

Checking release status

Synchronized releases

GitHub Actions workflows

Monorepo release workflow

Individual gem testing

Manual release process

Troubleshooting

Dependency management

Gem dependencies

Available rake tasks

Testing

Building

Installation

Code quality

Version management

Release management

Cleanup

Quick reference

Common development workflows

Contributing

Copyright and license