Skip to content

Commit dae9dfb

Browse files
fix(release): allocate collision-free beta versions
TICKET: WCN-3802
1 parent d2909f3 commit dae9dfb

13 files changed

Lines changed: 729 additions & 241 deletions

File tree

‎.github/workflows/publish.yml‎

Lines changed: 3 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,6 @@
11
name: Publish @bitgo-beta
22
on:
33
workflow_dispatch:
4-
inputs:
5-
recovery-mode:
6-
description: |
7-
Recover a stuck beta publish where sigstore/Rekor already logged
8-
provenance for a package's currently-computed version/tarball
9-
(registry write failed) but the package never landed on npm. When
10-
enabled, the publish step automatically detects the Rekor
11-
conflict per-package and bumps that package's version until it
12-
finds one that publishes cleanly - no manual input needed.
13-
type: boolean
14-
required: false
15-
default: false
164
# push:
175
# branches:
186
# - master
@@ -35,6 +23,9 @@ jobs:
3523
# a deployment branch policy on this environment, so the job cannot run
3624
# from arbitrary PR branches even though it is manually dispatched.
3725
environment: beta-alpha-release
26+
timeout-minutes: 180
27+
env:
28+
BITGO_PUBLISH_VISIBILITY_TIMEOUT_MINUTES: 120
3829

3930
steps:
4031
- uses: socketdev/action@4337a545deecc20f19a909e52db7a2f6ba292f42 # v1
@@ -105,15 +96,11 @@ jobs:
10596
run: git commit -am "Auto updated ${{ env.preid }} branch" --no-verify || echo "No changes to commit"
10697

10798
- name: Lerna Publish (siblings)
108-
# In recovery mode a stuck package's Rekor conflict fails this step outright; let it
109-
# continue so Verify Publish below still gets a chance to bump+retry that package.
110-
continue-on-error: ${{ inputs.recovery-mode }}
11199
run: yarn lerna publish from-package --preid ${{ env.preid }} --dist-tag ${{ env.preid }} --force-publish --yes --loglevel silly
112100
env:
113101
NPM_CONFIG_PROVENANCE: true
114102

115103
- name: Lerna Publish (bitgo)
116-
continue-on-error: ${{ inputs.recovery-mode }}
117104
run: |
118105
bitgo_name=$(jq -r '.name' modules/bitgo/package.json)
119106
yarn lerna publish from-package --include-private "$bitgo_name" --preid ${{ env.preid }} --dist-tag ${{ env.preid }} --force-publish --yes --loglevel silly
@@ -123,6 +110,3 @@ jobs:
123110

124111
- name: Verify Publish
125112
run: npx tsx ./scripts/verify-release.ts ${{ env.preid }}
126-
env:
127-
NPM_CONFIG_PROVENANCE: true
128-
RECOVERY_MODE: ${{ inputs.recovery-mode }}

‎docs/beta-release.md‎

Lines changed: 22 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -38,12 +38,15 @@ For each module, the script:
3838
- If a beta tag exists and its base version >= latest, use the beta tag as base
3939
- If the beta tag's base version < latest, start a new prerelease from latest
4040
- If no beta tag exists, create one from latest
41-
3. Computes the next version via `semver.inc(prevTag, 'prerelease', preid)`
41+
3. Computes a candidate via `semver.inc(prevTag, 'prerelease', preid)`
42+
4. Checks the exact package/version endpoint and keeps incrementing until the candidate is not already published
4243

4344
Example: `8.2.1-beta.1009` → `8.2.1-beta.1010`
4445

45-
The dist-tag fetch can be cached via `BITGO_PREPARE_RELEASE_CACHE_DIST_TAGS` env var pointing to a
46-
JSON file, avoiding repeated npm registry calls.
46+
The dist-tag fetch can be cached via `BITGO_PREPARE_RELEASE_CACHE_DIST_TAGS`. Tests can also set
47+
`BITGO_PREPARE_RELEASE_CACHE_PUBLISHED_VERSIONS` to a JSON object whose package-name keys contain
48+
arrays of occupied versions. Production releases do not use these caches; an unexpected registry
49+
response fails preparation instead of publishing a dependency graph with unverified versions.
4750

4851
Implementation: `scripts/prepareRelease/distTags.ts`
4952

