Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .github/workflows/package-ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,8 @@ jobs:
run: yarn build
- name: Build docs
run: yarn docs
- name: Test documentation publication boundaries
run: yarn test:docs-publishing
- id: test
name: Test the project
run: yarn test:ci
Expand Down
37 changes: 25 additions & 12 deletions .github/workflows/publish.yml
Original file line number Diff line number Diff line change
Expand Up @@ -40,26 +40,39 @@ jobs:
commit: Version Packages
env:
GITHUB_TOKEN: ${{ secrets.CHANGESETS_BOT_TOKEN }}
- name: Build docs
- name: Select released SDK documentation
if: steps.changesets.outputs.published == 'true'
id: docs
env:
PUBLISHED_PACKAGES: ${{ steps.changesets.outputs.publishedPackages }}
run: node scripts/docs-release-plan.mjs "$RUNNER_TEMP/sdk-docs-plan.json"
- name: Build docs
if: steps.docs.outputs.has_docs == 'true'
run: yarn docs
- name: Checkout docs with SSH
if: steps.changesets.outputs.published == 'true'
uses: actions/checkout@v3
if: steps.docs.outputs.has_docs == 'true'
uses: actions/checkout@v4
with:
repository: reflagcom/docs
ssh-key: ${{ secrets.DOCS_DEPLOY_KEY }}
path: reflag-docs
- name: Copy generated docs to docs repo
if: steps.changesets.outputs.published == 'true'
run: |
rm -rf reflag-docs/sdk
cp -R dist/docs reflag-docs/sdk
# Land the docs repository's SDK importer before enabling this workflow.
# That repository owns public paths/banners; SDK sources remain here.
- name: Sync only released packages and majors
if: steps.docs.outputs.has_docs == 'true'
run: node reflag-docs/.github/scripts/sdk-docs.mjs release --source . --destination reflag-docs --plan "$RUNNER_TEMP/sdk-docs-plan.json"
- name: Check generated documentation
if: steps.docs.outputs.has_docs == 'true'
working-directory: reflag-docs
run: node .github/scripts/check-sdk-docs.mjs
- name: Commit and push changes
if: steps.changesets.outputs.published == 'true'
if: steps.docs.outputs.has_docs == 'true'
working-directory: reflag-docs
run: |
cd reflag-docs
git config user.name "github-actions[bot]"
git config user.email "github-actions[bot]@reflag.com"
git add sdk
git commit -m "Update documentation" && git push || echo "No docs changes to commit"
git add supported-languages legacy api sdk .generated/sdk-docs
if ! git diff --cached --quiet; then
git commit -m "Update released SDK documentation"
git push
fi
1 change: 1 addition & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@
"release-packages": "yarn build && yarn release",
"release": "changeset publish",
"docs": "./docs.sh",
"test:docs-publishing": "node --test scripts/docs-release-plan.test.mjs",
"lint:fix": "yarn oxlint --fix .",
"fmt": "yarn oxfmt --check .",
"fmt:fix": "yarn oxfmt --write .",
Expand Down
99 changes: 99 additions & 0 deletions scripts/docs-release-plan.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,99 @@
import assert from "node:assert/strict";
import { execFileSync } from "node:child_process";
import fs from "node:fs";
import path from "node:path";
import { pathToFileURL } from "node:url";

const documented = new Set([
"browser-sdk",
"react-sdk",
"vue-sdk",
"node-sdk",
"react-native-sdk",
"management-sdk",
"cli",
]);
const versionPattern =
/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(-[\da-zA-Z.-]+)?(?:\+[\da-zA-Z.-]+)?$/;
const git = (source, ...args) =>
execFileSync("git", ["-C", source, ...args], { encoding: "utf8" }).trim();

export function selectReleases(source, published) {
assert(Array.isArray(published), "publishedPackages must be an array");
const seen = new Set();
const releases = [];
for (const release of published) {
assert(
release && /^@reflag\/[a-z][a-z0-9-]*$/.test(release.name),
"Invalid published package",
);
assert(
typeof release.version === "string" &&
versionPattern.test(release.version),
"Invalid published version",
);
assert(!seen.has(release.name), "Duplicate published package");
seen.add(release.name);
const name = release.name.slice("@reflag/".length);
if (!documented.has(name)) continue;
const pkg = JSON.parse(
fs.readFileSync(
path.join(source, "packages", name, "package.json"),
"utf8",
),
);
assert.equal(pkg.name, release.name);
assert.equal(
pkg.version,
release.version,
"Published/source version mismatch",
);
assert(!pkg.private, "Private published package");
// A prerelease must not change stable documentation or default navigation.
if (!versionPattern.exec(release.version)[4])
releases.push({ name: release.name, version: release.version });
}
return releases;
}

