0
# Version Management
1

2
Version handling system for ensuring compatibility between different Kotlin compiler versions and metadata formats. The version management system ensures that metadata can be read and written correctly across different Kotlin compiler versions.
3

4
## Capabilities
5

6
### JvmMetadataVersion Class
7

8
Represents a version for JVM metadata with major, minor, and patch components.
9

10
```kotlin { .api }
11
/**
12
 * Represents a version for JVM metadata
13
 * @param major Major version number
14
 * @param minor Minor version number  
15
 * @param patch Patch version number (defaults to 0)
16
 */
17
class JvmMetadataVersion(
18
    val major: Int, 
19
    val minor: Int, 
20
    val patch: Int = 0
21
) : Comparable<JvmMetadataVersion> {
22
    companion object {
23
        /** Latest stable supported metadata version */
24
        val LATEST_STABLE_SUPPORTED: JvmMetadataVersion
25
        
26
        /** Highest metadata version allowed for writing */
27
        val HIGHEST_ALLOWED_TO_WRITE: JvmMetadataVersion
28
    }
29
}
30
```
31

32
### Constructors
33

34
Multiple constructor options for creating version instances.
35

36
```kotlin { .api }
37
/**
38
 * Primary constructor with all version components
39
 * @param major Major version number
40
 * @param minor Minor version number
41
 * @param patch Patch version number
42
 */
43
constructor(major: Int, minor: Int, patch: Int)
44

45
/**
46
 * Secondary constructor with patch defaulting to 0
47
 * @param major Major version number
48
 * @param minor Minor version number
49
 */
50
constructor(major: Int, minor: Int)
51
```
52

53
**Usage Examples:**
54

55
```kotlin
56
import kotlin.metadata.jvm.JvmMetadataVersion
57

58
// Create version with all components
59
val version1 = JvmMetadataVersion(1, 6, 0)
60

61
// Create version with patch defaulting to 0
62
val version2 = JvmMetadataVersion(1, 7)
63

64
// Access version properties
65
println("Major: ${version1.major}")
66
println("Minor: ${version1.minor}")  
67
println("Patch: ${version1.patch}")
68
println("Version string: ${version1}")
69
```
70

71
### Version Comparison
72

73
Version comparison and equality operations.
74

75
```kotlin { .api }
76
/**
77
 * Compares this version with another version
78
 * @param other The version to compare against
79
 * @return Negative value if this < other, 0 if equal, positive if this > other
80
 */
81
override fun compareTo(other: JvmMetadataVersion): Int
82

83
/**
84
 * Returns string representation of the version
85
 * @return String in format "major.minor.patch"
86
 */
87
override fun toString(): String
88

89
/**
90
 * Calculates hash code for the version
91
 * @return Hash code based on major, minor, and patch values
92
 */
93
override fun hashCode(): Int
94

95
/**
96
 * Checks equality with another object
97
 * @param other Object to compare against
98
 * @return true if other is JvmMetadataVersion with same major, minor, patch
99
 */
100
override fun equals(other: Any?): Boolean
101
```
102

103
**Usage Examples:**
104

105
```kotlin
106
val version1 = JvmMetadataVersion(1, 6, 0)
107
val version2 = JvmMetadataVersion(1, 7, 0)
108
val version3 = JvmMetadataVersion(1, 6, 0)
109

110
// Version comparison
111
println(version1 < version2)  // true
112
println(version1 > version2)  // false
113
println(version1 == version3) // true
114

115
// Sorting versions
116
val versions = listOf(
117
    JvmMetadataVersion(1, 8, 0),
118
    JvmMetadataVersion(1, 6, 0), 
119
    JvmMetadataVersion(1, 7, 0)
120
)
121
val sortedVersions = versions.sorted()
122
println(sortedVersions) // [1.6.0, 1.7.0, 1.8.0]
123

124
// String representation
125
println(version1.toString()) // "1.6.0"
126
```
127

128
### Version Constants
129