@@ -71,21 +74,24 @@ Key behaviors to understand:
7174
- Each `@bitgo-beta` package has its own **independent prerelease counter** (e.g.,
7275
`sdk-core@8.2.1-beta.788`, `statics@15.1.1-beta.791`). There is no shared suffix —
7376
what ties a release together is the CI publish run.
74-
- The `beta` dist-tag on npm always points to the latest published prerelease for each package.
77+
- The `beta` dist-tag is the intended consumer entry point, but it can temporarily lag an immutable
78+
version while npm finishes processing a publish. Release verification waits for the exact
79+
version, tag, and npm provenance from the current GitHub Actions run.
7580
- Fetching dist-tags individually during a multi-package publish can yield inconsistent versions
7681
(a race condition): some packages may have the new version while others still show the old one.
7782
Use `--versions-file` with a CI-generated manifest to avoid this.
7883

7984
## Helper Modules (`scripts/prepareRelease/`)
8085

81-
| File | Purpose |
82-
|------|---------|
86+
| File | Purpose |
87+
| ---------------------- | --------------------------------------------------------------- |
8388
| `changeScopeInFile.ts` | Regex replacement of `@bitgo/*` → target scope in file contents |
84-
| `changePackageJson.ts` | Updates dependency versions in `package.json` objects |
85-
| `distTags.ts` | Fetches/caches npm dist-tags for all modules |
86-
| `getLernaModules.ts` | Runs `lerna list --json --all` to discover all modules |
87-
| `walk.ts` | Recursively walks directories, filtering by file extension |
88-
| `index.ts` | Barrel export |
89+
| `changePackageJson.ts` | Updates dependency versions in `package.json` objects |
90+
| `distTags.ts` | Fetches/caches npm dist-tags for all modules |
91+
| `getLernaModules.ts` | Runs `lerna list --json --all` to discover all modules |
92+
| `versionAllocation.ts` | Selects free versions and pins them into dependent manifests |
93+
| `walk.ts` | Recursively walks directories, filtering by file extension |
94+
| `index.ts` | Barrel export |
8995

9096
## Known Limitations
9197

@@ -96,7 +102,8 @@ Key behaviors to understand:
96102

97103
## Related Scripts
98104

99-
| Script | Purpose |
100-
|--------|---------|
101-
| `scripts/prepare-release.ts` | Main transformation script (this document) |
102-
| `@bitgo/beta-tools` (`modules/beta-tools`) | Canonical tool for consumers to bump `@bitgo-beta/*` versions |
105+
| Script | Purpose |
106+
| ------------------------------------------ | -------------------------------------------------------------------------------- |
107+
| `scripts/prepare-release.ts` | Main transformation script (this document) |
108+
| `scripts/verify-release.ts` | Read-only registry verification with bounded polling and fail-closed exit status |
109+
| `@bitgo/beta-tools` (`modules/beta-tools`) | Canonical tool for consumers to bump `@bitgo-beta/*` versions |

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -321,7 +321,7 @@
321321
"prepare-commit-msg": "node ./scripts/prepare-commit-msg.js",
322322
"test:prepare-release": "mocha --require tsx ./scripts/tests/prepareRelease/prepare-release-main.test.ts",
323323
"test:shrinkwrap": "mocha --require tsx ./scripts/tests/generate-bitgo-shrinkwrap.test.ts",
324-
"test:scripts": "mocha './scripts/tests/**/*.test.js'"
324+
"test:scripts": "mocha --require tsx './scripts/tests/**/*.test.js' './scripts/tests/verify-release.test.ts' './scripts/tests/prepareRelease/version-allocation.test.ts'"
325325
},
326326
"dependencies": {
327327
"axios": "1.20.0",

‎scripts/prepare-release.ts‎

Lines changed: 7 additions & 107 deletions
Original file line numberDiff line numberDiff line change
@@ -10,10 +10,8 @@
1010
*
1111
* Usage: npx tsx scripts/prepare-release.ts [preid] --scope [scope] --root-dir [dir]
1212
*/
13-
import assert from 'node:assert';
1413
import { readFileSync, writeFileSync } from 'fs';
1514
import path from 'path';
16-
import { inc, lt } from 'semver';
1715
import yargs from 'yargs';
1816
import { hideBin } from 'yargs/helpers';
1917

@@ -22,8 +20,7 @@ import {
2220
getDistTagsForModules,
2321
getLernaModules,
2422
changeScopeInFile,
25-
setDependencyVersion,
26-
DistTags,
23+
incrementVersionsForModuleLocation,
2724
LernaModule,
2825
} from './prepareRelease';
2926

@@ -60,95 +57,6 @@ function replaceBitGoPackageScope(rootDir: string, targetScope: string): void {
6057
);
6158
}
6259

