Skip to content

CLAUDE.md

Latest commit

 

History

History
218 lines (164 loc) · 7.27 KB

CLAUDE.md

File metadata and controls

218 lines (164 loc) · 7.27 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Optimizely Flutter SDK - Cross-platform plugin wrapping native Optimizely SDKs (iOS, Android) for A/B testing, feature flags, CMAB, and ODP integration.

Main Branch: master

Essential Commands

# Setup
flutter pub get

# Testing
flutter test                       # All tests
flutter test test/cmab_test.dart   # Specific test
flutter test --coverage            # With coverage

# Linting
flutter analyze

# Run example app
cd example && flutter run

Architecture

Bridge Pattern

Dart API (OptimizelyFlutterSdk)
    ↓
Wrapper (OptimizelyClientWrapper) + MethodChannel
    ↓
Native Plugins (Swift/Java)
    ↓
Native Optimizely SDKs (check Package.swift/build.gradle for current versions)

Critical Patterns

1. Response Object Pattern

  • ALL methods return BaseResponse derivatives (never throw exceptions)
  • Check success boolean and reason string for errors

2. Multi-Instance State Management

  • SDK instances tracked by sdkKey
  • User contexts: sdkKey → userContextId → context
  • Notification listeners: sdkKey → listenerId → callback
  • Call close() for cleanup

3. Platform-Specific Type Encoding (CRITICAL)

  • iOS: Attributes need type metadata: {"value": 123, "type": "int"}
  • Android: Direct primitives: {"attribute": 123}
  • Conversion in Utils.convertToTypedMap() (lib/src/utils/utils.dart)
  • Test override: forceIOSFormat parameter

4. Dual MethodChannel Architecture

  • optimizely_flutter_sdk - Main API operations
  • optimizely_flutter_sdk_logger - Native → Dart log forwarding

Adding Cross-Platform Features

  1. Add data models in lib/src/data_objects/ if needed
  2. Update lib/src/optimizely_client_wrapper.dart with MethodChannel call
  3. Android: Add case in OptimizelyFlutterClient.java, parse args, call native SDK
  4. iOS: Add case in SwiftOptimizelyFlutterSdkPlugin.swift, parse args, call native SDK
  5. Handle type conversions (iOS requires metadata wrapping)
  6. Write tests in test/
  7. Update public API in lib/optimizely_flutter_sdk.dart

Version Management

Three locations must stay synchronized (SDK version):

  1. pubspec.yaml → version: X.Y.Z
  2. lib/package_info.dart → version = 'X.Y.Z'
  3. README.md → Installation example ^X.Y.Z

Native iOS SDK version lives in one place (SPM only):

  • ios/optimizely_flutter_sdk/Package.swift → .package(url: "...swift-sdk.git", exact: "A.B.C")

Release Workflow

With Claude Code (Recommended)

Simply ask Claude to create a release:

"Create release 3.4.2 with ticket FSSDK-12345"
"Bump patch version with ticket FSSDK-12345"

Claude will execute the full workflow:

  • ✅ Pre-flight checks (master branch, clean working tree)
  • ✅ Create release branch (prepare-X.Y.Z)
  • ✅ Update all 3 version files (pubspec.yaml, package_info.dart, README.md)
  • ✅ Generate CHANGELOG.md template
  • ✅ Commit and push
  • ✅ Create PR

After the release PR merges (automated)

  • release.yml validates the version (pubspec.yaml, package_info.dart, README.md, CHANGELOG section) on the PR, and on merge pushes tag vX.Y.Z
  • publish.yml runs on the tag: publishes to pub.dev (waits for approval in the pub.dev environment), then creates the GitHub release from the CHANGELOG section
  • Versions with a - suffix (e.g. 4.0.0-rc.1) are released as prereleases
  • If a workflow fails, use "Re-run failed jobs" in the Actions tab. A failed GitHub release step is retried without publishing again

Manual Release

# 1. Create release branch
git checkout -b prepare-X.Y.Z

# 2. Update versions (pubspec.yaml, package_info.dart, README.md)
# 3. Update CHANGELOG.md (add release notes at top)

# 4. Commit with standard format
git commit -m "chore: prepare for release X.Y.Z

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>"

# 5. Push and create PR
git push -u origin prepare-X.Y.Z
gh pr create --title "[FSSDK-XXXXX] prepare for release X.Y.Z"

# 6. After merge, the tag, pub.dev publish and GitHub release are automated (see above)

CHANGELOG Format

## X.Y.Z
Month Day, Year

### New Features / Enhancements / Bug Fixes
* Description ([#PR](link))

Contributing Guidelines

Project Constitution

All code changes MUST comply with the project constitution at .specify/memory/constitution.md. This document defines the team's non-negotiable standards for correctness, testing, security, observability, naming, PR discipline, and architectural simplicity.

When to consult the constitution:

  • Before implementing any feature (large or small)
  • During code reviews to validate adherence
  • When making architectural decisions
  • For day-to-day changes that don't require full SDD workflow

Read the constitution before proposing changes.

Commit Messages

Follow Angular guidelines:

  • feat: - New features
  • fix: - Bug fixes
  • chore: - Maintenance
  • docs: - Documentation
  • refactor: - Code restructuring
  • test: - Test additions

Branch Strategy

  • Never commit directly to master
  • Feature branches: feature/name, prepare-X.Y.Z, fix/name
  • All PRs target master branch

Requirements

  • Tests required for all code changes
  • All CI checks must pass (5 parallel workflows)
  • Apache 2.0 license header on new files
  • Sign CLA (Contributor License Agreement)

CI Pipeline

  • unit_test_coverage (macOS) - Dart tests + Coveralls upload
  • build_test_android (Ubuntu) - Android build validation
  • build_test_ios (macOS) - iOS build validation
  • integration_android_tests (Ubuntu) - Triggers optimizely-flutter-testapp repo
  • integration_ios_tests (Ubuntu) - Triggers optimizely-flutter-testapp repo

Platform Requirements

Flutter/Dart:

  • Dart: >=2.16.2 <4.0.0
  • Flutter: >=3.44.0

Android:

  • minSdk: 21 (Android 5.0)
  • compileSdk: 35 (Android 15)
  • Kotlin: 2.1.0
  • Native SDK: android-sdk (see android/build.gradle for current version)

iOS:

  • Minimum: iOS 15.0
  • Swift: 5.0
  • Native SDK: OptimizelySwiftSDK (see ios/optimizely_flutter_sdk/Package.swift for current version)

Key Implementation Files

Dart Layer:

  • lib/optimizely_flutter_sdk.dart - Public API (initialize, decide, track)
  • lib/src/optimizely_client_wrapper.dart - Platform bridge (545 LOC)
  • lib/src/user_context/optimizely_user_context.dart - User context operations
  • lib/src/data_objects/ - 21 response/request models

Android Layer:

  • android/src/.../OptimizelyFlutterSdkPlugin.java - MethodChannel handler
  • android/src/.../OptimizelyFlutterClient.java - Core client wrapper (921 LOC)
  • android/build.gradle - Dependencies & SDK versions

iOS Layer:

  • ios/optimizely_flutter_sdk/Sources/optimizely_flutter_sdk/SwiftOptimizelyFlutterSdkPlugin.swift - Plugin implementation (786 LOC)
  • ios/optimizely_flutter_sdk/Sources/optimizely_flutter_sdk/OptimizelyFlutterLogger.swift - Logger bridge (main-thread dispatch)
  • ios/optimizely_flutter_sdk/Package.swift - SPM dependencies

For additional context about technologies to be used, project structure, shell commands, and other important information, read the current plan