130
Pre-defined version constants for common use cases.
131

132
```kotlin { .api }
133
companion object {
134
    /**
135
     * Latest stable supported version for reading metadata
136
     * This represents the highest version that can be reliably read
137
     */
138
    val LATEST_STABLE_SUPPORTED: JvmMetadataVersion
139
    
140
    /**
141
     * Highest version allowed for writing metadata
142
     * Writing metadata with versions higher than this may cause compatibility issues
143
     */
144
    val HIGHEST_ALLOWED_TO_WRITE: JvmMetadataVersion
145
}
146
```
147

148
**Usage Examples:**
149

150
```kotlin
151
// Check version compatibility
152
val currentVersion = JvmMetadataVersion(1, 6, 0)
153

154
if (currentVersion <= JvmMetadataVersion.LATEST_STABLE_SUPPORTED) {
155
    println("Version is supported for reading")
156
}
157

158
if (currentVersion <= JvmMetadataVersion.HIGHEST_ALLOWED_TO_WRITE) {
159
    println("Version is safe for writing")
160
}
161

162
// Use in metadata operations
163
val moduleMetadata = KotlinModuleMetadata(
164
    kmModule = module,
165
    version = JvmMetadataVersion.LATEST_STABLE_SUPPORTED
166
)
167
```
168

169
### Version Compatibility
170

171
Understanding and handling version compatibility in metadata operations.
172

173
```kotlin
174
// Version compatibility checking
175
fun isCompatibleForReading(version: JvmMetadataVersion): Boolean {
176
    return version <= JvmMetadataVersion.LATEST_STABLE_SUPPORTED
177
}
178

179
fun isCompatibleForWriting(version: JvmMetadataVersion): Boolean {
180
    return version <= JvmMetadataVersion.HIGHEST_ALLOWED_TO_WRITE
181
}
182

183
// Example usage in metadata reading
184
val metadataVersion = JvmMetadataVersion(1, 8, 0)
185
val metadata = if (isCompatibleForReading(metadataVersion)) {
186
    KotlinClassMetadata.readStrict(annotationData)
187
} else {
188
    // Fall back to lenient reading for newer versions
189
    KotlinClassMetadata.readLenient(annotationData)
190
}
191
```
192

193
### Working with Metadata Versions
194

195
Practical examples of version handling in metadata operations.
196

197
```kotlin
198
// Extract version from existing metadata
199
when (val metadata = KotlinClassMetadata.readLenient(annotationData)) {
200
    is KotlinClassMetadata.Class -> {
201
        val version = metadata.version
202
        println("Class metadata version: $version")
203
        
204
        // Check if version supports certain features
205
        if (version >= JvmMetadataVersion(1, 6)) {
206
            // Version 1.6+ features available
207
        }
208
    }
209
}
210

211
// Create metadata with specific version
212
val targetVersion = JvmMetadataVersion(1, 6, 0)
213
val moduleMetadata = KotlinModuleMetadata(
214
    kmModule = createModule(),
215
    version = targetVersion
216
)
217

218
// Version-aware metadata transformation
219
KotlinClassMetadata.transform(originalMetadata) { metadata ->
220
    // Ensure we don't exceed supported versions
221
    if (metadata.version <= JvmMetadataVersion.HIGHEST_ALLOWED_TO_WRITE) {
222
        // Safe to modify
223
        when (metadata) {
224
            is KotlinClassMetadata.Class -> {
225
                // Modify class metadata
226
            }
227
        }
228
    }
229
}
230
```
231

232
## Version Evolution
233

234
Kotlin metadata versions typically follow the Kotlin compiler version scheme:
235
- Major version increases indicate significant format changes
236
- Minor version increases may add new features or metadata fields
237
- Patch versions typically contain bug fixes without format changes
238

239
Understanding version compatibility is crucial for:
240
- Reading metadata from different Kotlin compiler versions
241
- Ensuring written metadata is compatible with target environments
242
- Handling forward and backward compatibility scenarios