gem-development

What this skill does

# Ruby Gem Development

Guide to creating, testing, and publishing Ruby gems.

## Creating a New Gem

### Using Bundler

```bash
# Create gem scaffold
bundle gem my_gem

# With options
bundle gem my_gem --test=minitest --ci=github --linter=rubocop
```

Generated structure:

```
my_gem/
├── lib/
│   ├── my_gem/
│   │   └── version.rb
│   └── my_gem.rb
├── test/ or spec/
├── bin/
│   ├── console
│   └── setup
├── Gemfile
├── Rakefile
├── my_gem.gemspec
├── README.md
├── LICENSE.txt
└── CHANGELOG.md
```

### Manual Structure

```
my_gem/
├── lib/
│   ├── my_gem/
│   │   ├── version.rb
│   │   ├── configuration.rb
│   │   └── core_class.rb
│   └── my_gem.rb          # Main entry point
├── test/
│   ├── test_helper.rb
│   └── my_gem_test.rb
├── Gemfile
├── Rakefile
├── my_gem.gemspec
├── README.md
├── LICENSE.txt
└── CHANGELOG.md
```

## The Gemspec

### Complete Example

```ruby
# my_gem.gemspec
require_relative "lib/my_gem/version"

Gem::Specification.new do |spec|
  spec.name          = "my_gem"
  spec.version       = MyGem::VERSION
  spec.authors       = ["Your Name"]
  spec.email         = ["[email protected]"]

  spec.summary       = "Short summary of your gem"
  spec.description   = "Longer description explaining what your gem does"
  spec.homepage      = "https://github.com/username/my_gem"
  spec.license       = "MIT"

  spec.required_ruby_version = ">= 3.0.0"

  spec.metadata = {
    "homepage_uri"      => spec.homepage,
    "source_code_uri"   => "https://github.com/username/my_gem",
    "changelog_uri"     => "https://github.com/username/my_gem/blob/main/CHANGELOG.md",
    "bug_tracker_uri"   => "https://github.com/username/my_gem/issues",
    "documentation_uri" => "https://rubydoc.info/gems/my_gem",
    "rubygems_mfa_required" => "true"
  }

  # Files to include
  spec.files = Dir.chdir(__dir__) do
    `git ls-files -z`.split("\x0").reject do |f|
      f.match?(%r{\A(?:test|spec|features)/})
    end
  end

  spec.bindir        = "exe"
  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
  spec.require_paths = ["lib"]

  # Runtime dependencies
  spec.add_dependency "some_gem", "~> 1.0"

  # Development dependencies (prefer Gemfile for these)
  # spec.add_development_dependency "rake", "~> 13.0"
end
```

### Version File

```ruby
# lib/my_gem/version.rb
module MyGem
  VERSION = "0.1.0"
end
```

## Main Entry Point

```ruby
# lib/my_gem.rb
require_relative "my_gem/version"
require_relative "my_gem/configuration"
require_relative "my_gem/client"

module MyGem
  class Error < StandardError; end
  class ConfigurationError < Error; end
  class APIError < Error; end

  class << self
    attr_accessor :configuration
  end

  def self.configure
    self.configuration ||= Configuration.new
    yield(configuration)
  end

  def self.reset_configuration!
    self.configuration = Configuration.new
  end
end
```

### Configuration Pattern

```ruby
# lib/my_gem/configuration.rb
module MyGem
  class Configuration
    attr_accessor :api_key, :timeout, :logger, :debug

    def initialize
      @api_key = nil
      @timeout = 30
      @logger = Logger.new($stdout)
      @debug = false
    end

    def validate!
      raise ConfigurationError, "API key required" if api_key.nil?
    end
  end
end
```

Usage:

```ruby
MyGem.configure do |config|
  config.api_key = "your-key"
  config.timeout = 60
  config.debug = true
end
```

## Testing Your Gem

### Test Helper

```ruby
# test/test_helper.rb
$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
require "my_gem"
require "minitest/autorun"

# Optional: VCR for API testing
require "vcr"
VCR.configure do |config|
  config.cassette_library_dir = "test/fixtures/vcr_cassettes"
  config.hook_into :webmock
end
```

### Example Tests

