mbuzz 0.6.2

data/lib/specs/old/v0.2.0_breaking_changes.md

@@ -0,0 +1,519 @@
+# mbuzz-ruby v0.2.0 - Breaking Changes & Migration Guide
+
+**Status**: Ready to Implement
+**Priority**: P0 - Blocking UAT
+**Created**: 2025-11-25
+**Target Release**: v0.2.0
+
+---
+
+## Overview
+
+Version 0.2.0 fixes critical inconsistencies between the gem and backend API that prevent events from being tracked. These are **breaking changes** that require existing users to update their code.
+
+**Impact**: Current gem (v0.1.0) sends incorrectly formatted data that will be rejected by the backend.
+
+---
+
+## Breaking Changes
+
+### 1. Parameter Name: `event` → `event_type` 🔴 BREAKING
+
+**Issue**: Gem sends `event:` but backend expects `event_type:`
+
+**Current (v0.1.0)**:
+```ruby
+Mbuzz.track(
+  user_id: current_user.id,
+  event: 'Signup',  # ❌ Backend rejects this
+  properties: { plan: 'pro' }
+)
+```
+
+**New (v0.2.0)**:
+```ruby
+Mbuzz.track(
+  user_id: current_user.id,
+  event_type: 'Signup',  # ✅ Matches backend API
+  properties: { plan: 'pro' }
+)
+```
+
+**Files to Change**:
+- `lib/mbuzz/client.rb` - Update method signature and payload
+- `lib/mbuzz.rb` - Update public API method
+- `test/mbuzz/client_test.rb` - Update all tests
+- `README.md` - Update all examples
+- `SPECIFICATION.md` - Update parameter documentation
+
+---
+
+### 2. Timestamp Format: Unix Epoch → ISO8601 🔴 BREAKING
+
+**Issue**: Gem sends Unix timestamp (integer) but backend expects ISO8601 string
+
+**Current (v0.1.0)**:
+```ruby
+# lib/mbuzz/client.rb
+{
+  event_type: event_type,
+  timestamp: Time.now.to_i  # ❌ Sends: 1732550400
+}
+```
+
+**New (v0.2.0)**:
+```ruby
+# lib/mbuzz/client.rb
+{
+  event_type: event_type,
+  timestamp: Time.now.utc.iso8601  # ✅ Sends: "2025-11-25T10:30:00Z"
+}
+```
+
+**Why UTC?**
+- Backend stores all timestamps in UTC
+- Avoids timezone confusion
+- ISO8601 format with 'Z' suffix is standard
+
+**Files to Change**:
+- `lib/mbuzz/client.rb` - Change `Time.now.to_i` → `Time.now.utc.iso8601`
+- `test/mbuzz/client_test.rb` - Update timestamp assertions
+
+---
+
+### 3. Documentation: `anonymous_id` → `visitor_id` 📝 NON-BREAKING
+
+**Issue**: SPECIFICATION.md says `anonymous_id` but implementation uses `visitor_id`
+
+**Current**:
+```markdown
+# SPECIFICATION.md
+- anonymous_id - Visitor ID from cookies (required if no user_id)
+```
+
+**New**:
+```markdown
+# SPECIFICATION.md
+- visitor_id - Visitor ID from cookies (required if no user_id)
+```
+
+**Note**: This is documentation-only. The gem implementation already uses `visitor_id` correctly.
+
+**Files to Change**:
+- `SPECIFICATION.md` - Find/replace `anonymous_id` → `visitor_id`
+
+---
+
+## Implementation Checklist
+
+### Step 1: Update Client Code
+
+**File**: `lib/mbuzz/client.rb`
+
+**Current Code** (lines ~10-16, ~25-30):
+```ruby
+def track(user_id: nil, visitor_id: nil, event:, properties: {})
+  Api.post(EVENTS_PATH, {
+    user_id: user_id,
+    visitor_id: visitor_id,
+    event: event,  # ❌ Wrong parameter name
+    properties: properties,
+    timestamp: Time.now.to_i  # ❌ Wrong format
+  })
+end
+```
+
+**New Code**:
+```ruby
+def track(user_id: nil, visitor_id: nil, event_type:, properties: {})
+  Api.post(EVENTS_PATH, {
+    user_id: user_id,
+    visitor_id: visitor_id,
+    event_type: event_type,  # ✅ Correct parameter name
+    properties: properties,
+    timestamp: Time.now.utc.iso8601  # ✅ ISO8601 format
+  })
+end
+```
+
+---
+
+### Step 2: Update Public API
+
+**File**: `lib/mbuzz.rb`
+
+**Current Code**:
+```ruby
+def self.track(event:, **options)
+  client.track(event: event, **options)
+end
+```
+
+**New Code**:
+```ruby
+def self.track(event_type:, **options)
+  client.track(event_type: event_type, **options)
+end
+```
+
+---
+
+### Step 3: Update Tests
+
+**File**: `test/mbuzz/client_test.rb`
+
+**Update all test cases**:
+```ruby
+# Before
+test "track sends event with correct payload" do
+  Mbuzz.track(
+    user_id: 1,
+    event: 'Test Event',
+    properties: { foo: 'bar' }
+  )
+
+  assert_requested :post, "#{base_url}/events", body: hash_including(
+    'event' => 'Test Event',
+    'timestamp' => kind_of(Integer)
+  )
+end
+
+# After
+test "track sends event with correct payload" do
+  Mbuzz.track(
+    user_id: 1,
+    event_type: 'Test Event',
+    properties: { foo: 'bar' }
+  )
+
+  assert_requested :post, "#{base_url}/events", body: hash_including(
+    'event_type' => 'Test Event',
+    'timestamp' => match(/\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z/)  # ISO8601
+  )
+end
+```
+
+---
+
+### Step 4: Update README.md
+
+**Find and replace ALL examples**:
+
+```ruby
+# Before (v0.1.0)
+Mbuzz.track(
+  user_id: current_user.id,
+  event: 'Signup',
+  properties: { plan: 'pro' }
+)
+
+# After (v0.2.0)
+Mbuzz.track(
+  user_id: current_user.id,
+  event_type: 'Signup',
+  properties: { plan: 'pro' }
+)
+```
+
+**Add Migration Section**:
+```markdown
+## Upgrading from v0.1.x to v0.2.0
+
+⚠️ **Breaking Changes**
+
+v0.2.0 fixes critical bugs that prevent events from being tracked. You MUST update your code.
+
+### 1. Rename `event:` parameter to `event_type:`
+
+```ruby
+# Before
+Mbuzz.track(event: 'Signup', user_id: 1)
+
+# After
+Mbuzz.track(event_type: 'Signup', user_id: 1)
+```
+
+### 2. No action required for timestamps
+
+The gem now automatically sends timestamps in the correct format (ISO8601). If you were manually setting timestamps, ensure they're ISO8601 strings:
+
+```ruby
+# Good - ISO8601 string
+Mbuzz.track(event_type: 'Signup', timestamp: '2025-11-25T10:30:00Z')
+
+# Bad - Unix epoch (no longer supported)
+Mbuzz.track(event_type: 'Signup', timestamp: 1732550400)
+```
+
+### Find and Replace
+
+Search your codebase for:
+```
+Mbuzz.track\(
+  (.*?)event: '
+```
+
+Replace with:
+```
+Mbuzz.track(
+  $1event_type: '
+```
+```
+
+---
+
+### Step 5: Update SPECIFICATION.md
+
+**Changes**:
+1. Find/replace `anonymous_id` → `visitor_id`
+2. Update timestamp documentation to show ISO8601
+3. Update parameter name `event` → `event_type`
+
+**Example updates**:
+```markdown
+# Before
+- event (required) - The name of the event
+- timestamp (optional) - Unix timestamp of when the event occurred
+
+# After
+- event_type (required) - The name of the event
+- timestamp (optional) - ISO8601 timestamp of when the event occurred (defaults to now)
+
+## Example
+
+```ruby
+Mbuzz.track(
+  user_id: 1,
+  event_type: 'Purchase Completed',  # Changed from 'event'
+  properties: {
+    order_id: 'order_123',
+    amount: 99.99
+  },
+  timestamp: '2025-11-25T10:30:00Z'  # ISO8601 format
+)
+```
+```
+
+---
+
+### Step 6: Update Gemspec Version
+
+**File**: `mbuzz.gemspec`
+
+```ruby
+Gem::Specification.new do |spec|
+  spec.name = "mbuzz"
+  spec.version = "0.2.0"  # Bump from 0.1.0
+  spec.summary = "Multi-touch attribution for Ruby applications"
+  spec.description = "Server-side event tracking with automatic visitor and session management. v0.2.0 includes breaking changes - see CHANGELOG.md"
+  # ...
+end
+```
+
+---
+
+### Step 7: Create CHANGELOG.md
+
+**File**: `CHANGELOG.md`
+
+```markdown
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2025-11-26
+
+### ⚠️ BREAKING CHANGES
+
+This release fixes critical bugs that prevented events from being tracked. You MUST update your code to use this version.
+
+### Changed
+
+- **BREAKING**: Renamed `event:` parameter to `event_type:` to match backend API (#1)
+  - Before: `Mbuzz.track(event: 'Signup', user_id: 1)`
+  - After: `Mbuzz.track(event_type: 'Signup', user_id: 1)`
+  - Migration: Search/replace `event:` → `event_type:` in all `Mbuzz.track()` calls
+
+- **BREAKING**: Changed timestamp format from Unix epoch to ISO8601 (#2)
+  - Before: Sent `1732550400` (integer)
+  - After: Sends `"2025-11-25T10:30:00Z"` (ISO8601 string)
+  - Migration: No action required - gem handles this automatically
+
+### Fixed
+
+- Events are now correctly formatted and accepted by backend
+- Timestamps are now in UTC with ISO8601 format
+- Documentation now correctly refers to `visitor_id` instead of `anonymous_id`
+
+### Documentation
+
+- Updated README.md with new parameter names
+- Updated SPECIFICATION.md with correct parameter names and formats
+- Added migration guide for v0.1.x → v0.2.0
+
+## [0.1.0] - 2025-11-XX
+
+### Added
+
+- Initial release
+- Event tracking with `Mbuzz.track()`
+- Automatic visitor and session management
+- Rails middleware for automatic page view tracking
+- Rack middleware support
+
+---
+
+## [Unreleased]
+
+### Planned for v0.3.0
+
+- User identification with `Mbuzz.identify()`
+- Visitor aliasing with `Mbuzz.alias()`
+- Batch event sending
+- Offline queueing
+
+[0.2.0]: https://github.com/multibuzz/mbuzz-ruby/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/multibuzz/mbuzz-ruby/releases/tag/v0.1.0
+```
+
+---
+
+## Testing Checklist
+
+### Unit Tests
+
+- [ ] All existing tests pass with new parameter names
+- [ ] Test timestamp format is ISO8601
+- [ ] Test that `event_type` is sent in payload
+- [ ] Test that `event` parameter is NOT in payload
+- [ ] Test visitor_id is correctly included
+- [ ] Test properties are correctly merged
+
+### Integration Tests (Against Backend)
+
+- [ ] Create new test Rails app
+- [ ] Install gem from local source: `gem 'mbuzz', path: '../mbuzz-ruby'`
+- [ ] Configure with test API key
+- [ ] Track event with `event_type:` parameter
+- [ ] Verify event appears in backend (check logs or database)
+- [ ] Verify timestamp is stored correctly
+- [ ] Test with missing `timestamp` (should default to now)
+- [ ] Test with custom `timestamp` (ISO8601 string)
+
+### Manual Testing
+
+```bash
+# In test app console
+rails console
+
+# Track an event
+Mbuzz.track(
+  user_id: 1,
+  event_type: 'Test Event',
+  properties: { source: 'rails_console' }
+)
+
+# Check what was sent (enable debug mode)
+Mbuzz.configure do |config|
+  config.debug = true
+end
+
+Mbuzz.track(event_type: 'Debug Test', user_id: 1)
+# Should see request body with event_type and ISO8601 timestamp
+```
+
+---
+
+## Release Process
+
+### Pre-Release
+
+1. [ ] Complete all code changes
+2. [ ] Update all documentation
+3. [ ] All tests pass locally
+4. [ ] Manual testing complete
+5. [ ] CHANGELOG.md updated
+6. [ ] README.md migration guide added
+7. [ ] Version bumped to 0.2.0 in gemspec
+
+### Release
+
+1. [ ] Create git tag: `git tag -a v0.2.0 -m "Release v0.2.0 - Breaking changes"`
+2. [ ] Push tag: `git push origin v0.2.0`
+3. [ ] Build gem: `gem build mbuzz.gemspec`
+4. [ ] Publish to RubyGems: `gem push mbuzz-0.2.0.gem`
+5. [ ] Create GitHub release with changelog
+6. [ ] Announce breaking changes to users (email/blog/Discord)
+
+### Post-Release
+
+1. [ ] Update backend docs (mbuzz.co) to reference v0.2.0
+2. [ ] Update getting started guide with new examples
+3. [ ] Monitor for issues in first 48 hours
+4. [ ] Respond to user migration questions
+
+---
+
+## User Communication Template
+
+**Subject**: mbuzz-ruby v0.2.0 Released - Breaking Changes Required
+
+**Body**:
+```
+Hi mbuzz users,
+
+We've released v0.2.0 of the mbuzz-ruby gem with critical bug fixes. This release includes breaking changes that require you to update your code.
+
+⚠️ What's broken?
+
+v0.1.0 sends incorrectly formatted data that is rejected by the backend. No events are being tracked with v0.1.0.
+
+✅ What's fixed?
+
+v0.2.0 fixes the parameter names and timestamp format to match the backend API. Events will now be tracked correctly.
+
+🔧 How to upgrade:
+
+1. Update your Gemfile:
+   gem 'mbuzz', '~> 0.2.0'
+
+2. Run bundle update:
+   bundle update mbuzz
+
+3. Find and replace in your codebase:
+   - Change: Mbuzz.track(event: 'Name', ...)
+   - To: Mbuzz.track(event_type: 'Name', ...)
+
+That's it! The gem handles everything else automatically.
+
+📖 Full migration guide:
+https://github.com/multibuzz/mbuzz-ruby#upgrading-from-v01x-to-v020
+
+Questions? Reply to this email or open a GitHub issue.
+
+Thanks for using mbuzz!
+```
+
+---
+
+## Success Criteria
+
+- [ ] Gem v0.2.0 published to RubyGems
+- [ ] All parameter names match backend API exactly
+- [ ] Timestamps are ISO8601 format
+- [ ] All tests pass
+- [ ] Documentation updated
+- [ ] Migration guide available
+- [ ] Backend successfully accepts events from gem
+- [ ] No breaking changes for users who follow migration guide
+
+---
+
+## Related Documentation
+
+- Backend API Contract: `multibuzz/lib/docs/sdk/api_contract.md`
+- Backend Bug Spec: `multibuzz/lib/specs/bug_fixes_critical_inconsistencies.md`
+- SDK Registry: `multibuzz/lib/docs/sdk/sdk_registry.md`