ABOUTME: Ruby gem development guide - structure, testing, linting, CI/CD, publishing

ABOUTME: Modern Ruby (3.3-3.4): Prism parser, frozen strings, Ractor, attestation

Ruby Gem Development

What's New (2025-2026)

Ruby 3.4	RubyGems 4.0
Prism default parser	Go extension support
Frozen string warnings	5 parallel connections
Gem attestation (sigstore)	Reproducible builds
Bundler checksums
Ractor require

Quick Reference

bundle gem my_gem --test=rspec --ci=github --linter=rubocop
bundle install && bundle exec rspec && bundle exec rubocop -A
gem build my_gem.gemspec
gem push my_gem-1.0.0.gem --attestation

Target: Ruby 3.3+ | For Rails apps, use rails skill | See also: _AST_GREP.md, _PATTERNS.md

---

Gem Structure

my_gem/
├── lib/my_gem.rb           # Entry point
├── lib/my_gem/version.rb   # VERSION constant
├── spec/                   # RSpec tests
├── sig/                    # RBS types (optional)
├── .github/workflows/ci.yml
├── .rubocop.yml
├── my_gem.gemspec
└── Gemfile

Entry Point (lib/my_gem.rb)

# frozen_string_literal: true

# ABOUTME: Main entry point for MyGem
# ABOUTME: Requires all components and provides configuration

require_relative "my_gem/version"
require_relative "my_gem/client"

module MyGem
  class << self
    attr_writer :configuration
    def configuration = @configuration ||= Configuration.new
    def configure = yield(configuration) if block_given?
  end
end

---

Gemspec

# frozen_string_literal: true

Gem::Specification.new do |spec|
  spec.name = "my_gem"
  spec.version = MyGem::VERSION
  spec.required_ruby_version = ">= 3.3.0"  # Always specify!

  spec.metadata = {
    "rubygems_mfa_required" => "true",  # Required!
    "source_code_uri" => "https://github.com/you/my_gem",
    "changelog_uri" => "https://github.com/you/my_gem/blob/main/CHANGELOG.md"
  }

  spec.files = Dir.glob(%w[lib/**/* LICENSE.txt README.md CHANGELOG.md])
  # Runtime deps in gemspec, dev deps in Gemfile
end

---

Testing & Quality

RSpec: describe/it with expect syntax, subject(:name), WebMock for HTTP, SimpleCov >= 90%.

RuboCop: rubocop-rspec + rubocop-performance, TargetRubyVersion: 3.3, NewCops: enable, max line 120, max method 10.

Thread safety: Mutex.new + @mutex.synchronize { ... } for shared state.

For detailed testing examples, CI config, HTTP client pattern, and publishing steps, see references/ruby-patterns.md.

---

Code Review Checklist

Category	Checks
Structure	frozen_string_literal, ABOUTME headers, standard layout
Gemspec	required_ruby_version, rubygems_mfa_required, metadata URIs
Testing	RSpec expect syntax, SimpleCov >= 90%, WebMock, no real HTTP
Quality	RuboCop passes, thread-safe if async, custom error classes
CI	Ruby 3.3+3.4, ruby/setup-ruby, bundler-cache

---

Resources

• Bundler: Creating Gems
• RubyGems Patterns
• Ruby 3.4 Changes