opaque_id 1.4.0 → 1.7.0

data/docs/usage.md

@@ -20,13 +20,13 @@ OpaqueId can be used independently of ActiveRecord for generating secure, random
 ### Basic Usage
 
 ```ruby
-# Generate a default opaque ID (21 characters, alphanumeric)
+# Generate a default opaque ID (18 characters, slug-like)
 id = OpaqueId.generate
-# => "V1StGXR8_Z5jdHi6B-myT"
+# => "izkpm55j334u8x9y2a"
 
 # Generate multiple IDs
 ids = 5.times.map { OpaqueId.generate }
-# => ["V1StGXR8_Z5jdHi6B-myT", "K8jH2mN9_pL3qR7sT1v", ...]
+# => ["izkpm55j334u8x9y2a", "k8jh2mn9pl3qr7st1v", ...]
 ```
 
 ### Custom Parameters
@@ -34,7 +34,7 @@ ids = 5.times.map { OpaqueId.generate }
 ```ruby
 # Custom length
 id = OpaqueId.generate(size: 10)
-# => "V1StGXR8_Z5"
+# => "izkpm55j334u"
 
 # Custom alphabet
 id = OpaqueId.generate(alphabet: OpaqueId::STANDARD_ALPHABET)
@@ -42,15 +42,19 @@ id = OpaqueId.generate(alphabet: OpaqueId::STANDARD_ALPHABET)
 
 # Both custom length and alphabet
 id = OpaqueId.generate(size: 15, alphabet: OpaqueId::STANDARD_ALPHABET)
-# => "V1StGXR8_Z5jdHi"
+# => "V1StGXR8_Z5jdHi6B"
 ```
 
 ### Built-in Alphabets
 
 ```ruby
-# Alphanumeric alphabet (default) - A-Z, a-z, 0-9
+# Slug-like alphabet (default) - 0-9, a-z
+id = OpaqueId.generate(alphabet: OpaqueId::SLUG_LIKE_ALPHABET)
+# => "izkpm55j334u8x9y2a"
+
+# Alphanumeric alphabet - A-Z, a-z, 0-9
 id = OpaqueId.generate(alphabet: OpaqueId::ALPHANUMERIC_ALPHABET)
-# => "V1StGXR8_Z5jdHi6B-myT"
+# => "V1StGXR8Z5jdHi6BmyT"
 
 # Standard alphabet - A-Z, a-z, 0-9, -, _
 id = OpaqueId.generate(alphabet: OpaqueId::STANDARD_ALPHABET)
@@ -73,7 +77,7 @@ id = OpaqueId.generate(size: 16, alphabet: hex_alphabet)
 # URL-safe characters
 url_safe = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_"
 id = OpaqueId.generate(size: 12, alphabet: url_safe)
-# => "V1StGXR8_Z5j"
+# => "izkpm55j334u8x"
 ```
 
 ## ActiveRecord Integration
@@ -94,7 +98,7 @@ end
 # Create a new user - opaque_id is automatically generated
 user = User.create!(name: "John Doe", email: "john@example.com")
 puts user.opaque_id
-# => "V1StGXR8_Z5jdHi6B-myT"
+# => "izkpm55j334u8x9y2a"
 
 # The ID is generated before the record is saved
 user = User.new(name: "Jane Smith")
@@ -103,17 +107,17 @@ puts user.opaque_id
 
 user.save!
 puts user.opaque_id
-# => "K8jH2mN9_pL3qR7sT1v" (generated on save)
+# => "k8jh2mn9pl3qr7st1va" (generated on save)
 ```
 
 ### Finder Methods
 
 ```ruby
 # Find by opaque_id (returns nil if not found)
-user = User.find_by_opaque_id("V1StGXR8_Z5jdHi6B-myT")
+user = User.find_by_opaque_id("izkpm55j334u8x9y2a")
 
 # Find by opaque_id (raises exception if not found)
-user = User.find_by_opaque_id!("V1StGXR8_Z5jdHi6B-myT")
+user = User.find_by_opaque_id!("izkpm55j334u8x9y2a")
 # => ActiveRecord::RecordNotFound if not found
 
 # Use in scopes
@@ -123,7 +127,7 @@ class User < ApplicationRecord
   scope :by_opaque_id, ->(id) { where(opaque_id: id) }
 end
 