63-
/**
64-
* Read package.json for a module
65-
* @param module The module to read package.json from
66-
* @returns The parsed package.json content
67-
*/
68-
function readModulePackageJson(module: LernaModule): any {
69-
return JSON.parse(
70-
readFileSync(path.join(module.location, 'package.json'), {
71-
encoding: 'utf-8',
72-
}),
73-
);
74-
}
75-
76-
/**
77-
* Write package.json for a module
78-
* @param module The module to write package.json to
79-
* @param json The content to write
80-
*/
81-
function writeModulePackageJson(module: LernaModule, json: any): void {
82-
writeFileSync(
83-
path.join(module.location, 'package.json'),
84-
JSON.stringify(json, null, 2) + '\n',
85-
);
86-
}
87-
88-
/**
89-
* Increment the version for a single module based on the preid.
90-
*
91-
* @param {String} preid - The prerelease identifier
92-
* @param {LernaModule} module - The module to update
93-
* @param {DistTags|undefined} tags - The dist tags for the module
94-
* @param {LernaModule[]} allModules - All modules for dependency updates
95-
* @returns {String|undefined} - The new version if set, undefined otherwise
96-
*/
97-
function incrementVersionsForModuleLocation(
98-
preid: string,
99-
module: LernaModule,
100-
tags: DistTags | undefined,
101-
allModules: LernaModule[],
102-
): string | undefined {
103-
const json = readModulePackageJson(module);
104-
105-
let prevTag: string | undefined = undefined;
106-
107-
if (tags) {
108-
if (tags[preid]) {
109-
const version = tags[preid].split('-');
110-
const latest = tags?.latest?.split('-') ?? ['0.0.0'];
111-
prevTag = lt(version[0], latest[0])
112-
? `${tags.latest}-${preid}`
113-
: tags[preid];
114-
} else {
115-
prevTag = `${tags.latest}-${preid}`;
116-
}
117-
}
118-
119-
if (prevTag) {
120-
const next = inc(prevTag, 'prerelease', undefined, preid);
121-
assert(
122-
typeof next === 'string',
123-
`Failed to increment version for ${json.name} prevTag=${prevTag}`,
124-
);
125-
console.log(`Setting next version for ${json.name} to ${next}`);
126-
json.version = next;
127-
writeModulePackageJson(module, json);
128-
129-
// since we're manually setting new versions, we must also reconcile all other lerna packages to use the 'next' version for this module
130-
allModules.forEach((otherModule) => {
131-
// skip it for the current version
132-
if (otherModule.location === module.location) {
133-
return;
134-
}
135-
136-
// Use readModulePackageJson here instead of direct readFileSync
137-
const otherJson = readModulePackageJson(otherModule);
138-
139-
// Check if this module depends on the one we're updating
140-
const otherJsonString = JSON.stringify(otherJson);
141-
if (otherJsonString.includes(json.name)) {
142-
setDependencyVersion(otherJson, json.name, next);
143-
writeModulePackageJson(otherModule, otherJson);
144-
}
145-
});
146-
147-
return next;
148-
}
149-
return undefined;
150-
}
151-
15260
/**
15361
* increment the version based on the preid.
15462
*
@@ -162,20 +70,12 @@ async function incrementVersions(
16270
const distTags = await getDistTagsForModules(lernaModules);
16371

16472
for (const m of lernaModules) {
165-
try {
166-
incrementVersionsForModuleLocation(
167-
preid,
168-
m,
169-
distTags.get(m),
170-
lernaModules,
171-
);
172-
} catch (e) {
173-
// it's not necessarily a blocking error. Let lerna try and publish anyways
174-
console.warn(
175-
`Couldn't set next version for ${m.name} at ${m.location}`,
176-
e,
177-
);
178-
}
73+
await incrementVersionsForModuleLocation(
74+
preid,
75+
m,
76+
distTags.get(m),
77+
lernaModules,
78+
);
17979
}
18080
}
18181

0 commit comments

Comments
 (0)