gem-scaffold

A template repository for creating Ruby gems with automated Ruby version management.

Prerequisites

The initialization script requires the following commands:

• zsh - Z shell (usually pre-installed on macOS/Linux)
• gh - GitHub CLI for repository configuration
• git - Version control (usually pre-installed)
• Ruby 3.2 or higher - Use your preferred version manager (mise, rbenv, asdf, chruby, etc.)

Usage

1. Create a new repository from this template:

   Option A: Using GitHub CLI (recommended)

   gh repo create my-gem --template sakuro/gem-scaffold --clone --public
   cd my-gem

   Option B: Using GitHub web interface

   • Click the "Use this template" button on GitHub
   • See Creating a repository from a template
   • Clone your new repository

2. Run the initialization script:

   ./bin/initialize

   This script will:

   • Update all files with your gem name
   • Generate proper Ruby module namespacing
   • Set up repository-specific cron schedule
   • Configure GitHub settings automatically
   • Optionally configure WORKFLOW_TOKEN secret (for workflows that update .github/workflows/)
   • Remove setup script and amend changes into initial commit

   Note: During setup, you'll be prompted for a Personal Access Token with workflow scope. This is required for workflows like update-ruby-versions.yml that modify workflow files. Create one at: https://github.com/settings/tokens/new?scopes=workflow

3. Push the initialized changes:

   git push -f origin main

Features

This template provides a modern Ruby gem setup with automated Ruby version management:

• Always up-to-date Ruby support: Automatically tracks maintained Ruby versions from Ruby's official branches.yml
• Zero-maintenance CI matrix: Tests run against current Ruby versions without manual updates
• Repository-specific scheduling: Each cloned repository gets a unique cron schedule to distribute API load
• One-command initialization: Single script transforms the template into a ready-to-use gem

What's Included in the Generated Gem

The initialization script creates a fully-configured gem with:

Code Structure

• Zeitwerk autoloading: Automatic code loading with proper namespace handling
• Proper module nesting: Multi-level module structure based on gem name (e.g., my-awesome-gem → My::Awesome::Gem)

Development Tools

• Ruby LSP: Language server for IDE features and code intelligence
• RSpec with SimpleCov: Testing framework with code coverage analysis (configurable via .simplecov)
• RuboCop with docquet: Code style enforcement with docquet configuration
• Mise integration: Development environment uses minimum supported Ruby version

CI/CD

• Dynamic test matrix: CI automatically tests against all maintained Ruby versions
• Twice-yearly Ruby version updates: GitHub Actions workflow keeps Ruby versions current (runs Dec 25-31 and Apr 1-7)

Automatic Configuration

• Author information: Extracted from git config (user.name, user.email)
• Dependency versions: Latest compatible versions detected from remote (zeitwerk, etc.)

License

This template is available as open source under the terms of the MIT License.

License for Generated Code

Code generated from this template can be licensed under any license chosen by the author. The initialization script:

• Preserves this template's MIT license as LICENSE-TEMPLATE.txt (for template-derived code)
• Creates a new LICENSE.txt (MIT) with the author's name and year (for the generated gem)

Authors are free to replace LICENSE.txt with any license of their choosing.