```ruby
# test/my_gem_test.rb
require "test_helper"

class MyGemTest < Minitest::Test
  def setup
    MyGem.reset_configuration!
  end

  def test_version
    refute_nil MyGem::VERSION
  end

  def test_configuration
    MyGem.configure do |config|
      config.api_key = "test-key"
    end

    assert_equal "test-key", MyGem.configuration.api_key
  end

  def test_requires_api_key
    assert_raises(MyGem::ConfigurationError) do
      MyGem.configuration.validate!
    end
  end
end
```

### Rakefile

```ruby
# Rakefile
require "bundler/gem_tasks"
require "rake/testtask"

Rake::TestTask.new(:test) do |t|
  t.libs << "test"
  t.libs << "lib"
  t.test_files = FileList["test/**/*_test.rb"]
end

require "rubocop/rake_task"
RuboCop::RakeTask.new

task default: %i[test rubocop]
```

## Versioning

### Semantic Versioning

```
MAJOR.MINOR.PATCH

1.0.0 - Initial stable release
1.0.1 - Bug fix (backwards compatible)
1.1.0 - New feature (backwards compatible)
2.0.0 - Breaking change
```

### Pre-release Versions

```ruby
VERSION = "1.0.0.alpha"
VERSION = "1.0.0.beta1"
VERSION = "1.0.0.rc1"
```

### Updating Version

```ruby
# Use a rake task
# lib/tasks/version.rake
namespace :version do
  desc "Bump patch version"
  task :patch do
    bump_version(:patch)
  end

  desc "Bump minor version"
  task :minor do
    bump_version(:minor)
  end

  desc "Bump major version"
  task :major do
    bump_version(:major)
  end

  def bump_version(type)
    version_file = "lib/my_gem/version.rb"
    content = File.read(version_file)
    current = content.match(/VERSION = "(.+)"/)[1]
    parts = current.split(".").map(&:to_i)

    case type
    when :patch then parts[2] += 1
    when :minor then parts[1] += 1; parts[2] = 0
    when :major then parts[0] += 1; parts[1] = 0; parts[2] = 0
    end

    new_version = parts.join(".")
    new_content = content.gsub(/VERSION = ".+"/, %(VERSION = "#{new_version}"))
    File.write(version_file, new_content)
    puts "Bumped to #{new_version}"
  end
end
```

## Documentation

### YARD Documentation

```ruby
# Add to Gemfile
# gem 'yard', group: :development

# Example documentation
module MyGem
  # Client for interacting with the API
  #
  # @example Basic usage
  #   client = MyGem::Client.new(api_key: "key")
  #   result = client.fetch("resource")
  #
  # @see https://api.example.com/docs API Documentation
  class Client
    # Create a new client instance
    #
    # @param api_key [String] API authentication key
    # @param timeout [Integer] Request timeout in seconds
    # @return [Client] a new client instance
    # @raise [ConfigurationError] if api_key is nil
    def initialize(api_key:, timeout: 30)
      @api_key = api_key
      @timeout = timeout
    end

    # Fetch a resource from the API
    #
    # @param resource [String] Resource path to fetch
    # @param params [Hash] Optional query parameters
    # @option params [Integer] :limit Maximum results
    # @option params [Integer] :offset Pagination offset
    # @return [Hash] Parsed JSON response
    # @raise [APIError] on API errors
    def fetch(resource, params = {})
      # implementation
    end
  end
end
```

Generate docs:

```bash
yard doc
yard server  # View at http://localhost:8808
```

### README Template

```markdown
# MyGem

Short description of what your gem does.

## Installation

Add to your Gemfile:

    gem 'my_gem'

Or install directly:

    gem install my_gem

## Usage

    require 'my_gem'

    MyGem.configure do |config|
      config.api_key = ENV['API_KEY']
    end

    client = MyGem::Client.new
    result = client.fetch('users')

## Development

    git clone https://github.com/username/my_gem
    cd my_gem
    bin/setup
    rake test

## Contributing

Bug reports and pull requests welcome on GitHub.

## License

MIT License
```

## Publishing

### First-time Setup

```bash
# Create account at rubygems.org
gem signin
```

### Release Process

```bash
# 1. Update version in lib/my_gem/version.rb
# 2. Update CHANGELOG.md
# 3. Commit changes
git add -A
git commit -m "Release v1.0.0"

# 4. Build and push
bundle exec rake release
# This will:
# - Build the gem
# - Tag the version
# - Push to RubyGems
# - Push to GitHub
```

### Manual Release

```bash
# Build
gem build m