export function releasePlan(source, published) {
assert.equal(
git(source, "status", "--porcelain", "--untracked-files=no"),
"",
"SDK source must be clean",
);
const sourceCommit = git(source, "rev-parse", "HEAD");
const releases = selectReleases(source, published);
for (const release of releases)
assert.equal(
git(
source,
"rev-parse",
`refs/tags/${release.name}@${release.version}^{commit}`,
),
sourceCommit,
"Release tag/source mismatch",
);
return { sourceCommit, releases };
}

if (
process.argv[1] &&
import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href
) {
const destination = process.argv[2];
assert(destination, "Pass the release-plan output filename");
const plan = releasePlan(
process.cwd(),
JSON.parse(process.env.PUBLISHED_PACKAGES),
);
fs.writeFileSync(destination, `${JSON.stringify(plan, null, 2)}\n`);
if (process.env.GITHUB_OUTPUT)
fs.appendFileSync(
process.env.GITHUB_OUTPUT,
`has_docs=${plan.releases.length > 0}\n`,
);
console.log(
`Selected ${plan.releases.length} stable package releases for documentation.`,
);
}
90 changes: 90 additions & 0 deletions scripts/docs-release-plan.test.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,90 @@
import assert from "node:assert/strict";
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
import test from "node:test";

import { selectReleases } from "./docs-release-plan.mjs";

function fixture(t) {
const root = fs.mkdtempSync(
path.join(os.tmpdir(), "reflag-docs-release-test-"),
);
t.after(() => fs.rmSync(root, { recursive: true, force: true }));
for (const [name, version] of [
["node-sdk", "2.0.0"],
["react-sdk", "2.0.0-next.0"],
["management-sdk", "1.9.0"],
["cli", "1.0.4"],
]) {
const dir = path.join(root, "packages", name);
fs.mkdirSync(dir, { recursive: true });
fs.writeFileSync(
path.join(dir, "package.json"),
JSON.stringify({ name: `@reflag/${name}`, version }),
);
}
return root;
}

test("only stable, actually published SDK/tooling packages enter the plan", (t) => {
const root = fixture(t);
assert.deepEqual(
selectReleases(root, [
{ name: "@reflag/node-sdk", version: "2.0.0" },
{ name: "@reflag/react-sdk", version: "2.0.0-next.0" },
{ name: "@reflag/flag-evaluation", version: "2.0.0" },
]),
[{ name: "@reflag/node-sdk", version: "2.0.0" }],
);
});

test("an independent or CLI-v1 release cannot select unreleased web SDKs", (t) => {
const root = fixture(t);
for (const release of [
{ name: "@reflag/management-sdk", version: "1.9.0" },
{ name: "@reflag/cli", version: "1.0.4" },
])
assert.deepEqual(selectReleases(root, [release]), [release]);
assert.deepEqual(selectReleases(root, []), []);
});

test("source mismatches, malformed inputs and duplicates fail closed", (t) => {
const root = fixture(t);
assert.throws(() => selectReleases(root, {}), /array/);
assert.throws(
() => selectReleases(root, [{ name: "../../escape", version: "2.0.0" }]),
/Invalid published package/,
);
assert.throws(
() => selectReleases(root, [{ name: "@reflag/node-sdk", version: "main" }]),
/Invalid published version/,
);
assert.throws(
() =>
selectReleases(root, [{ name: "@reflag/node-sdk", version: "2.0.1" }]),
/version mismatch/,
);
const item = { name: "@reflag/node-sdk", version: "2.0.0" };
assert.throws(() => selectReleases(root, [item, item]), /Duplicate/);
});

test("workflow scopes documentation by release and delegates version routing to the docs importer", () => {
const release = fs.readFileSync(
new URL("../.github/workflows/publish.yml", import.meta.url),
"utf8",
);
assert.doesNotMatch(release, /rm -rf|cp -R dist\/docs|echo "No docs changes/);
assert.match(release, /steps\.changesets\.outputs\.publishedPackages/);
assert.match(release, /steps\.docs\.outputs\.has_docs == 'true'/);
assert.match(
release,
/sdk-docs\.mjs release --source \. --destination reflag-docs --plan/,
);
assert.match(release, /node \.github\/scripts\/check-sdk-docs\.mjs/);
const ci = fs.readFileSync(
new URL("../.github/workflows/package-ci.yml", import.meta.url),
"utf8",
);
assert.match(ci, /yarn test:docs-publishing/);
});
Loading