-users = User.by_opaque_id("V1StGXR8_Z5jdHi6B-myT")
+users = User.by_opaque_id("izkpm55j334u8x9y2a")
 ```
 
 ### Custom Column Names
@@ -139,9 +143,9 @@ end
 # Now the methods use the custom column name
 user = User.create!(name: "John Doe")
 puts user.public_id
-# => "V1StGXR8_Z5jdHi6B-myT"
+# => "izkpm55j334u8x9y2a"
 
-user = User.find_by_public_id("V1StGXR8_Z5jdHi6B-myT")
+user = User.find_by_public_id("izkpm55j334u8x9y2a")
 ```
 
 ## Rails Generator
@@ -198,7 +202,7 @@ end
 # Create an order
 order = Order.create!(user_id: 1, total: 99.99)
 puts order.opaque_id
-# => "V1StGXR8_Z5j"
+# => "izkpm55j334u8x"
 
 # Use in URLs
 order_url(order.opaque_id)
@@ -259,7 +263,7 @@ end
 # Create a user
 user = User.create!(name: "John Doe", email: "john@example.com")
 puts user.opaque_id
-# => "V1StGXR8_Z5jdHi6B-myT" (starts with letter)
+# => "izkpm55j334u8x9y2a" (starts with letter)
 
 # Use in user profiles
 user_url(user.opaque_id)
