e11y 0.1.0 → 0.2.0

data/RELEASE.md

@@ -0,0 +1,254 @@
+# Release Instructions for e11y
+
+## Quick Release (Automated)
+
+```bash
+# 1. Bump version (updates VERSION + CHANGELOG)
+rake release:bump
+# Enter new version when prompted, e.g., 0.2.0
+
+# 2. Review and commit
+git diff
+git add -A
+git commit -m "Bump version to 0.2.0"
+
+# 3. Full release (test + build + tag + push + publish)
+rake release:full
+```
+
+For more control, see [Step-by-Step Release](#step-by-step-release) below.
+
+## Pre-Release Checklist
+
+- [ ] All changes documented in CHANGELOG.md under `[Unreleased]`
+- [ ] Version bumped: `rake release:bump`
+- [ ] All tests passing: `rake spec`
+- [ ] Changes committed
+- [ ] Git tag created
+- [ ] Published to RubyGems.org
+- [ ] GitHub release created
+
+## Step-by-Step Release
+
+### Step 0: Bump Version
+
+First, update version and CHANGELOG:
+
+```bash
+rake release:bump
+```
+
+This will:
+1. Prompt for new version (e.g., 0.2.0)
+2. Update `lib/e11y/version.rb`
+3. Convert `[Unreleased]` → `[0.2.0] - YYYY-MM-DD` in CHANGELOG
+4. Add new empty `[Unreleased]` section
+
+Commit the changes:
+
+```bash
+git add -A
+git commit -m "Bump version to 0.2.0"
+```
+
+### Step 1: Prepare Release
+
+Run tests, build gem, create tag:
+
+```bash
+rake release:prep
+```
+
+This will:
+- ✅ Check git status (fails if uncommitted changes)
+- ✅ Run full test suite
+- ✅ Build gem file
+- ✅ Create annotated git tag
+
+Or manually:
+
+```bash
+# Run all tests
+bundle exec rspec
+
+# Build gem
+gem build e11y.gemspec
+
+# Create and push tag
+git tag -a v0.2.0 -m "Release v0.2.0"
+git push origin main
+git push origin v0.2.0
+```
+
+### Step 2: Push to GitHub
+
+```bash
+rake release:git_push
+```
+
+This will:
+- ✅ Verify tag exists
+- ✅ Push commits to origin/main
+- ✅ Push tag to origin
+- ✅ Show GitHub release URL
+
+### Step 3: Publish to RubyGems.org
+
+```bash
+rake release:gem_push
+```
+
+This will:
+- ✅ Verify gem file exists
+- ✅ Prompt for confirmation
+- ✅ Push gem to RubyGems (requires MFA)
+- ✅ Show verification URL
+
+Or manually:
+
+### Prerequisites
+
+1. **RubyGems Account**: Create account at https://rubygems.org/sign_up
+2. **API Key**: Get your API key from https://rubygems.org/profile/edit
+3. **MFA Enabled**: This gem requires MFA (configured in gemspec)
+
+### Publish Command
+
+```bash
+# Sign in to RubyGems (one-time setup)
+gem signin
+
+# Push the gem (requires MFA)
+gem push e11y-0.1.0.gem
+```
+
+Expected output:
+```
+Pushing gem to https://rubygems.org...
+Enter your RubyGems.org credentials.
+Username: [your_username]
+Password: [your_password]
+MFA Code: [6-digit code from authenticator app]
+Successfully registered gem: e11y (0.1.0)
+```
+
+### Verify Publication
+
+```bash
+# Check gem is available
+gem search e11y --remote
+
+# Install from RubyGems
+gem install e11y
+```
+
+## Step 3: Create GitHub Release
+
+1. Go to https://github.com/arturseletskiy/e11y/releases/new
+2. Choose tag: `v0.1.0`
+3. Release title: `v0.1.0 - First Production Release`
+4. Description: Use content from CHANGELOG.md (see below)
+5. Attach binary: Upload `e11y-0.1.0.gem`
+6. Click "Publish release"
+
+### GitHub Release Notes Template
+
+```markdown
+# 🎉 E11y 0.1.0 - First Production Release
+
+Production-ready observability gem for Ruby on Rails with zero-config SLO tracking, request-scoped buffering, and high-performance event streaming.
+
+## 🚀 Highlights
+
+- **Zero-Config SLO Tracking** - Automatic Service Level Objectives for HTTP and background jobs
+- **100K+ events/sec** - Benchmark-validated performance (p99 <50μs latency)
+- **99%+ Test Coverage** - 1409 test examples, battle-tested
+- **16 ADRs** - Fully documented architecture decisions
+- **Cardinality Protection** - 4-layer defense against metric explosions
+- **Production-Ready** - Reliability layer with retry, circuit breaker, DLQ
+
+## 📦 Installation
+
+```ruby
+# Gemfile
+gem 'e11y', '~> 1.0'
+```
+
+```bash
+bundle install
+```
+
+## 📚 Documentation
+
+- **Quick Start**: [README.md](https://github.com/arturseletskiy/e11y#quick-start)
+- **Architecture**: [docs/ADR-INDEX.md](https://github.com/arturseletskiy/e11y/blob/main/docs/ADR-INDEX.md)
+- **Benchmarks**: [benchmarks/README.md](https://github.com/arturseletskiy/e11y/blob/main/benchmarks/README.md)
+
+## 🔥 What's New
+
+See [CHANGELOG.md](https://github.com/arturseletskiy/e11y/blob/main/CHANGELOG.md) for full details.
+
+### Core Features (Phase 1-2)
+- Event System with dry-schema validation
+- Pipeline Architecture (middleware-based)
+- 7 Adapters: Stdout, File, InMemory, Loki, Sentry, OpenTelemetry, Yabeda
+- 3 Buffer Types: RingBuffer, RequestScopedBuffer, AdaptiveBuffer
+- Reliability: Retry, Circuit Breaker, Dead Letter Queue
+
+### SLO Tracking (Phase 3)
+- Event-Driven SLOs for HTTP/jobs
+- Stratified Sampling (latency-aware)
+- Error Spike Detection
+- Value-Based Sampling
+
+### Rails Integration (Phase 4)
+- Auto-instrumentation for Rails events
+- HTTP request tracking
+- Background job tracking (ActiveJob, Sidekiq)
+- Database query events
+- Logger bridge (Rails.logger → E11y)
+
+### Scale & Performance (Phase 5)
+- Cardinality Protection (4-layer defense)
+- Tiered Storage (hot/warm/cold)
+- Benchmarked: 100K events/sec, p99 <50μs
+
+## ⚡ Performance
+
+| Scale | Latency (p99) | Throughput | Memory |
+|-------|--------------|------------|---------|
+| Small (1K/s) | 47μs | 107K/s | 1.95 MB |
+| Medium (10K/s) | 33μs | 110K/s | 19.49 MB |
+| Large (100K/s) | 26μs | 109K/s | 194.93 MB |
+
+## 🙏 Credits
+
+Built with patterns from Devise, Sidekiq, Puma, Dry-rb, Yabeda, and Sentry.
+
+---
+
+**Full Changelog**: https://github.com/arturseletskiy/e11y/blob/main/CHANGELOG.md
+```
+
+## Post-Release Tasks
+
+- [ ] Announce on Twitter/social media
+- [ ] Update README badge with latest version
+- [ ] Monitor RubyGems download stats
+- [ ] Monitor GitHub issues for bug reports
+
+## Rollback Procedure (if needed)
+
+If critical bug found after release:
+
+```bash
+# Yank the gem (makes it unavailable for new installs)
+gem yank e11y -v 0.1.0
+
+# Fix the issue, bump to 1.0.1, and re-release
+```
+
+## Support
+
+- **Issues**: https://github.com/arturseletskiy/e11y/issues
+- **Discussions**: https://github.com/arturseletskiy/e11y/discussions

data/Rakefile

@@ -1,5 +1,21 @@
 # frozen_string_literal: true
 
+#
+# E11y Gem Rakefile
+#
+# Quick reference:
+#   rake                   # Run tests and rubocop
+#   rake release:bump      # Bump version and update CHANGELOG (interactive)
+#   rake release:full      # Complete release workflow (prep + git_push + gem_push)
+#   rake release:prep      # Run tests, build gem, create tag
+#   rake release:git_push  # Push to GitHub
+#   rake release:gem_push  # Publish to RubyGems
+#   rake spec:all          # Run all test suites
+#   rake spec:unit         # Run unit tests only (fast)
+#   rake spec:integration  # Run integration tests
+#
+# See RELEASE.md for detailed release instructions
+
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 require "rubocop/rake_task"
@@ -10,6 +26,82 @@ RuboCop::RakeTask.new
 
 task default: %i[spec rubocop]
 
+# Test suite tasks
+namespace :spec do
+  desc "Run unit tests only (fast, no Rails/integrations)"
+  task :unit do
+    sh "bundle exec rspec spec/e11y spec/e11y_spec.rb spec/zeitwerk_spec.rb"
+  end
+
+  desc "Run integration tests (requires Rails, bundle install --with integration)"
+  task :integration do
+    # Run integration tests with explicit file patterns to avoid loading all specs
+    # This prevents test pollution from unit test files
+    sh "INTEGRATION=true bundle exec rspec " \
+       "spec/integration/*.rb " \
+       "spec/e11y/adapters/*_spec.rb " \
+       "spec/e11y/instruments/*_spec.rb " \
+       "--tag integration"
+  end
+
+  desc "Run railtie integration tests (separate Rails app instance)"
+  task :railtie do
+    sh "bundle exec rspec spec/e11y/railtie_integration_spec.rb --tag railtie_integration"
+  end
+
+  desc "Run all tests (unit + integration + railtie, ~1729 examples)"
+  task :all do
+    puts "\n#{'=' * 80}"
+    puts "Running UNIT tests (spec/e11y + top-level specs)..."
+    puts "#{'=' * 80}\n"
+    Rake::Task["spec:unit"].invoke
+
+    puts "\n#{'=' * 80}"
+    puts "Running INTEGRATION tests (spec/integration)..."
+    puts "#{'=' * 80}\n"
+    Rake::Task["spec:integration"].invoke
+
+    puts "\n#{'=' * 80}"
+    puts "Running RAILTIE tests (Rails initialization)..."
+    puts "#{'=' * 80}\n"
+    Rake::Task["spec:railtie"].invoke
+
+    puts "\n#{'=' * 80}"
+    puts "✅ All test suites completed!"
+    puts "#{'=' * 80}\n"
+  end
+
+  desc "Run tests with coverage report"
+  task :coverage do
+    sh "COVERAGE=true bundle exec rspec"
+  end
+
+  desc "Run integration tests with coverage"
+  task :coverage_integration do
+    sh "COVERAGE=true INTEGRATION=true bundle exec rspec spec/integration/"
+  end
+
+  desc "Run benchmark tests (performance tests, slow)"
+  task :benchmark do
+    sh "bundle exec rspec spec/e11y --tag benchmark"
+  end
+
+  desc "Run ALL tests including benchmarks (very slow)"
+  task :everything do
+    puts "\n#{'=' * 80}"
+    puts "Running ALL tests (unit + integration + railtie + benchmarks)"
+    puts "#{'=' * 80}\n"
+    Rake::Task["spec:unit"].invoke
+    Rake::Task["spec:integration"].invoke
+    Rake::Task["spec:railtie"].invoke
+    Rake::Task["spec:benchmark"].invoke
+
+    puts "\n#{'=' * 80}"
+    puts "✅ All test suites including benchmarks completed!"
+    puts "#{'=' * 80}\n"
+  end
+end
+
 # Custom tasks
 namespace :e11y do
   desc "Start interactive console"
@@ -35,3 +127,288 @@ namespace :e11y do
     sh "bundle exec brakeman --no-pager"
   end
 end
+
+# Custom release automation (extends bundler/gem_tasks)
+# Note: bundler/gem_tasks provides: release, release:guard_clean, release:rubygem_push, etc.
+# Our tasks provide more control and visibility
+namespace :release do
+  desc "Bump version and update CHANGELOG (interactive)"
+  task :bump do
+    require_relative "lib/e11y/version"
+    current_version = E11y::VERSION
+    
+    puts "\n#{'=' * 80}"
+    puts "📝 Version Bump"
+    puts "#{'=' * 80}\n"
+    puts "Current version: #{current_version}"
+    puts "\nEnter new version (e.g., 0.2.0, 1.0.0):"
+    
+    new_version = $stdin.gets.chomp.strip
+    
+    if new_version.empty?
+      puts "❌ Error: Version cannot be empty"
+      exit 1
+    end
+    
+    unless new_version.match?(/^\d+\.\d+\.\d+$/)
+      puts "❌ Error: Invalid version format. Use semantic versioning (e.g., 0.2.0)"
+      exit 1
+    end
+    
+    if new_version == current_version
+      puts "⚠️  Warning: New version is the same as current version"
+      puts "Continue anyway? (y/N)"
+      response = $stdin.gets.chomp.downcase
+      exit 0 unless response == "y" || response == "yes"
+    end
+    
+    puts "\n[1/3] Updating lib/e11y/version.rb..."
+    version_file = "lib/e11y/version.rb"
+    version_content = File.read(version_file)
+    updated_version_content = version_content.gsub(
+      /VERSION = "#{Regexp.escape(current_version)}"/,
+      "VERSION = \"#{new_version}\""
+    )
+    File.write(version_file, updated_version_content)
+    puts "✅ Updated: #{current_version} → #{new_version}"
+    
+    puts "\n[2/3] Updating CHANGELOG.md..."
+    changelog_file = "CHANGELOG.md"
+    changelog_content = File.read(changelog_file)
+    
+    # Check if there's an [Unreleased] section
+    if changelog_content.include?("## [Unreleased]")
+      # Replace [Unreleased] with version and date
+      today = Time.now.strftime("%Y-%m-%d")
+      updated_changelog = changelog_content.sub(
+        /## \[Unreleased\]/,
+        "## [#{new_version}] - #{today}"
+      )
+      
+      # Add new [Unreleased] section at the top
+      updated_changelog = updated_changelog.sub(
+        /(## \[#{Regexp.escape(new_version)}\] - #{today})/,
+        "## [Unreleased]\n\n### Added\n\n### Changed\n\n### Fixed\n\n### Deprecated\n\n### Removed\n\n### Security\n\n\\1"
+      )
+      
+      File.write(changelog_file, updated_changelog)
+      puts "✅ Updated CHANGELOG.md:"
+      puts "   - [Unreleased] → [#{new_version}] - #{today}"
+      puts "   - Added new [Unreleased] section"
+    else
+      # No [Unreleased] section, just add version entry
+      today = Time.now.strftime("%Y-%m-%d")
+      
+      # Find where to insert (after the header, before first version)
+      if changelog_content =~ /(## \[\d+\.\d+\.\d+\])/
+        updated_changelog = changelog_content.sub(
+          /(## \[\d+\.\d+\.\d+\])/,
+          "## [Unreleased]\n\n### Added\n\n### Changed\n\n### Fixed\n\n### Deprecated\n\n### Removed\n\n### Security\n\n## [#{new_version}] - #{today}\n\n### Added\n- Version bump\n\n\\1"
+        )
+      else
+        # No previous versions, add after header
+        header_end = changelog_content.index("\n\n") || 0
+        header = changelog_content[0..header_end]
+        rest = changelog_content[header_end + 1..-1] || ""
+        updated_changelog = "#{header}\n## [#{new_version}] - #{today}\n\n### Added\n- Initial release\n\n#{rest}"
+      end
+      
+      File.write(changelog_file, updated_changelog)
+      puts "✅ Added version [#{new_version}] - #{today} to CHANGELOG.md"
+    end
+    
+    puts "\n[3/3] Summary"
+    puts "✅ Version bumped: #{current_version} → #{new_version}"
+    puts "✅ Files updated:"
+    puts "   - lib/e11y/version.rb"
+    puts "   - CHANGELOG.md"
+    
+    puts "\n#{'=' * 80}"
+    puts "Next steps:"
+    puts "  1. Review changes: git diff"
+    puts "  2. Commit changes: git add -A && git commit -m 'Bump version to #{new_version}'"
+    puts "  3. Release: rake release:prep"
+    puts "#{'=' * 80}\n"
+  end
+
+  desc "Prepare release: run tests, build gem, create git tag (safe)"
+  task :prep do
+    require_relative "lib/e11y/version"
+    version = E11y::VERSION
+
+    puts "\n#{'=' * 80}"
+    puts "📦 Preparing release for e11y v#{version}"
+    puts "#{'=' * 80}\n"
+
+    # Step 1: Check git status
+    puts "\n[1/5] Checking git status..."
+    unless system("git diff-index --quiet HEAD --")
+      puts "❌ Error: You have uncommitted changes. Please commit them first."
+      exit 1
+    end
+    puts "✅ Git working directory is clean"
+
+    # Step 2: Run tests
+    puts "\n[2/5] Running tests..."
+    unless system("bundle exec rspec")
+      puts "❌ Error: Tests failed. Please fix them before releasing."
+      exit 1
+    end
+    puts "✅ All tests passed"
+
+    # Step 3: Build gem
+    puts "\n[3/5] Building gem..."
+    unless system("gem build e11y.gemspec")
+      puts "❌ Error: Failed to build gem"
+      exit 1
+    end
+    puts "✅ Gem built: e11y-#{version}.gem"
+
+    # Step 4: Create git tag
+    puts "\n[4/5] Creating git tag..."
+    tag_name = "v#{version}"
+    tag_message = "Release v#{version}"
+
+    if system("git rev-parse #{tag_name} >/dev/null 2>&1")
+      puts "⚠️  Warning: Tag #{tag_name} already exists"
+    else
+      unless system("git tag -a #{tag_name} -m '#{tag_message}'")
+        puts "❌ Error: Failed to create git tag"
+        exit 1
+      end
+      puts "✅ Git tag created: #{tag_name}"
+    end
+
+    # Step 5: Summary
+    puts "\n[5/5] Release preparation complete!"
+    puts "\n#{'=' * 80}"
+    puts "📦 Release v#{version} is ready!"
+    puts "#{'=' * 80}\n"
+    puts "Next steps:"
+    puts "  1. Review CHANGELOG.md"
+    puts "  2. Push to GitHub:"
+    puts "     git push origin main"
+    puts "     git push origin #{tag_name}"
+    puts "  3. Publish to RubyGems:"
+    puts "     rake release:publish"
+    puts "\n"
+  end
+
+  desc "Publish gem to RubyGems.org (requires authentication, safe)"
+  task :gem_push do
+    require_relative "lib/e11y/version"
+    version = E11y::VERSION
+    gem_file = "e11y-#{version}.gem"
+
+    puts "\n#{'=' * 80}"
+    puts "📤 Publishing e11y v#{version} to RubyGems.org"
+    puts "#{'=' * 80}\n"
+
+    unless File.exist?(gem_file)
+      puts "❌ Error: Gem file not found: #{gem_file}"
+      puts "Run 'rake release:prep' first"
+      exit 1
+    end
+
+    puts "This will publish #{gem_file} to RubyGems.org"
+    puts "You will be prompted for your RubyGems credentials and MFA code."
+    puts "\nContinue? (y/N)"
+
+    response = $stdin.gets.chomp.downcase
+    unless %w[y yes].include?(response)
+      puts "❌ Publication cancelled"
+      exit 0
+    end
+
+    unless system("gem push #{gem_file}")
+      puts "\n❌ Error: Failed to publish gem"
+      puts "Make sure you have:"
+      puts "  1. RubyGems account (https://rubygems.org/sign_up)"
+      puts "  2. Signed in: gem signin"
+      puts "  3. MFA enabled on your account"
+      exit 1
+    end
+
+    puts "\n✅ Successfully published e11y v#{version} to RubyGems.org!"
+    puts "\nVerify: https://rubygems.org/gems/e11y/versions/#{version}"
+  end
+
+  desc "Push git changes and tag to GitHub (safe)"
+  task :git_push do
+    require_relative "lib/e11y/version"
+    version = E11y::VERSION
+    tag_name = "v#{version}"
+
+    puts "\n#{'=' * 80}"
+    puts "🚀 Pushing to GitHub"
+    puts "#{'=' * 80}\n"
+
+    unless system("git rev-parse #{tag_name} >/dev/null 2>&1")
+      puts "❌ Error: Tag #{tag_name} does not exist"
+      puts "Run 'rake release:prep' first"
+      exit 1
+    end
+
+    puts "[1/2] Pushing commits to origin/main..."
+    unless system("git push origin main")
+      puts "❌ Error: Failed to push commits"
+      exit 1
+    end
+    puts "✅ Commits pushed"
+
+    puts "\n[2/2] Pushing tag #{tag_name}..."
+    unless system("git push origin #{tag_name}")
+      puts "❌ Error: Failed to push tag"
+      exit 1
+    end
+    puts "✅ Tag pushed"
+
+    puts "\n✅ Successfully pushed to GitHub!"
+    puts "\nCreate GitHub release: https://github.com/arturseletskiy/e11y/releases/new?tag=#{tag_name}"
+  end
+
+  desc "Complete release workflow: prep, git_push, and gem_push (interactive)"
+  task :full do
+    Rake::Task["release:prep"].invoke
+
+    puts "\n#{'=' * 80}"
+    puts "Ready to push to GitHub and publish to RubyGems?"
+    puts "=" * 80
+    puts "This will:"
+    puts "  1. Push commits and tag to GitHub"
+    puts "  2. Publish gem to RubyGems.org"
+    puts "\nContinue? (y/N)"
+
+    response = $stdin.gets.chomp.downcase
+    unless %w[y yes].include?(response)
+      puts "\n⏸️  Release prepared but not published"
+      puts "To continue later, run:"
+      puts "  rake release:git_push  # Push to GitHub"
+      puts "  rake release:gem_push  # Publish to RubyGems"
+      exit 0
+    end
+
+    Rake::Task["release:git_push"].invoke
+    Rake::Task["release:gem_push"].invoke
+
+    puts "\n#{'=' * 80}"
+    puts "🎉 Release complete!"
+    puts "=" * 80
+    puts "\nPost-release tasks:"
+    puts "  1. Create GitHub release: https://github.com/arturseletskiy/e11y/releases/new"
+    puts "  2. Verify on RubyGems: https://rubygems.org/gems/e11y"
+    puts "  3. Update README badges"
+    puts "  4. Announce on social media"
+    puts "\n"
+  end
+
+  desc "Clean up built gems"
+  task :clean do
+    puts "🧹 Cleaning up gem files..."
+    FileList["*.gem"].each do |gem_file|
+      File.delete(gem_file)
+      puts "  Deleted: #{gem_file}"
+    end
+    puts "✅ Clean complete"
+  end
+end