e11y 0.1.0 → 0.2.0

data/docs/ADR-017-multi-rails-compatibility.md

@@ -0,0 +1,103 @@
+# ADR-017: Multi-Rails Version Compatibility
+
+**Status:** Accepted  
+**Date:** January 26, 2026  
+**Covers:** Cross-cutting concern  
+**Depends On:** ADR-008 (Rails Integration)
+
+---
+
+## Context & Problem
+
+E11y initially supported only Rails 8.0, limiting adoption:
+- ~40% of Rails apps still on 7.x
+- Enterprise upgrades take 12-18 months
+- No migration path for Rails 7 users
+
+---
+
+## Decision
+
+Support Rails 7.0, 7.1, 8.0 with dynamic version detection.
+
+**Implementation:**
+
+```ruby
+# Gemfile
+rails_version = ENV.fetch('RAILS_VERSION', '8.0')
+gem 'rails', "~> #{rails_version}.0", "< 8.1"
+
+if rails_version.to_f < 8.0
+  gem 'sqlite3', '~> 1.4' # Rails 7.x
+else
+  gem 'sqlite3', '~> 2.0' # Rails 8.x
+end
+```
+
+**CI Matrix:**
+```yaml
+matrix:
+  ruby: ['3.2', '3.3']
+  rails: ['7.0', '7.1', '8.0']
+# Total: 6 combinations
+```
+
+---
+
+## Consequences
+
+### Positive
+- Doubles potential user base
+- Enterprise-friendly (slower upgrade cycles)
+- Migration path (use E11y during Rails upgrade)
+- Full feature parity (no degradation)
+
+### Negative
+- CI time: 5min → 15min (3× Rails versions)
+- Maintenance: 3 Rails versions to test
+- Conditional code (2 places only)
+
+---
+
+## Version-Specific Code
+
+**1. Exception handling (Rails 8.0 changed behavior):**
+```ruby
+if Rails.version.to_f >= 8.0
+  expect(response.status).to eq(500) # Rails 8.0: caught
+else
+  expect { get '/error' }.to raise_error # Rails 7.x: raised
+end
+```
+
+**2. sqlite3 dependency (Gemfile only)**
+
+---
+
+## Maintenance Plan
+
+**Drop Rails 7.0 when:**
+- Rails 7.0 EOL (~2027)
+- <5% users on Rails 7.0
+- Rails 9.0 released
+
+**Review quarterly:** Check market share, update CI matrix.
+
+---
+
+## Alternatives Considered
+
+1. **Rails 8.0 only** - Rejected: excludes 40% users
+2. **Rails 6.x support** - Rejected: EOL June 2024
+3. **Backport gem** - Rejected: doubles maintenance
+
+---
+
+## Success Metrics
+
+| Metric | Target | Current |
+|--------|--------|---------|
+| Test pass rate | 100% | 100% ✅ |
+| Code coverage | ≥95% | 96.46% ✅ |
+| Version checks | <10 | 2 ✅ |
+| CI time | <20min | ~15min ✅ |

data/docs/ADR-INDEX.md

