0
# Version Management
1

2
Version policies, bumping strategies, and coordinated publishing across monorepo projects.
3

4
**Note**: All APIs in this document are re-exported from @microsoft/rush-lib through @rushstack/rush-sdk.
5

6
## Capabilities
7

8
### Version Policies
9

10
Base version policy system for managing coordinated versioning across monorepo projects.
11

12
```typescript { .api }
13
/**
14
 * Base class for version policies that coordinate versioning across projects
15
 */
16
abstract class VersionPolicy {
17
  /** Policy name from configuration */
18
  readonly policyName: string;
19
  
20
  /** Type of version policy */
21
  readonly definitionName: VersionPolicyDefinitionName;
22
  
23
  /** Projects associated with this policy */
24
  readonly associatedProjects: ReadonlyArray<RushConfigurationProject>;
25
  
26
  /** Validate that all projects follow the policy */
27
  abstract validate(terminal: ITerminal): void;
28
  
29
  /** Update project versions according to policy */
30
  abstract bump(bumpType?: BumpType, identifier?: string): void;
31
  
32
  /** Check if projects are in sync with policy */
33
  abstract isProjectInSync(project: RushConfigurationProject): boolean;
34
  
35
  /** Get the next version for a project */
36
  abstract getVersionString(project: RushConfigurationProject): string;
37
}
38

39
/**
40
 * Version policy type enumeration
41
 */
42
enum VersionPolicyDefinitionName {
43
  lockStepVersion = "lockStepVersion",
44
  individualVersion = "individualVersion"
45
}
46

47
/**
48
 * Version bump type enumeration
49
 */
50
enum BumpType {
51
  prerelease = "prerelease",
52
  patch = "patch",
53
  minor = "minor", 
54
  major = "major"
55
}
56
```
57

58
### Individual Version Policy
59

60
Version policy where each project manages its own independent version.
61

62
```typescript { .api }
63
/**
64
 * Version policy where each project maintains its own version independently
65
 */
66
class IndividualVersionPolicy extends VersionPolicy {
67
  /** Optional locked major version */
68
  readonly lockedMajor?: number;
69
  
70
  /** Validate individual project versions */
71
  validate(terminal: ITerminal): void;
72
  
73
  /** Bump individual project version */
74
  bump(bumpType?: BumpType, identifier?: string): void;
75
  
76
  /** Check if project version is valid */
77
  isProjectInSync(project: RushConfigurationProject): boolean;
78
  
79
  /** Get current version for project */
80
  getVersionString(project: RushConfigurationProject): string;
81
}
82
```
83

84
**Usage Examples:**
85

86
```typescript
87
import { IndividualVersionPolicy, BumpType } from "@rushstack/rush-sdk";
88

89
// Typically accessed through VersionPolicyConfiguration
90
const versionPolicy = config.versionPolicyConfiguration
91
  .getVersionPolicy("my-individual-policy") as IndividualVersionPolicy;
92

93
// Check locked major version
94
if (versionPolicy.lockedMajor !== undefined) {
95
  console.log(`Locked to major version: ${versionPolicy.lockedMajor}`);
96
}
97

98
// Validate all projects follow the policy
99
versionPolicy.validate(terminal);
100

101
// Check specific project
102
const project = config.projectsByName.get("@mycompany/my-package");
103
if (project) {
104
  const inSync = versionPolicy.isProjectInSync(project);
105
  console.log(`Project in sync: ${inSync}`);
106
  
107
  const currentVersion = versionPolicy.getVersionString(project);
108
  console.log(`Current version: ${currentVersion}`);
109
}
110

111
// Bump version (typically done by rush version command)
112
versionPolicy.bump(BumpType.minor);
113
```
114

115
### Lock-Step Version Policy
116

117
Version policy where all projects share the same version and are bumped together.
118

119
```typescript { .api }
120
/**
121
 * Version policy where all associated projects share the same version
122
 */
123
class LockStepVersionPolicy extends VersionPolicy {
124
  /** Current shared version */
125
  readonly version: string;
126
  
127
  /** Next bump type to apply */
128
  readonly nextBump?: BumpType;
129
  
130
  /** Main project that drives the version */
131
  readonly mainProject?: RushConfigurationProject;
132
  
133
  /** Validate all projects have same version */
134
  validate(terminal: ITerminal): void;
135
  
136
  /** Bump all projects to new version */
137
  bump(bumpType?: BumpType, identifier?: string): void;
138
  
139
  /** Check if project matches policy version */
140
  isProjectInSync(project: RushConfigurationProject): boolean;
141
  
142
  /** Get the shared version string */
143
  getVersionString(project: RushConfigurationProject): string;
144
  
145
  /** Update all projects to policy version */
146
  updateProjects(): void;
147
}
148
```
149

150
**Usage Examples:**
151

152
```typescript
153
import { LockStepVersionPolicy, BumpType } from "@rushstack/rush-sdk";
154

155
const lockStepPolicy = config.versionPolicyConfiguration
156
  .getVersionPolicy("my-lockstep-policy") as LockStepVersionPolicy;
157

158
// Check current shared version
159
console.log(`Shared version: ${lockStepPolicy.version}`);
160

161
if (lockStepPolicy.nextBump) {
162
  console.log(`Next bump: ${lockStepPolicy.nextBump}`);
163
}
164

165
// Validate all projects are in sync
166
lockStepPolicy.validate(terminal);
167

168
// Check if all projects have the correct version
169
for (const project of lockStepPolicy.associatedProjects) {
170
  const inSync = lockStepPolicy.isProjectInSync(project);
171
  console.log(`${project.packageName} in sync: ${inSync}`);
172
}
173

174
// Bump all projects together
175
lockStepPolicy.bump(BumpType.minor);
176

177
// Update all project package.json files
178
lockStepPolicy.updateProjects();
179
```
180

