@capillarytech/react-native-hydra-lib 1.7.0-beta.1

package/MIGRATION.md

@@ -0,0 +1,361 @@
+# Migration Guide
+
+This guide helps you migrate between major versions of `@capillary/react-native-hydra-lib` and handle deprecated features.
+
+## Table of Contents
+
+- [General Migration Guidelines](#general-migration-guidelines)
+- [Version-Specific Migrations](#version-specific-migrations)
+- [Breaking Changes](#breaking-changes)
+- [Deprecated Features](#deprecated-features)
+- [Common Migration Patterns](#common-migration-patterns)
+- [Troubleshooting](#troubleshooting)
+
+## General Migration Guidelines
+
+### Before You Start
+
+1. **Review the Changelog**: Check [CHANGELOG.md](./CHANGELOG.md) for all changes
+2. **Update Dependencies**: Ensure your React Native version is compatible
+3. **Backup Your Code**: Create a backup or commit your current working state
+4. **Test Environment**: Perform migration in a development environment first
+
+### Migration Process
+
+1. **Update Package**: Install the new version
+2. **Address Deprecations**: Fix any deprecation warnings from the previous version
+3. **Update Code**: Apply breaking changes documented in this guide
+4. **Test Thoroughly**: Run comprehensive tests on both platforms
+5. **Update Documentation**: Update any internal documentation
+
+## Version-Specific Migrations
+
+### Migrating to v2.0.0 (Future Release)
+
+> **Note**: This is a future release. Current version is 1.3.0.
+
+When v2.0.0 is released, it will include:
+
+#### Breaking Changes (Planned)
+
+- Minimum React Native version: 0.72.0+
+- Minimum iOS version: 13.0+
+- Minimum Android API: 23 (Android 6.0)+
+
+#### API Changes (Planned)
+
+```typescript
+// v1.x (Current)
+import { HydraLib } from '@capillary/react-native-hydra-lib';
+
+await HydraLib.init({
+  apiKey: 'your-key',
+  debug: true
+});
+
+// v2.x (Future)
+import { HydraLib } from '@capillary/react-native-hydra-lib';
+
+await HydraLib.initialize({
+  apiKey: 'your-key',
+  logLevel: 'debug' // 'none' | 'error' | 'warn' | 'info' | 'debug'
+});
+```
+
+### Migrating from v1.2.x to v1.3.0
+
+#### New Features
+
+✅ **SBOM Generation**: Automatic Software Bill of Materials generation
+✅ **Enhanced TypeScript Support**: Improved type definitions
+✅ **Better Error Handling**: More descriptive error messages
+
+#### Changes Required
+
+No breaking changes in this version. All existing code continues to work.
+
+#### Optional Enhancements
+
+```typescript
+// Enhanced error handling (recommended)
+try {
+  await HydraLib.initialize(config);
+} catch (error) {
+  if (error instanceof HydraError) {
+    console.error('Hydra SDK Error:', error.code, error.message);
+  } else {
+    console.error('Unexpected error:', error);
+  }
+}
+```
+
+## Breaking Changes
+
+### Current Deprecations
+
+> **Note**: Currently, there are no active deprecations in this library.
+
+As features are deprecated, they will be listed here with migration instructions.
+
+### Handling Breaking Changes
+
+When breaking changes are introduced:
+
+1. **Deprecation Warnings**: Watch for warnings in development
+2. **Migration Timeline**: Allow 6-12 months for migration
+3. **Parallel Support**: Use new APIs alongside deprecated ones during transition
+4. **Testing**: Thoroughly test new implementations
+
+## Deprecated Features
+
+### Example: Migrating from Deprecated Method
+
+When we deprecate features, the migration pattern will look like this:
+
+#### Before (Deprecated)
+```typescript
+// This is how deprecated features will be marked
+/**
+ * @deprecated Use newMethod() instead. Will be removed in v2.0.0.
+ */
+await HydraLib.oldMethod(param);
+```
+
+#### After (Recommended)
+```typescript
+// This is how you should migrate
+await HydraLib.newMethod(param);
+```
+
+### Configuration Migrations
+
+#### Before (Deprecated Properties)
+```typescript
+const config = {
+  apiUrl: 'https://api.example.com', // deprecated
+  debug: true, // deprecated
+};
+```
+
+#### After (New Properties)
+```typescript
+const config = {
+  apiEndpoint: 'https://api.example.com', // new
+  logLevel: 'debug', // new
+};
+```
+
+## Common Migration Patterns
+
+### 1. Configuration Object Changes
+
+```typescript
+// Pattern for configuration migrations
+const legacyConfig = {
+  apiUrl: 'https://api.example.com',
+  debug: true,
+  timeout: 5000,
+};
+
+// Convert to new format
+const newConfig = {
+  apiEndpoint: legacyConfig.apiUrl,
+  logLevel: legacyConfig.debug ? 'debug' : 'none',
+  timeout: legacyConfig.timeout,
+};
+```
+
+### 2. Method Signature Changes
+
+```typescript
+// Old method signature
+await HydraLib.trackEvent('event_name', { prop: 'value' });
+
+// New method signature (example)
+await HydraLib.analytics.track({
+  event: 'event_name',
+  properties: { prop: 'value' },
+  timestamp: Date.now(),
+});
+```
+
+### 3. Callback to Promise Migration
+
+```typescript
+// Old callback-based API
+HydraLib.getData((error, data) => {
+  if (error) {
+    console.error(error);
+  } else {
+    console.log(data);
+  }
+});
+
+// New Promise-based API
+try {
+  const data = await HydraLib.getData();
+  console.log(data);
+} catch (error) {
+  console.error(error);
+}
+```
+
+## Platform-Specific Migrations
+
+### iOS Migrations
+
+#### Podfile Changes
+
+```ruby
+# If you need to update your Podfile
+target 'YourApp' do
+  # Update minimum iOS version if required
+  platform :ios, '12.0'
+  
+  # Add any new pod dependencies
+  pod 'HydraSDK', '~> 2.0'
+end
+```
+
+#### Info.plist Updates
+
+```xml
+<!-- Add new permissions if required -->
+<key>NSLocationWhenInUseUsageDescription</key>
+<string>This app uses location for personalized content</string>
+```
+
+### Android Migrations
+
+#### Gradle Changes
+
+```gradle
+// android/app/build.gradle
+android {
+    compileSdkVersion 34
+    
+    defaultConfig {
+        minSdkVersion 21 // Update if minimum version changes
+        targetSdkVersion 34
+    }
+}
+```
+
+#### Manifest Updates
+
+```xml
+<!-- Add new permissions if required -->
+<uses-permission android:name="android.permission.NEW_PERMISSION" />
+```
+
+## Automated Migration Tools
+
+### Codemods (Future)
+
+We plan to provide automated migration tools for major version updates:
+
+```bash
+# Example: Future codemod for v2.0.0 migration
+npx @capillary/react-native-hydra-lib-codemod v1-to-v2 src/
+```
+
+### ESLint Rules (Future)
+
+Custom ESLint rules to catch deprecated API usage:
+
+```json
+{
+  "rules": {
+    "@capillary/hydra-lib/no-deprecated-apis": "error"
+  }
+}
+```
+
+## Troubleshooting
+
+### Common Migration Issues
+
+#### Issue: TypeScript Errors After Update
+
+```bash
+# Solution: Clear TypeScript cache and rebuild
+rm -rf node_modules/@types
+npm install
+npx tsc --build --clean
+npm run prepare
+```
+
+#### Issue: Native Module Not Found
+
+```bash
+# iOS Solution
+cd ios
+rm -rf Pods Podfile.lock
+pod install
+
+# Android Solution
+cd android
+./gradlew clean
+cd ..
+```
+
+#### Issue: Runtime Crashes After Migration
+
+1. **Check Version Compatibility**: Ensure React Native version is supported
+2. **Verify Native Setup**: Check iOS/Android specific setup
+3. **Review Breaking Changes**: Ensure all breaking changes are addressed
+4. **Check Logs**: Look for specific error messages in device logs
+
+### Getting Help
+
+If you encounter issues during migration:
+
+1. **Check This Guide**: Review relevant sections above
+2. **Search Issues**: Look for similar problems in [GitHub Issues](https://github.com/Capillary/react-native-hydra-lib/issues)
+3. **Create Issue**: If problem persists, create a detailed issue report
+4. **Community Support**: Ask questions in [GitHub Discussions](https://github.com/Capillary/react-native-hydra-lib/discussions)
+
+### Issue Template
+
+When reporting migration issues, include:
+
+```
+**Migration Version**: From X.X.X to Y.Y.Y
+**Platform**: iOS/Android/Both
+**React Native Version**: 0.XX.X
+**Error Message**: [Full error message]
+**Steps to Reproduce**: [Detailed steps]
+**Expected Behavior**: [What should happen]
+**Actual Behavior**: [What actually happens]
+```
+
+## Migration Checklist
+
+### Pre-Migration
+- [ ] Review changelog and migration guide
+- [ ] Check React Native version compatibility
+- [ ] Backup current codebase
+- [ ] Create test environment
+
+### During Migration
+- [ ] Update package version
+- [ ] Address deprecation warnings
+- [ ] Apply breaking changes
+- [ ] Update platform-specific configurations
+- [ ] Update documentation
+
+### Post-Migration
+- [ ] Run comprehensive tests
+- [ ] Test on both iOS and Android
+- [ ] Verify all features work correctly
+- [ ] Update CI/CD pipelines if needed
+- [ ] Deploy to staging environment
+- [ ] Monitor for issues
+
+---
+
+**Need Help?** If you have questions about migration, please:
+- Check our [Documentation](./README.md)
+- Search [GitHub Issues](https://github.com/Capillary/react-native-hydra-lib/issues)
+- Join [GitHub Discussions](https://github.com/Capillary/react-native-hydra-lib/discussions)
+- Contact support: [rakesh.ostwal@capillarytech.com](mailto:rakesh.ostwal@capillarytech.com)