Skip to content

Commit d8db3c6

Browse files
Route API docs to the website branch matching the compiler major (#8945)
* Route API docs to the website branch matching the compiler major Why: Following the website default branch lets v13 compiler prereleases update stable v12 API docs. The target must follow the compiler package version through website promotions and maintenance branch cuts. Select v<major> for API checks and publication, push to that branch explicitly, and cover maintenance branches in CI. Test release promotion and branch cuts without changing the API documentation destination. Signed-off-by: Florian Hammerschmidt <florianh89@gmail.com> * Run release planning from Windows script paths Why: The API routing CLI tests exposed an entry-point check that compares a file URL to a Windows path prefixed with file://. It skips main on Windows and exits successfully without writing the workflow outputs. Compare resolved filesystem paths, using the same check as changelog.js. The existing CLI output tests cover the failure on Windows CI. Signed-off-by: Florian Hammerschmidt <florianh89@gmail.com> * Remove the deleted release branch from push CI The review noted that 11.0_release no longer exists. Keep CI on master and maintenance branches for push events. Co-authored-by: Christoph Knittel <ck@cca.io> Signed-off-by: Florian Hammerschmidt <florianh89@gmail.com> * Remove the deleted release branch from pull request CI The review noted that 11.0_release no longer exists. Keep CI on master and maintenance branches for pull request events. Co-authored-by: Christoph Knittel <ck@cca.io> Signed-off-by: Florian Hammerschmidt <florianh89@gmail.com> --------- Signed-off-by: Florian Hammerschmidt <florianh89@gmail.com> Co-authored-by: Christoph Knittel <ck@cca.io>
1 parent 39bf4a1 commit d8db3c6

5 files changed

Lines changed: 135 additions & 4 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,10 @@ name: CI
22

33
on:
44
push:
5-
branches: [master, 11.0_release]
5+
branches: [master, maintenance/*]
66

77
pull_request:
8-
branches: [master, 11.0_release]
8+
branches: [master, maintenance/*]
99

1010
# Release builds are started by publish.yml after a maintainer indicates
1111
# whether the package version is current stable. The npm tag is derived from
@@ -32,6 +32,7 @@ jobs:
3232
build-compiler:
3333
outputs:
3434
api-docs-artifact-id: ${{ steps.upload-api-docs.outputs.artifact-id }}
35+
website-branch: ${{ steps.api-docs-plan.outputs.website-branch }}
3536
strategy:
3637
fail-fast: false
3738
matrix:
@@ -381,6 +382,11 @@ jobs:
381382
!packages/@rescript/runtime/lib/ocaml/*.ast
382383
!packages/@rescript/runtime/lib/ocaml/*.iast
383384
385+
- name: Select API docs website branch
386+
id: api-docs-plan
387+
if: ${{ matrix.generate_api_docs }}
388+
run: node scripts/releasePlan.js --github-output "$GITHUB_OUTPUT"
389+
384390
- name: Generate API Docs
385391
if: ${{ matrix.generate_api_docs }}
386392
run: yarn apidocs:generate
@@ -488,6 +494,7 @@ jobs:
488494
uses: actions/checkout@v7
489495
with:
490496
repository: rescript-lang/rescript-lang.org
497+
ref: ${{ needs.build-compiler.outputs.website-branch }}
491498

492499
- name: Download artifacts
493500
uses: actions/download-artifact@v8

‎.github/workflows/publish.yml‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ jobs:
1919
version: ${{ steps.plan.outputs.version }}
2020
npm-tag: ${{ steps.plan.outputs.npm-tag }}
2121
publish-tag: ${{ steps.plan.outputs.publish-tag }}
22+
website-branch: ${{ steps.plan.outputs.website-branch }}
2223
steps:
2324
- name: Checkout
2425
uses: actions/checkout@v7
@@ -156,6 +157,7 @@ jobs:
156157
uses: actions/checkout@v7
157158
with:
158159
repository: rescript-lang/rescript-lang.org
160+
ref: ${{ needs.release-plan.outputs.website-branch }}
159161
path: rescript-lang.org
160162
ssh-key: ${{ secrets.RESCRIPT_LANG_ORG_DEPLOY_KEY }}
161163

@@ -194,12 +196,16 @@ jobs:
194196

195197
- name: Publish API docs
196198
if: steps.api-docs-diff.outputs.changed == 'true'
199+
env:
200+
WEBSITE_BRANCH: ${{ needs.release-plan.outputs.website-branch }}
197201
run: |
198202
git config user.name "github-actions[bot]"
199203
git config user.email "github-actions@rescript-lang.org"
200204
git add data/api
201205
git commit -m "Update API docs for v${{ needs.release-plan.outputs.version }}"
202-
git push
206+
# The deploy key lets this push trigger the website branch's
207+
# deployment workflow.
208+
git push origin "HEAD:$WEBSITE_BRANCH"
203209
working-directory: rescript-lang.org
204210

205211
- name: Update Website Playground
Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
- Route API documentation checks and publication to the website branch matching
2+
the compiler major (`v12`, `v13`, and later), keeping the target unchanged when
3+
a release becomes current stable or moves to a maintenance branch.

‎scripts/releasePlan.js‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
import fs from "node:fs/promises";
44
import path from "node:path";
55
import process from "node:process";
6+
import { fileURLToPath } from "node:url";
67
import { parseArgs } from "node:util";
78
import semver from "semver";
89

@@ -36,6 +37,7 @@ export function createReleasePlan(version, currentStable = false) {
3637
currentStable,
3738
npmTag,
3839
publishTag: currentStable ? null : npmTag,
40+
websiteBranch: `v${parsedVersion.major}`,
3941
};
4042
}
4143

@@ -112,6 +114,7 @@ async function main() {
112114
`git-tag=${plan.gitTag}`,
113115
`npm-tag=${plan.npmTag}`,
114116
`publish-tag=${plan.publishTag ?? ""}`,
117+
`website-branch=${plan.websiteBranch}`,
115118
].join("\n");
116119
await fs.appendFile(values["github-output"], `${output}\n`);
117120
}
@@ -125,6 +128,7 @@ async function main() {
125128
`| Version | \`${plan.version}\` |`,
126129
`| Git tag | \`${plan.gitTag}\` |`,
127130
`| npm tag | \`${plan.npmTag}\` |`,
131+
`| Website branch | \`${plan.websiteBranch}\` |`,
128132
`| Source commit | \`${process.env.GITHUB_SHA ?? "local"}\` |`,
129133
"",
130134
"The protected `npm-release` job publishes this plan after approval.",
@@ -136,7 +140,10 @@ async function main() {
136140
console.log(JSON.stringify(plan, null, 2));
137141
}
138142

139-
if (import.meta.url === `file://${process.argv[1]}`) {
143+
if (
144+
process.argv[1] &&
145+
path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)
146+
) {
140147
main().catch(error => {
141148
console.error(error.message || error);
142149
process.exitCode = 1;

‎scripts/releasePlan.test.js‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,42 @@
11
import assert from "node:assert/strict";
2+
import { spawnSync } from "node:child_process";
23
import fs from "node:fs/promises";
34
import os from "node:os";
45
import path from "node:path";
56
import test from "node:test";
7+
import { fileURLToPath } from "node:url";
68
import {
79
createReleasePlan,
810
findFirstReleasedVersion,
911
findPendingFragments,
1012
} from "./releasePlan.js";
1113

14+
const websiteTargets = [
15+
["12.3.1", "v12"],
16+
["12.4.0-alpha.1", "v12"],
17+
["13.0.0-alpha.7", "v13"],
18+
["13.0.0", "v13"],
19+
["13.0.1", "v13"],
20+
["14.0.0-alpha.1", "v14"],
21+
["14.0.0", "v14"],
22+
];
23+
1224
test("plans a maintenance release", () => {
1325
assert.deepEqual(createReleasePlan("12.3.0"), {
1426
version: "12.3.0",
1527
gitTag: "v12.3.0",
1628
currentStable: false,
1729
npmTag: "latest-12",
1830
publishTag: "latest-12",
31+
websiteBranch: "v12",
1932
});
2033
});
2134

2235
test("plans a current stable release", () => {
2336
const plan = createReleasePlan("13.0.0", true);
2437
assert.equal(plan.npmTag, "latest");
2538
assert.equal(plan.publishTag, null);
39+
assert.equal(plan.websiteBranch, "v13");
2640
});
2741

2842
test("derives the prerelease tag", () => {
@@ -33,6 +47,100 @@ test("derives the prerelease tag for an older major", () => {
3347
assert.equal(createReleasePlan("12.4.0-beta.1").npmTag, "next-12");
3448
});
3549

50+
test("routes stable and prerelease API docs by compiler major", () => {
51+
for (const [version, branch] of websiteTargets) {
52+
assert.equal(createReleasePlan(version).websiteBranch, branch);
53+
}
54+
});
55+
56+
test("promoting a release changes its npm tag without moving its docs", () => {
57+
for (const [version, branch] of websiteTargets) {
58+
if (version.includes("-")) continue;
59+
const maintenance = createReleasePlan(version);
60+
const stable = createReleasePlan(version, true);
61+
assert.notEqual(maintenance.npmTag, stable.npmTag);
62+
assert.equal(maintenance.websiteBranch, branch);
63+
assert.equal(stable.websiteBranch, branch);
64+
}
65+
});
66+
67+
test("exports the selected website branch for release workflows", async t => {
68+
const root = await fs.mkdtemp(path.join(os.tmpdir(), "rescript-api-docs-"));
69+
t.after(() => fs.rm(root, { recursive: true, force: true }));
70+
const script = fileURLToPath(new URL("./releasePlan.js", import.meta.url));
71+
72+
for (const [version, branch] of websiteTargets) {
73+
const output = path.join(root, `${version}.output`);
74+
const summary = path.join(root, `${version}.summary`);
75+
const result = spawnSync(
76+
process.execPath,
77+
[
78+
script,
79+
"--version",
80+
version,
81+
"--github-output",
82+
output,
83+
"--github-summary",
84+
summary,
85+
],
86+
{ encoding: "utf8" },
87+
);
88+
assert.equal(result.status, 0, result.stderr);
89+
assert.ok(
90+
(await fs.readFile(output, "utf8")).includes(
91+
`website-branch=${branch}\n`,
92+
),
93+
);
94+
assert.ok(
95+
(await fs.readFile(summary, "utf8")).includes(
96+
`| Website branch | \`${branch}\` |`,
97+
),
98+
);
99+
}
100+
});
101+
102+
test("keeps CI routing when master advances and a maintenance branch is cut", async t => {
103+
const root = await fs.mkdtemp(path.join(os.tmpdir(), "rescript-api-docs-"));
104+
t.after(() => fs.rm(root, { recursive: true, force: true }));
105+
const cases = [
106+
["maintenance/12.x", "12.3.1", "v12"],
107+
["master", "13.0.0-alpha.7", "v13"],
108+
["maintenance/13.x", "13.0.1", "v13"],
109+
["master", "14.0.0-alpha.1", "v14"],
110+
];
111+
for (const [index, [ref, version, branch]] of cases.entries()) {
112+
await fs.writeFile(
113+
path.join(root, "package.json"),
114+
JSON.stringify({ version }),
115+
);
116+
const output = path.join(root, `github-output-${index}`);
117+
const result = spawnSync(
118+
process.execPath,
119+
[
120+
fileURLToPath(new URL("./releasePlan.js", import.meta.url)),
121+
"--github-output",
122+
output,
123+
],
124+
{
125+
cwd: root,
126+
encoding: "utf8",
127+
env: {
128+
...process.env,
129+
GITHUB_REF: `refs/heads/${ref}`,
130+
GITHUB_REF_NAME: ref,
131+
},
132+
},
133+
);
134+
assert.equal(result.status, 0, result.stderr);
135+
assert.ok(
136+
(await fs.readFile(output, "utf8")).includes(
137+
`website-branch=${branch}\n`,
138+
),
139+
`${ref} at ${version} should use ${branch}`,
140+
);
141+
}
142+
});
143+
36144
test("rejects promoting a prerelease to current stable", () => {
37145
assert.throws(
38146
() => createReleasePlan("13.0.0-alpha.6", true),

0 commit comments

Comments
 (0)