@@ -0,0 +1,99 @@
+# Architecture Decision Records (ADR) Index
+
+This document provides an index of all architectural decisions made for the E11y gem.
+
+## 📋 Index
+
+| ADR | Title | Status | Phase |
+|-----|-------|--------|-------|
+| [ADR-001](ADR-001-architecture.md) | Architecture & Design Principles | ✅ Accepted | 0 |
+| [ADR-002](ADR-002-metrics-yabeda.md) | Metrics Integration (Yabeda) | ✅ Accepted | 2 |
+| [ADR-003](ADR-003-slo-observability.md) | SLO Observability | ✅ Accepted | 2 |
+| [ADR-004](ADR-004-adapter-architecture.md) | Adapter Architecture | ✅ Accepted | 2 |
+| [ADR-005](ADR-005-tracing-context.md) | Tracing Context Propagation | ✅ Accepted | 2 |
+| [ADR-006](ADR-006-security-compliance.md) | Security & Compliance (GDPR/SOC2) | ✅ Accepted | 2 |
+| [ADR-007](ADR-007-opentelemetry-integration.md) | OpenTelemetry Integration | ✅ Accepted | 3 |
+| [ADR-008](ADR-008-rails-integration.md) | Rails Integration Strategy | ✅ Accepted | 3 |
+| [ADR-009](ADR-009-cost-optimization.md) | Cost Optimization Strategies | ✅ Accepted | 4 |
+| [ADR-010](ADR-010-developer-experience.md) | Developer Experience (DX) | ✅ Accepted | 5 |
+| [ADR-011](ADR-011-testing-strategy.md) | Testing Strategy | ✅ Accepted | 5 |
+| [ADR-012](ADR-012-event-evolution.md) | Event Schema Evolution | ✅ Accepted | 1 |
+| [ADR-013](ADR-013-reliability-error-handling.md) | Reliability & Error Handling | ✅ Accepted | 4 |
+| [ADR-014](ADR-014-event-driven-slo.md) | Event-Driven SLO Tracking | ✅ Accepted | 3 |
+| [ADR-015](ADR-015-middleware-order.md) | Middleware Execution Order | ✅ Accepted | 2 |
+| [ADR-016](ADR-016-self-monitoring-slo.md) | Self-Monitoring SLO | ✅ Accepted | 4 |
+
+## 🎯 Key Decisions by Topic
+
+### Architecture & Design
+- **ADR-001**: Core architecture principles, zero-allocation pattern, convention over configuration
+- **ADR-012**: Event schema evolution strategy with versioning
+
+### Performance & Scale
+- **ADR-001 §5**: Performance requirements (1K/10K/100K events/sec)
+- **ADR-009**: Cost optimization strategies (adaptive sampling, compression, tiered storage)
+
+### Reliability & Operations
+- **ADR-013**: Circuit breakers, retry policies, dead letter queues
+- **ADR-016**: Self-monitoring SLO targets
+
+### Integration & Adapters
+- **ADR-004**: Pluggable adapter architecture
+- **ADR-007**: OpenTelemetry integration for distributed tracing
+- **ADR-008**: Rails integration patterns (Railtie, instrumentation)
+
+### Observability
+- **ADR-002**: Yabeda metrics integration
+- **ADR-003**: SLO observability patterns
+- **ADR-014**: Event-driven SLO tracking
+
+### Security & Compliance
+- **ADR-006**: GDPR/SOC2 compliance (PII filtering, audit trails, encryption)
+- **ADR-005**: Trace context propagation
+
+### Developer Experience
+- **ADR-010**: Developer experience priorities (5-min setup, conventions)
+- **ADR-011**: Testing strategy (RSpec, integration tests, benchmarks)
+- **ADR-015**: Middleware execution order guarantees
+
+## 📚 Decision Process
+
+All ADRs follow this structure:
+
+1. **Context** - The issue motivating this decision
+2. **Decision** - The change that we're proposing or have agreed to
+3. **Consequences** - What becomes easier or more difficult to do
+
+## 🔄 Status Legend
+
+- ✅ **Accepted** - Decision is final and implemented
+- 🔄 **Proposed** - Under review
+- ❌ **Rejected** - Decision was not accepted
+- ⚠️ **Deprecated** - Superseded by a newer decision
+
+## 📖 How to Read ADRs
+
+### For New Contributors
+Start with:
+1. [ADR-001](ADR-001-architecture.md) - Core architecture principles
+2. [ADR-010](ADR-010-developer-experience.md) - Developer experience goals
+3. [ADR-008](ADR-008-rails-integration.md) - Rails integration patterns
+
+### For Production Deployment
+Review:
+1. [ADR-013](ADR-013-reliability-error-handling.md) - Reliability patterns
+2. [ADR-006](ADR-006-security-compliance.md) - Security & compliance
+3. [ADR-009](ADR-009-cost-optimization.md) - Cost optimization
+
+### For Performance Tuning
+See:
+1. [ADR-001 §5](ADR-001-architecture.md) - Performance requirements
+2. [ADR-009](ADR-009-cost-optimization.md) - Optimization strategies
+3. [docs/guides/performance-tuning.md](guides/performance-tuning.md) - Tuning guide
+
+## 🔗 Related Documentation
+
+- [Implementation Plan](IMPLEMENTATION_PLAN.md) - Detailed development timeline
+- [Use Cases](use_cases/) - User scenarios and requirements
+- [API Reference](API.md) - Public API documentation
+- [Guides](guides/) - How-to guides for common tasks