181
### Version Policy Configuration
182

183
Management and loading of version policies from Rush configuration.
184

185
```typescript { .api }
186
/**
187
 * Manages version policies defined in rush.json
188
 */
189
class VersionPolicyConfiguration {
190
  /** All configured version policies */
191
  readonly versionPolicies: ReadonlyArray<VersionPolicy>;
192
  
193
  /** Get version policy by name */
194
  getVersionPolicy(policyName: string): VersionPolicy | undefined;
195
  
196
  /** Try to get version policy by name */
197
  tryGetVersionPolicy(policyName: string): VersionPolicy | undefined;
198
  
199
  /** Get version policy for a specific project */
200
  getVersionPolicyForProject(project: RushConfigurationProject): VersionPolicy | undefined;
201
  
202
  /** Load version policies from configuration */
203
  static loadFromConfiguration(
204
    rushConfiguration: RushConfiguration
205
  ): VersionPolicyConfiguration;
206
  
207
  /** Validate all version policies */
208
  validate(terminal: ITerminal): void;
209
  
210
  /** Update all projects to match their policies */
211
  updateProjectVersions(): void;
212
}
213
```
214

215
**Usage Examples:**
216

217
```typescript
218
import { VersionPolicyConfiguration, RushConfiguration } from "@rushstack/rush-sdk";
219

220
const config = RushConfiguration.loadFromDefaultLocation();
221
const versionConfig = VersionPolicyConfiguration.loadFromConfiguration(config);
222

223
// List all version policies
224
console.log(`Found ${versionConfig.versionPolicies.length} version policies:`);
225
for (const policy of versionConfig.versionPolicies) {
226
  console.log(`  ${policy.policyName} (${policy.definitionName})`);
227
  console.log(`    Projects: ${policy.associatedProjects.length}`);
228
}
229

230
// Get specific policy
231
const myPolicy = versionConfig.getVersionPolicy("my-policy");
232
if (myPolicy) {
233
  console.log(`Policy type: ${myPolicy.definitionName}`);
234
}
235

236
// Get policy for specific project
237
const project = config.projectsByName.get("@mycompany/my-package");
238
if (project) {
239
  const policy = versionConfig.getVersionPolicyForProject(project);
240
  if (policy) {
241
    console.log(`Project uses policy: ${policy.policyName}`);
242
  } else {
243
    console.log("Project has no version policy");
244
  }
245
}
246

247
// Validate all policies
248
versionConfig.validate(terminal);
249

250
// Update all projects to match policies
251
versionConfig.updateProjectVersions();
252
```
253

254
### Version Utilities
255

256
Utility functions for version string manipulation and validation.
257

258
```typescript { .api }
259
/**
260
 * Utilities for working with semantic versions
261
 */
262
class SemVer {
263
  /** Parse version string */
264
  static parse(version: string): SemVer;
265
  
266
  /** Check if version string is valid */
267
  static isValid(version: string): boolean;
268
  
269
  /** Compare two versions */
270
  static compare(a: string, b: string): number;
271
  
272
  /** Major version number */
273
  readonly major: number;
274
  
275
  /** Minor version number */
276
  readonly minor: number;
277
  
278
  /** Patch version number */
279
  readonly patch: number;
280
  
281
  /** Prerelease identifier */
282
  readonly prerelease: ReadonlyArray<string | number>;
283
  
284
  /** Build metadata */
285
  readonly build: ReadonlyArray<string>;
286
  
287
  /** Increment version by bump type */
288
  inc(bumpType: BumpType, identifier?: string): SemVer;
289
  
290
  /** Convert to string */
291
  toString(): string;
292
  
293
  /** Check if satisfies range */
294
  satisfies(range: string): boolean;
295
}
296

297
/**
298
 * Version range utilities
299
 */
300
class VersionRange {
301
  /** Parse range string */  
302
  static parse(range: string): VersionRange;
303
  
304
  /** Check if version satisfies range */
305
  static satisfies(version: string, range: string): boolean;
306
  
307
  /** Get best matching version from array */
308
  static maxSatisfying(versions: string[], range: string): string | undefined;
309
}
310
```
311

312
**Usage Examples:**
313

314
```typescript
315
import { SemVer, VersionRange, BumpType } from "@rushstack/rush-sdk";
316

317
// Parse and manipulate versions
318
const version = SemVer.parse("1.2.3-beta.1");
319
console.log(`Major: ${version.major}`); // 1
320
console.log(`Minor: ${version.minor}`); // 2
321
console.log(`Patch: ${version.patch}`); // 3
322
console.log(`Prerelease: ${version.prerelease}`); // ["beta", 1]
323

324
// Increment version
325
const newVersion = version.inc(BumpType.minor);
326
console.log(`New version: ${newVersion.toString()}`); // "1.3.0"
327

328
// Version validation
329
const isValid = SemVer.isValid("1.2.3-alpha");
330
console.log(`Valid: ${isValid}`); // true
331

332
// Version comparison  
333
const comparison = SemVer.compare("1.2.3", "1.2.4");
334
console.log(`Comparison: ${comparison}`); // -1
335

336
// Range operations
337
const satisfies = VersionRange.satisfies("1.2.3", "^1.2.0");
338
console.log(`Satisfies: ${satisfies}`); // true
339

340
const best = VersionRange.maxSatisfying(
341
  ["1.2.0", "1.2.3", "1.3.0"], 
342
  "^1.2.0"
343
);
344
console.log(`Best match: ${best}`); // "1.2.3"
345
```