Skip to content

Commit 05a89a3

Browse files
wpinho-branchwpinho-branch
committed
Add version configuration and timeline documentation for Branch SDK
- Introduced comprehensive documentation for the Branch SDK's version configuration, detailing the management of API deprecation and removal timelines through external properties files. - Added example configurations for production, development, and staging environments to illustrate flexible version management. - Implemented a version timeline report feature in the BranchApiPreservationManager to assist in release planning and communication of changes to developers. - Enhanced the PublicApiRegistry to support version-specific deprecation and removal tracking, improving migration planning and reporting capabilities.
1 parent 74ef3b8 commit 05a89a3

File tree

8 files changed

+942
-57
lines changed

8 files changed

+942
-57
lines changed

‎Branch-SDK/docs/version-configuration.md‎

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
# Branch SDK Version Configuration
2+
3+
## Overview
4+
5+
The Branch SDK now supports configurable deprecation and removal timelines through external configuration files. This allows for flexible management of API lifecycle without requiring code changes.
6+
7+
## Configuration Files
8+
9+
### Location
10+
Configuration files should be placed in `src/main/assets/` directory:
11+
- `branch_version_config.properties` - Production configuration
12+
- `branch_version_config.development.properties` - Development configuration (example)
13+
14+
### Configuration Properties
15+
16+
| Property | Description | Example |
17+
|----------|-------------|---------|
18+
| `branch.api.deprecation.version` | Version when APIs are marked as deprecated | `5.0.0` |
19+
| `branch.api.removal.version` | Version when deprecated APIs will be removed | `6.0.0` |
20+
| `branch.migration.guide.url` | URL to migration documentation | `https://branch.io/migration-guide` |
21+
22+
### Example Configuration
23+
24+
```properties
25+
# Branch SDK Version Configuration
26+
branch.api.deprecation.version=5.0.0
27+
branch.api.removal.version=6.0.0
28+
branch.migration.guide.url=https://branch.io/migration-guide
29+
```
30+
31+
## Usage
32+
33+
### Initialization
34+
35+
The version configuration is automatically loaded when the `BranchApiPreservationManager` is initialized:
36+
37+
```kotlin
38+
val preservationManager = BranchApiPreservationManager.getInstance(context)
39+
```
40+
41+
### Accessing Configuration
42+
43+
```kotlin
44+
val versionConfig = VersionConfigurationFactory.createConfiguration(context)
45+
val deprecationVersion = versionConfig.getDeprecationVersion()
46+
val removalVersion = versionConfig.getRemovalVersion()
47+
val migrationGuideUrl = versionConfig.getMigrationGuideUrl()
48+
```
49+
50+
### API-Specific Version Management
51+
52+
Each API can have its own deprecation and removal timeline:
53+
54+
```kotlin
55+
// Register API with specific versions
56+
publicApiRegistry.registerApi(
57+
methodName = "generateShortUrl",
58+
signature = "BranchUniversalObject.generateShortUrl()",
59+
usageImpact = UsageImpact.CRITICAL,
60+
complexity = MigrationComplexity.COMPLEX,
61+
removalTimeline = "Q4 2025",
62+
modernReplacement = "linkManager.createShortLink()",
63+
deprecationVersion = "5.0.0", // Specific deprecation version
64+
removalVersion = "7.0.0" // Extended removal due to complexity
65+
)
66+
67+
// Get APIs by version
68+
val apisToDeprecateIn5_0 = preservationManager.getApisForDeprecationInVersion("5.0.0")
69+
val apisToRemoveIn6_0 = preservationManager.getApisForRemovalInVersion("6.0.0")
70+
```
71+
72+
### Version Timeline Reports
73+
74+
Generate comprehensive reports for release planning:
75+
76+
```kotlin
77+
val timelineReport = preservationManager.generateVersionTimelineReport()
78+
79+
// Access timeline details
80+
timelineReport.versionDetails.forEach { versionDetail ->
81+
println("Version ${versionDetail.version}:")
82+
println(" - ${versionDetail.deprecatedApis.size} APIs deprecated")
83+
println(" - ${versionDetail.removedApis.size} APIs removed")
84+
println(" - Breaking changes: ${versionDetail.hasBreakingChanges}")
85+
}
86+
87+
// Access summary statistics
88+
val summary = timelineReport.summary
89+
println("Busiest version: ${summary.busiestVersion}")
90+
println("Max removals in single version: ${summary.maxRemovalsInSingleVersion}")
91+
```
92+
93+
## Architecture
94+
95+
### Components
96+
97+
1. **VersionConfiguration** - Interface for version configuration access
98+
2. **PropertiesVersionConfiguration** - Implementation that reads from properties files
99+
3. **VersionConfigurationFactory** - Factory for creating configuration instances
100+
4. **PublicApiRegistry** - Uses configuration for API metadata
101+
5. **BranchApiPreservationManager** - Coordinates configuration usage
102+
103+
### Benefits
104+
105+
- **Flexibility**: Change versions without code modifications
106+
- **Environment-specific**: Different configurations for dev/staging/prod
107+
- **Centralized**: Single source of truth for version information
108+
- **Thread-safe**: Singleton pattern with proper synchronization
109+
- **Fallback**: Default values when configuration file is missing
110+
111+
## Migration from Hardcoded Values
112+
113+
### Before
114+
```kotlin
115+
private const val DEPRECATION_VERSION = "5.0.0"
116+
private const val REMOVAL_VERSION = "6.0.0"
117+
```
118+
119+
### After
120+
```kotlin
121+
private val versionConfiguration: VersionConfiguration
122+
val deprecationVersion = versionConfiguration.getDeprecationVersion()
123+
val removalVersion = versionConfiguration.getRemovalVersion()
124+
```
125+
126+
## Version Strategy Examples
127+
128+
### Conservative Approach (High Stability)
129+
```kotlin
130+
// Critical APIs - Extended timeline
131+
deprecationVersion = "5.0.0"
132+
removalVersion = "7.0.0" // 2 major versions later
133+
134+
// High impact APIs - Standard timeline
135+
deprecationVersion = "5.0.0"
136+
removalVersion = "6.0.0" // 1 major version later
137+
```
138+
139+
### Aggressive Approach (Fast Modernization)
140+
```kotlin
141+
// Performance-critical APIs - Accelerated removal
142+
deprecationVersion = "4.0.0"
143+
removalVersion = "5.0.0" // Same major version
144+
145+
// Blocking APIs - Immediate removal
146+
deprecationVersion = "4.5.0"
147+
removalVersion = "5.0.0" // Next major version
148+
```
149+
150+
### Balanced Approach (Recommended)
151+
```kotlin
152+
// Categorize by impact and complexity:
153+
// - Critical + Complex: 5.0.0 → 7.0.0 (extended)
154+
// - High + Medium: 5.0.0 → 6.5.0 (standard+)
155+
// - Medium + Simple: 5.0.0 → 6.0.0 (standard)
156+
// - Low + Simple: 4.5.0 → 5.5.0 (accelerated)
157+
```
158+
159+
## Best Practices
160+
161+
1. **Version Consistency**: Ensure all environments use consistent versioning schemes
162+
2. **Impact-Based Scheduling**: Schedule based on usage impact and migration complexity
163+
3. **Documentation**: Update migration guides when versions change
164+
4. **Testing**: Test configuration loading in different scenarios
165+
5. **Validation**: Validate version format and logical consistency
166+
6. **Monitoring**: Track configuration loading success/failure
167+
7. **Timeline Communication**: Clearly communicate timelines to developers
168+
8. **Gradual Migration**: Provide overlapping support periods for smooth transitions
169+
170+
## Error Handling
171+
172+
The system gracefully handles configuration errors:
173+
- Missing files: Falls back to default values
174+
- Invalid format: Logs warning and uses defaults
175+
- Access errors: Handles IOException gracefully
176+
177+
## Future Enhancements
178+
179+
Planned improvements:
180+
- JSON configuration support
181+
- Remote configuration loading
182+
- Version validation rules
183+
- Configuration hot-reloading

0 commit comments

Comments
 (0)