data/docs/CONTRIBUTING.md

@@ -0,0 +1,312 @@
+# Contributing to E11y
+
+Thank you for your interest in contributing to E11y! This document provides guidelines and instructions for contributing.
+
+## 📋 Table of Contents
+
+- [Getting Started](#getting-started)
+- [Development Setup](#development-setup)
+- [Running Tests](#running-tests)
+- [Code Style](#code-style)
+- [Submitting Changes](#submitting-changes)
+
+## 🚀 Getting Started
+
+### Prerequisites
+
+- **Ruby 3.2+** (recommended: 3.3+)
+- **Bundler 2.0+**
+- **Docker & Docker Compose** (for integration tests)
+- **Git**
+
+### Fork and Clone
+
+```bash
+# Fork the repository on GitHub
+# Then clone your fork
+git clone git@github.com:YOUR_USERNAME/e11y.git
+cd e11y
+```
+
+## 🔧 Development Setup
+
+### 1. Install Dependencies
+
+```bash
+# Run setup script (configures bundle, installs dependencies)
+bin/setup
+```
+
+This will:
+- Configure bundle to exclude integration dependencies by default
+- Install core dependencies
+- Display available commands
+
+### 2. Install Integration Dependencies (Optional)
+
+For working on Rails integration, OpenTelemetry adapter, or other integrations:
+
+```bash
+bundle install --with integration
+```
+
+This installs:
+- Rails 8.0
+- OpenTelemetry SDK
+- RSpec Rails
+- Database Cleaner
+
+## 🧪 Running Tests
+
+E11y has two types of tests:
+
+### Unit Tests (Default)
+
+Fast, isolated tests without external dependencies:
+
+```bash
+bundle exec rspec
+```
+
+- **Duration**: ~2 minutes
+- **Coverage**: 100% required
+- **When to run**: Before every commit
+
+### Integration Tests
+
+Full tests with Rails, OpenTelemetry SDK, and docker-compose services:
+
+```bash
+# Option 1: Using helper script (recommended)
+bin/test-integration
+
+# Option 2: Manual
+docker-compose up -d
+INTEGRATION=true bundle exec rspec --tag integration
+docker-compose down
+```
+
+- **Duration**: ~5 minutes
+- **When to run**: Before submitting PR, when changing integrations
+- **Requirements**: Docker, integration dependencies installed
+
+See [Integration Testing Guide](testing/integration-tests.md) for detailed instructions.
+
+### Running Specific Tests
+
+```bash
+# Run specific file
+bundle exec rspec spec/e11y/event/base_spec.rb
+
+# Run specific example
+bundle exec rspec spec/e11y/event/base_spec.rb:42
+
+# Run tests matching pattern
+bundle exec rspec --tag validation
+```
+
+## 📝 Code Style
+
+E11y follows the Ruby community style guide with RuboCop:
+
+### Run Linter
+
+```bash
+# Check code style
+bundle exec rubocop
+
+# Auto-fix issues
+bundle exec rubocop -a
+```
+
+### Key Conventions
+
+- **100% test coverage** required
+- **Type-safe code** - use dry-schema, dry-types
+- **Thread-safe** - avoid shared mutable state
+- **Performance-conscious** - zero-allocation patterns where possible
+- **Documentation** - YARD comments for public APIs
+
+## 🔒 Security
+
+### Run Security Audits
+
+```bash
+# Check for vulnerable dependencies
+bundle exec bundler-audit check --update
+
+# Static security analysis
+bundle exec brakeman
+```
+
+## 📦 Submitting Changes
+
+### 1. Create a Branch
+
+```bash
+git checkout -b feature/your-feature-name
+# or
+git checkout -b fix/issue-description
+```
+
+### 2. Make Your Changes
+
+- Write tests first (TDD)
+- Ensure all tests pass
+- Update documentation
+- Follow code style guidelines
+
+### 3. Commit Your Changes
+
+```bash
+git add .
+git commit -m "feat: add awesome feature
+
+- Added X functionality
+- Updated Y documentation
+- Fixed Z edge case
+
+Closes #123"
+```
+
+Use [Conventional Commits](https://www.conventionalcommits.org/):
+- `feat:` - New feature
+- `fix:` - Bug fix
+- `docs:` - Documentation only
+- `refactor:` - Code refactoring
+- `test:` - Adding tests
+- `chore:` - Maintenance tasks
+
+### 4. Push and Create Pull Request
+
+```bash
+git push origin feature/your-feature-name
+```
+
+Then create a PR on GitHub with:
+- Clear description of changes
+- Link to related issue
+- Screenshots (if UI changes)
+- Test results
+
+### 5. PR Review Process
+
+Your PR will be reviewed for:
+- ✅ All tests pass (unit + integration in CI)
+- ✅ 100% code coverage maintained
+- ✅ RuboCop passes
+- ✅ Security audits pass
+- ✅ Documentation updated
+- ✅ Follows coding conventions
+
+## 🐛 Reporting Bugs
+
+### Before Reporting
+
+1. Search existing issues
+2. Check if bug still exists in main branch
+3. Reproduce with minimal example
+
+### Bug Report Template
+
+```markdown
+**Describe the bug**
+A clear description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce:
+1. Configure E11y with...
+2. Call `SomeEvent.track(...)`
+3. See error
+
+**Expected behavior**
+What you expected to happen.
+
+**Actual behavior**
+What actually happened.
+
+**Environment**
+- Ruby version: 3.3.0
+- E11y version: 0.1.0
+- Rails version (if applicable): 8.0.0
+- OS: macOS 14.0
+
+**Additional context**
+Any other relevant information.
+```
+
+## 💡 Suggesting Features
+
+### Feature Request Template
+
+```markdown
+**Problem**
+What problem does this solve?
+
+**Proposed Solution**
+How should E11y solve this?
+
+**Alternatives**
+What alternatives have you considered?
+
+**Additional Context**
+Examples, use cases, references.
+```
+
+## 📚 Development Resources
+
+### Documentation
+
+- [Architecture Decisions (ADRs)](../docs/)
+- [Implementation Plan](IMPLEMENTATION_PLAN.md)
+- [API Reference](API.md)
+- [Integration Testing Guide](testing/integration-tests.md)
+
+### Code Structure
+
+```
+lib/e11y/
+├── event/           # Event system
+├── adapters/        # Backend adapters
+├── buffers/         # Memory buffers
+├── middleware/      # Pipeline middleware
+├── reliability/     # Retry, circuit breaker, DLQ
+├── sampling/        # Sampling strategies
+├── self_monitoring/ # Internal metrics
+└── slo/            # SLO tracking
+```
+
+### Useful Commands
+
+```bash
+# Interactive console
+bin/console
+
+# Generate documentation
+bundle exec yard doc
+
+# Performance benchmarks
+bundle exec ruby benchmarks/run_all.rb
+
+# Check for breaking changes
+bundle exec ruby scripts/check_compatibility.rb
+```
+
+## 🤝 Code of Conduct
+
+By participating in this project, you agree to abide by our [Code of Conduct](../CODE_OF_CONDUCT.md).
+
+## 📧 Getting Help
+
+- **Questions**: Open a GitHub Discussion
+- **Bugs**: Open a GitHub Issue
+- **Security**: Email security@e11y.dev (private disclosure)
+
+## 🎉 Recognition
+
+Contributors are recognized in:
+- [CHANGELOG.md](../CHANGELOG.md)
+- GitHub Contributors page
+- Release notes
+
+Thank you for contributing to E11y! 🚀

data/docs/IMPLEMENTATION_PLAN.md

@@ -1581,7 +1581,7 @@ PHASE 5: SCALE & OPTIMIZATION (Weeks 21-26)
 1. **Gemspec**
    - File: `e11y.gemspec`
    - Dependencies (dry-schema, yabeda, concurrent-ruby)
-   - Version (1.0.0)
+   - Version (0.1.0)
    - License (MIT)
    - ✅ DoD: Gem builds successfully
 

data/docs/QUICK-START.md

@@ -925,10 +925,4 @@ Yabeda.e11y.track_duration_seconds # p99 should be <1ms
 - [ ] Monitor performance
 - [ ] Rollout to production (canary 1% → 10% → 100%)
 
----
-
-**Questions?** See `e11y-final-spec.md` FAQ section or open GitHub issue.
-
-**Version**: 1.0.0  
-**Last Updated**: 2025-12-24