@@ -273,7 +277,7 @@ user_url(user.opaque_id)
 ```ruby
 # Generate multiple IDs at once
 ids = 100.times.map { OpaqueId.generate }
-# => ["V1StGXR8_Z5jdHi6B-myT", "K8jH2mN9_pL3qR7sT1v", ...]
+# => ["izkpm55j334u8x9y2a", "k8jh2mn9pl3qr7st1va", ...]
 
 # Use in bulk operations
 users_data = ids.map.with_index do |id, index|

data/lib/generators/opaque_id/install_generator.rb

@@ -15,8 +15,12 @@ module OpaqueId
       class_option :column_name, type: :string, default: 'opaque_id',
                                  desc: 'Name of the column to add'
 
+      class_option :limit, type: :numeric, default: 21,
+                           desc: 'Column limit for the opaque_id string (default: 21)'
+
       def create_migration_file
         if model_name.present?
+          validate_limit_option
           table_name = model_name.tableize
           migration_template 'migration.rb.tt',
                              "db/migrate/add_opaque_id_to_#{table_name}.rb"
@@ -26,11 +30,20 @@ module OpaqueId
           say 'Usage: rails generate opaque_id:install ModelName', :red
           say 'Example: rails generate opaque_id:install User', :green
           say 'Example: rails generate opaque_id:install Post --column-name=public_id', :green
+          say 'Example: rails generate opaque_id:install Post --limit=25', :green
         end
       end
 
       private
 
+      def validate_limit_option
+        # Default OpaqueId length is 18, so limit should be at least that
+        return unless options[:limit] < 18
+
+        say "Warning: Column limit (#{options[:limit]}) is less than the default OpaqueId length (18).", :yellow
+        say 'Consider using --limit=21 or higher to avoid truncation issues.', :yellow
+      end
+
       def add_include_to_model
         model_path = "app/models/#{model_name.underscore}.rb"
 

data/lib/generators/opaque_id/templates/migration.rb.tt

@@ -1,6 +1,6 @@
-class AddOpaqueIdTo<%= table_name.camelize %> < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+class AddOpaqueIdTo<%= model_name.tableize.camelize %> < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
   def change
-    add_column :<%= table_name %>, :<%= options[:column_name] %>, :string
-    add_index :<%= table_name %>, :<%= options[:column_name] %>, unique: true
+    add_column :<%= model_name.tableize %>, :<%= options[:column_name] %>, :string, limit: <%= options[:limit] %>
+    add_index :<%= model_name.tableize %>, :<%= options[:column_name] %>, unique: true
   end
 end

data/lib/opaque_id/model.rb

@@ -30,7 +30,7 @@ module OpaqueId
       end
 
       def opaque_id_length
-        @opaque_id_length ||= 21
+        @opaque_id_length ||= 18
       end
 
       def opaque_id_length=(value)
@@ -38,7 +38,7 @@ module OpaqueId
       end
 
       def opaque_id_alphabet
-        @opaque_id_alphabet ||= OpaqueId::ALPHANUMERIC_ALPHABET
+        @opaque_id_alphabet ||= OpaqueId::SLUG_LIKE_ALPHABET
       end
 
       def opaque_id_alphabet=(value)

data/lib/opaque_id/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OpaqueId
-  VERSION = '1.4.0'
+  VERSION = '1.7.0'
 end

data/lib/opaque_id.rb

@@ -9,6 +9,9 @@ module OpaqueId
   class GenerationError < Error; end
   class ConfigurationError < Error; end
 
+  # Slug-like alphabet for URL-safe, double-click selectable IDs (36 characters)
+  SLUG_LIKE_ALPHABET = '0123456789abcdefghijklmnopqrstuvwxyz'
+
   # Standard URL-safe alphabet (64 characters)
   STANDARD_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_'
 
@@ -17,7 +20,7 @@ module OpaqueId
 
   class << self
     # Generate a cryptographically secure random ID
-    def generate(size: 21, alphabet: ALPHANUMERIC_ALPHABET)
+    def generate(size: 18, alphabet: SLUG_LIKE_ALPHABET)
       raise ConfigurationError, 'Size must be positive' unless size.positive?
       raise ConfigurationError, 'Alphabet cannot be empty' if alphabet.nil? || alphabet.empty?
 

data/release-please-config.json

@@ -3,7 +3,8 @@
   "packages": {
     ".": {
       "package-name": "opaque_id",
-      "version-file": "lib/opaque_id/version.rb"
+      "version-file": "lib/opaque_id/version.rb",
+      "tag-template": "v${version}"
     }
   },
   "changelog-sections": [

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: opaque_id
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.7.0
 platform: ruby
 authors:
 - Joe Nyaggah
@@ -140,6 +140,7 @@ files:
 - docs/assets/css/custom.scss
 - docs/assets/images/favicon.svg
 - docs/assets/images/og-image.svg
+- docs/benchmarks.md
 - docs/configuration.md
 - docs/development.md
 - docs/getting-started.md
@@ -156,14 +157,6 @@ files:
 - lib/opaque_id/model.rb
 - lib/opaque_id/version.rb
 - release-please-config.json
-- tasks/0001-prd-opaque-id-gem.md
-- tasks/0002-prd-publishing-release-automation.md
-- tasks/0003-prd-documentation-site.md
-- tasks/references/opaque_gem_requirements.md
-- tasks/references/original_identifiable_concern_and_nanoid.md
-- tasks/tasks-0001-prd-opaque-id-gem.md
-- tasks/tasks-0002-prd-publishing-release-automation.md
-- tasks/tasks-0003-prd-documentation-site.md
 homepage: https://github.com/nyaggah/opaque_id
 licenses:
 - MIT

data/tasks/0001-prd-opaque-id-gem.md

@@ -1,202 +0,0 @@
-# Product Requirements Document: OpaqueId Ruby Gem
-
-## Introduction/Overview
-
-The OpaqueId gem is a Ruby library that generates cryptographically secure, collision-free opaque identifiers for ActiveRecord models. This gem replaces the existing `nanoid.rb` dependency by implementing the same functionality using Ruby's built-in `SecureRandom` methods, eliminating external dependencies while maintaining the same security and performance characteristics.
-
-The primary problem this gem solves is preventing the exposure of incremental database IDs in public URLs and APIs, which can reveal business metrics, enable enumeration attacks, and expose internal system architecture. Instead, it provides opaque, non-sequential identifiers that are URL-friendly and cryptographically secure.
-
-## Goals
-
-1. **Replace nanoid.rb dependency** - Implement equivalent functionality using Ruby's built-in SecureRandom
-2. **Maintain security standards** - Provide cryptographically secure ID generation with unbiased distribution
-3. **Ensure performance** - Achieve 1M+ IDs/sec for 64-character alphabets, 180K+ IDs/sec for 36-character alphabets
-4. **Simplify integration** - Provide seamless ActiveRecord integration with minimal configuration
-5. **Enable wide adoption** - Create comprehensive documentation accessible to all Rails developers
-6. **Ensure reliability** - Implement robust collision detection and retry logic
-7. **Maintain compatibility** - Support Rails 8.0+ and Ruby 3.2+ environments
-
-## User Stories
-
-### Primary Users: Rails Developers
-
-**As a Rails developer**, I want to generate opaque IDs for my models so that I can expose public identifiers without revealing database structure.
-
-**As a Rails developer**, I want to easily integrate opaque ID generation into my existing models so that I don't have to manually implement ID generation logic.
-
-**As a Rails developer**, I want to configure ID generation parameters (length, alphabet, column name) so that I can customize the behavior for different use cases.
-
-**As a Rails developer**, I want to find records by their opaque ID so that I can build public-facing APIs and URLs.
-
-**As a Rails developer**, I want the gem to handle collision detection automatically so that I don't have to worry about duplicate IDs.
-
-**As a Rails developer**, I want comprehensive documentation and examples so that I can quickly understand and implement the gem in my project.
-
-### Secondary Users: Security-Conscious Teams
-
-**As a security-conscious developer**, I want cryptographically secure ID generation so that my public identifiers cannot be predicted or enumerated.
-
-**As a security-conscious developer**, I want unbiased character distribution so that my IDs have maximum entropy and cannot be analyzed for patterns.
-
-## Functional Requirements
-
-### Core ID Generation
-
-1. The system must generate cryptographically secure random IDs using Ruby's `SecureRandom`
-2. The system must implement rejection sampling algorithm to ensure unbiased character distribution
-3. The system must provide optimized fast path for 64-character alphabets using bitwise operations
-4. The system must support custom alphabet configurations
-5. The system must support custom ID length configurations
-6. The system must provide two predefined alphabets: ALPHANUMERIC_ALPHABET (36 chars) and STANDARD_ALPHABET (64 chars)
-
-### ActiveRecord Integration
-
-7. The system must provide `OpaqueId::Model` concern for easy ActiveRecord integration
-8. The system must automatically generate opaque IDs on model creation via `before_create` callback
-9. The system must provide `find_by_opaque_id` and `find_by_opaque_id!` class methods
-10. The system must support custom column names via `opaque_id_column` configuration
-11. The system must implement collision detection with configurable retry attempts
-12. The system must raise appropriate errors when collision resolution fails
-
-### Rails Generator (Optional Convenience Tool)
-
-13. The system must provide optional Rails generator `opaque_id:install` for creating migrations and updating models
-14. The system must generate migration files that add opaque_id column with unique index
-15. The system must automatically add `include OpaqueId::Model` to the corresponding model file
-16. The system must support custom column names via generator options
-17. The system must require explicit table name argument and show clear usage instructions when run without arguments
-18. The system must work with any existing table (new or existing models)
-19. The system must handle edge cases gracefully (missing model file, already included, different class names)
-
-### Configuration Options
-
-20. The system must support `opaque_id_column` configuration (default: `:opaque_id`)
-21. The system must support `opaque_id_length` configuration (default: `18`)
-22. The system must support `opaque_id_alphabet` configuration (default: `ALPHANUMERIC_ALPHABET`)
-23. The system must support `opaque_id_require_letter_start` configuration (default: `true`)
-24. The system must support `opaque_id_purge_chars` configuration (default: `nil`)
-25. The system must support `opaque_id_max_retry` configuration (default: `1000`)
-
-### Error Handling
-
-26. The system must raise `OpaqueId::ConfigurationError` for invalid size or empty alphabet
-27. The system must raise `OpaqueId::GenerationError` when collision resolution fails
-28. The system must provide clear error messages for debugging
-
-### Standalone Usage
-
-29. The system must provide `OpaqueId.generate` method for standalone ID generation
-30. The system must support all configuration options in standalone generation
-31. The system must maintain the same security and performance characteristics in standalone mode
-
-## Non-Goals (Out of Scope)
-
-1. **Other ORM Support** - Will not support Mongoid, Sequel, or other ORMs in initial release
-2. **Non-Rails Usage** - Will not provide standalone Ruby usage without ActiveRecord dependency
-3. **Custom Algorithms** - Will not implement alternative ID generation algorithms beyond rejection sampling
-4. **Database Migrations** - Will not provide automatic database migration for existing records
-5. **ID Validation** - Will not provide built-in ID format validation (users can implement their own)
-6. **Bulk Generation** - Will not provide optimized bulk ID generation methods
-7. **ID Prefixes/Suffixes** - Will not support adding prefixes or suffixes to generated IDs
-8. **Custom Random Sources** - Will not support custom random number generators beyond SecureRandom
-9. **Interactive Generator Mode** - Will not provide interactive prompts for generator arguments
-10. **Backward Compatibility** - Will not maintain compatibility with existing `public_id` implementations
-
-## Design Considerations
-
-### API Design
-
-- Follow Rails conventions for ActiveRecord concerns and generators
-- Use descriptive method names that clearly indicate functionality
-- Provide both safe (`find_by_opaque_id`) and unsafe (`find_by_opaque_id!`) lookup methods
-- Use class-level configuration options for easy customization
-- Follow Devise-style generator pattern for seamless integration
-
-### Performance Optimization
-
-- Implement fast path for 64-character alphabets using bitwise operations (`byte & 63`)
-- Use rejection sampling with optimal mask calculation for unbiased distribution
-- Pre-allocate string capacity to avoid memory reallocation during generation
-- Batch random byte generation to minimize SecureRandom calls
-
-### Security Considerations
-
-- Use only cryptographically secure random number generation
-- Implement proper rejection sampling to avoid modulo bias
-- Provide sufficient entropy through configurable alphabet sizes
-- Ensure IDs cannot be predicted or enumerated
-
-## Technical Considerations
-
-### Dependencies
-
-- **ActiveRecord**: >= 6.0 (targeting Rails 8.0+ compatibility)
-- **ActiveSupport**: >= 6.0 (for concern functionality)
-- **Ruby**: >= 3.2 (for modern Ruby features and performance)
-
-### Testing Framework
-
-- Use **Minitest** instead of RSpec for consistency with Rails conventions
-- Implement comprehensive unit tests for all public methods
-- Include statistical tests for character distribution uniformity
-- Add performance benchmarks to ensure performance requirements are met
-- Test edge cases including collision scenarios and error conditions
-
-### File Structure
-
-```
-lib/
-├── opaque_id.rb                 # Main module with generator
-├── opaque_id/
-│   ├── version.rb               # Version constant
-│   └── model.rb                 # ActiveRecord concern
-└── generators/
-    └── opaque_id/
-        ├── install_generator.rb  # Migration generator
-        └── templates/
-            └── migration.rb.tt   # Migration template
-```
-
-### Error Classes
-
-- `OpaqueId::Error` - Base error class
-- `OpaqueId::GenerationError` - ID generation failures
-- `OpaqueId::ConfigurationError` - Invalid configuration
-
-## Success Metrics
-
-### Performance Metrics
-
-- **Standard alphabet (64 chars)**: Achieve ~1.2M IDs/sec generation rate
-- **Alphanumeric alphabet (36 chars)**: Achieve ~180K IDs/sec generation rate
-- **Custom alphabet (20 chars)**: Achieve ~150K IDs/sec generation rate
-
-### Quality Metrics
-
-- **Test Coverage**: Achieve 95%+ code coverage
-- **Documentation**: Provide comprehensive README with examples
-- **Error Handling**: All error conditions properly tested and documented
-
-### Adoption Metrics
-
-- **Gem Downloads**: Target 1000+ downloads in first month
-- **GitHub Stars**: Target 50+ stars within 6 months
-- **Community Feedback**: Positive reception from Rails community
-
-## Open Questions
-
-1. **Version Strategy**: Should we follow semantic versioning strictly, or use a different versioning strategy for a utility gem?
-
-2. **Backward Compatibility**: How should we handle potential breaking changes in future versions, especially regarding default configurations?
-
-3. **Performance Testing**: Should we include automated performance regression testing in CI/CD, or rely on manual benchmarking?
-
-4. **Documentation Hosting**: Should we create a dedicated documentation site, or rely on GitHub README and inline documentation?
-
-5. **Community Contributions**: What level of community contribution should we expect, and how should we structure the project to encourage contributions?
-
-6. **Integration Testing**: Should we test against multiple Rails versions in CI, or focus on the target Rails 8.0+ range?
-
-7. **Security Auditing**: Should we implement any security auditing tools or processes for the random number generation?
-
-8. **Migration Path**: How should we help users migrate from nanoid.rb to opaque_id, if at all?

data/tasks/0002-prd-publishing-release-automation.md

@@ -1,206 +0,0 @@
-# Product Requirements Document: Publishing & Release Automation
-
-## Introduction/Overview
-
-This PRD outlines the implementation of a fully automated publishing and release system for the OpaqueId Ruby gem. The system will automatically version, test, and publish releases to RubyGems.org based on conventional commits, eliminating manual release processes and ensuring consistent, professional releases.
-
-**Problem**: Manual release processes are error-prone, time-consuming, and inconsistent. Without automated versioning and publishing, releases can be delayed, version numbers can be inconsistent, and changelogs can be incomplete.
-
-**Goal**: Implement a fully automated CI/CD pipeline that handles versioning, testing, changelog generation, and publishing based on conventional commits and the state of the main branch.
-
-## Goals
-
-1. **Automated Versioning**: Automatically determine version bumps (patch/minor/major) based on conventional commit types
-2. **Automated Publishing**: Automatically publish to RubyGems.org when changes are ready
-3. **Quality Gates**: Ensure all tests pass, code quality standards are met, and security checks pass before release
-4. **Automated Changelog**: Generate changelog entries from conventional commits
-5. **Dependency Management**: Automatically check for and update dependencies weekly
-6. **Commit Standardization**: Enforce conventional commit format for consistent messaging
-7. **Security**: Use RubyGems trusted publishing for secure, keyless releases
-
-## User Stories
-
-### As a Developer
-
-- **US1**: I want my commits to automatically trigger appropriate version bumps so that I don't have to manually manage version numbers
-- **US2**: I want releases to be published automatically when I push to main so that I don't have to remember to manually publish
-- **US3**: I want commit message validation so that I follow consistent formatting standards
-- **US4**: I want automated dependency updates so that my gem stays secure and up-to-date
-
-### As a Maintainer
-
-- **US5**: I want automated testing and quality checks before release so that I can trust the published code
-- **US6**: I want automated changelog generation so that users know what changed in each release
-- **US7**: I want security scanning before release so that vulnerabilities are caught early
-
-### As a User
-
-- **US8**: I want consistent, predictable releases so that I can trust the gem's stability
-- **US9**: I want clear changelogs so that I understand what changed between versions
-
-## Functional Requirements
-
-### 1. Conventional Commits Integration
-
-1.1. **Commit Message Validation**: Enforce conventional commit format (feat:, fix:, docs:, etc.) on all commits
-1.2. **Commit Linting**: Use commitlint or similar tool to validate commit message format
-1.3. **Pre-commit Hooks**: Automatically validate commit messages before they are accepted
-1.4. **Commit Types**: Support standard types: feat, fix, docs, style, refactor, perf, test, chore, ci, build
-
-### 2. Automated Versioning
-
-2.1. **Semantic Versioning**: Use semantic versioning (MAJOR.MINOR.PATCH) based on conventional commits
-2.2. **Version Bump Logic**:
-
-- `feat:` commits → MINOR version bump
-- `fix:` commits → PATCH version bump
-- `BREAKING CHANGE:` or `!` → MAJOR version bump
-- Other types → no version bump
-  2.3. **Version Detection**: Automatically detect when version should be bumped based on unreleased commits
-  2.4. **Version File Update**: Automatically update `lib/opaque_id/version.rb` with new version
-
-### 3. GitHub Actions Workflow
-
-3.1. **Single Workflow**: Update existing `main.yml` to include release automation
-3.2. **Trigger Conditions**: Run on push to main branch when unreleased changes exist
-3.3. **Workflow Steps**:
-
-- Checkout code
-- Setup Ruby environment
-- Install dependencies
-- Run tests
-- Run RuboCop
-- Security audit
-- Determine version bump
-- Update version file
-- Generate changelog
-- Create git tag
-- Publish to RubyGems.org
-- Create GitHub release
-
-### 4. Quality Gates
-
-4.1. **Test Execution**: Run full test suite before any release
-4.2. **Code Quality**: Run RuboCop and fail if violations exist
-4.3. **Security Scanning**: Run `bundle audit` to check for vulnerable dependencies
-4.4. **Dependency Check**: Ensure all dependencies are up-to-date and secure
-
-### 5. Changelog Generation
-
-5.1. **Automated Generation**: Generate changelog from conventional commits since last release
-5.2. **Changelog Format**: Use conventional changelog format with categorized sections
-5.3. **Changelog Sections**: Features, Bug Fixes, Breaking Changes, Documentation, etc.
-5.4. **Changelog Update**: Automatically update `CHANGELOG.md` with new entries
-
-### 6. RubyGems Publishing
-
-6.1. **Trusted Publishing**: Use RubyGems trusted publishing (no API keys required)
-6.2. **MFA Enforcement**: Ensure MFA is required for publishing (already configured)
-6.3. **Build Process**: Build gem package before publishing
-6.4. **Publish Process**: Automatically push to RubyGems.org when all checks pass
-
-### 7. Dependabot Integration
-
-7.1. **Weekly Updates**: Check for dependency updates every Monday at 9 AM
-7.2. **Update Types**: Check for both direct and indirect dependency updates
-7.3. **Security Updates**: Prioritize security-related updates
-7.4. **Update Strategy**: Create pull requests for dependency updates
-
-### 8. Git Tag Management
-
-8.1. **Automatic Tagging**: Create git tags for each release (e.g., `v1.2.3`)
-8.2. **Tag Format**: Use semantic versioning format with `v` prefix
-8.3. **Tag Push**: Automatically push tags to GitHub repository
-8.4. **GitHub Release**: Create GitHub release with changelog and tag
-
-## Non-Goals (Out of Scope)
-
-1. **Manual Release Override**: No manual release triggers or overrides
-2. **Multiple Branch Support**: Only support releases from main branch
-3. **Pre-release Versions**: No support for alpha/beta/rc versions initially
-4. **Monorepo Support**: Single gem repository only
-5. **Custom Versioning Logic**: No custom versioning rules beyond conventional commits
-6. **Rollback Automation**: No automatic rollback of failed releases
-
-## Technical Considerations
-
-### Dependencies
-
-- **Release Please**: Google's tool for PR-based versioning and changelog generation
-- **Bundler's release tasks**: Built-in rake tasks for building and tagging (already present)
-- **commitlint**: For commit message validation (optional)
-- **bundle-audit**: For security scanning
-
-### GitHub Actions
-
-- **googleapis/release-please-action**: For creating release PRs and versioning
-- **rubygems/release-gem**: For RubyGems publishing with trusted publishing
-- **actions/checkout**: For code checkout
-- **ruby/setup-ruby**: For Ruby environment setup
-
-### Configuration Files
-
-- **release-please-config.json**: Release Please configuration
-- **dependabot.yml**: Dependency update configuration
-- **.github/workflows/release-please.yml**: Release PR workflow
-- **.github/workflows/publish.yml**: Publishing workflow
-
-### RubyGems Trusted Publishing
-
-- Configure trusted publishing on RubyGems.org
-- Use GitHub OIDC for authentication
-- No API keys or secrets required
-
-## Success Metrics
-
-1. **Release Automation**: 100% of releases are automated (no manual intervention)
-2. **Release Frequency**: Ability to release multiple times per day if needed
-3. **Quality Gates**: 0% of releases with failing tests or security issues
-4. **Commit Compliance**: 100% of commits follow conventional commit format
-5. **Dependency Currency**: Dependencies updated within 7 days of availability
-6. **Release Time**: From commit to published gem in under 10 minutes
-
-## Open Questions
-
-1. **Commit Message Enforcement**: Should we use pre-commit hooks or GitHub Actions validation?
-2. **Changelog Format**: Should we use conventional-changelog or custom format?
-3. **Version Bump Strategy**: Should we batch multiple commits into single releases?
-4. **Rollback Strategy**: How should we handle failed releases or rollbacks?
-5. **Notification Strategy**: Should we notify maintainers of successful/failed releases?
-6. **Branch Protection**: Should we require status checks before merging to main?
-
-## Implementation Priority
-
-### Phase 1: Core Automation
-
-- Conventional commits validation
-- Automated versioning
-- Basic GitHub Actions workflow
-- RubyGems publishing
-
-### Phase 2: Quality & Security
-
-- Quality gates (tests, RuboCop, security)
-- Automated changelog generation
-- Dependabot integration
-
-### Phase 3: Polish & Monitoring
-
-- Enhanced notifications
-- Release monitoring
-- Performance optimization
-
-## Acceptance Criteria
-
-- [ ] All commits follow conventional commit format
-- [ ] Version numbers are automatically bumped based on commit types
-- [ ] Releases are automatically published to RubyGems.org
-- [ ] Changelog is automatically generated from commits
-- [ ] All tests pass before release
-- [ ] RuboCop passes before release
-- [ ] Security audit passes before release
-- [ ] Dependencies are automatically updated weekly
-- [ ] Git tags are automatically created for releases
-- [ ] GitHub releases are automatically created
-- [ ] RubyGems trusted publishing is configured
-- [ ] No manual intervention required for releases