Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs: align release process with branch merge-back (#7293)

Cindy Zhang693da50c07c8
diff --git a/.changeset/release-branch-process-docs.md b/.changeset/release-branch-process-docs.md
new file mode 100644
index 0000000000..98f254b477
--- /dev/null
+++ b/.changeset/release-branch-process-docs.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[docs] Clarify release-branch codemod promotion and version ownership.
+
+@cixzhang
diff --git a/.github/scripts/cdn-template-smoke-test.mjs b/.github/scripts/cdn-template-smoke-test.mjs
index 1e30c905c4..c0d58b8504 100644
--- a/.github/scripts/cdn-template-smoke-test.mjs
+++ b/.github/scripts/cdn-template-smoke-test.mjs
@@ -31,7 +31,10 @@ import * as path from 'node:path';
import {fileURLToPath} from 'node:url';
import {resolvePublishedCdnVersion} from './lib/cdn-version.mjs';
-const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+const ROOT = path.resolve(
+ path.dirname(fileURLToPath(import.meta.url)),
+ '../..',
+);
const CLI = path.join(ROOT, 'packages/cli/clients/cli/bin/astryx.mjs');
const PAGE = 'cdn.template.html';
const ATTEMPTS = 2;
@@ -50,11 +53,15 @@ fs.writeFileSync(
path.join(tmpDir, 'package.json'),
JSON.stringify({name: 'cdn-smoke', private: true}),
);
-const scaffold = spawnSync(process.execPath, [CLI, '--json', 'template', '--cdn'], {
- cwd: tmpDir,
- encoding: 'utf8',
- timeout: 60_000,
-});
+const scaffold = spawnSync(
+ process.execPath,
+ [CLI, '--json', 'template', '--cdn'],
+ {
+ cwd: tmpDir,
+ encoding: 'utf8',
+ timeout: 60_000,
+ },
+);
if (scaffold.status !== 0 || !fs.existsSync(pagePath)) {
fail(`astryx template --cdn (exit ${scaffold.status})`, scaffold.stderr);
process.exit(1);
@@ -63,9 +70,9 @@ const pinned = JSON.parse(scaffold.stdout).data.version;
console.log(`scaffolded ${PAGE} pinned to ${pinned}`);
// ── 2. Point the page at a version that is actually on the CDN ───────────────
-// The pin is the version in this checkout, which is unpublished for the whole
-// life of a release PR (`changeset version` bumps package.json before npm has
-// the tarball). Gating every PR on that would make the release PR unmergeable,
+// The pin is the owner-declared version in this checkout. It can remain
+// unpublished throughout next-plan and release-branch PRs; branch consolidation
+// writes changelogs without bumping package.json. Gating every PR on that exact
// so on an unpublished pin we re-point the page at npm's stable `latest`
// dist-tag and still assert the recipe. Registry `versions` keys are not a
// version-ordered API: the final key can be a canary that esm.sh has not built.
@@ -78,7 +85,9 @@ if (rendered == null) {
process.exit(1);
}
if (rendered !== pinned) {
- console.log(` note ${pinned} is not published yet — rendering against ${rendered}`);
+ console.log(
+ ` note ${pinned} is not published yet — rendering against ${rendered}`,
+ );
fs.writeFileSync(
pagePath,
fs.readFileSync(pagePath, 'utf8').replaceAll(`@${pinned}`, `@${rendered}`),
@@ -153,7 +162,10 @@ for (const [label, entries] of [
if (entries.length === 0) {
console.log(` ok no ${label}s`);
} else {
- fail(`${entries.length} ${label}(s)`, entries.map(e => ` ${e}`).join('\n'));
+ fail(
+ `${entries.length} ${label}(s)`,
+ entries.map(e => ` ${e}`).join('\n'),
+ );
}
}
if (result.button) {
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b6e9b05f0e..098201da23 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -707,27 +707,58 @@ release keep working. Name an id the way the failure prints it, such as
`themes` or `DoctorCheck.fix`. Catalog values inside those responses, such as template
slugs and docs routes, are data and may change.
-### Version Bumps
-
-- **Main declares the next version.** The fixed group's version in main's `package.json` files is the next planned release, for example `0.7.0` while `0.6.7` is the latest stable release. Main publishes only canaries of it (`0.7.0-canary.<sha>`). Before the cut, a release owner may raise or lower the plan—`0.7.0` to `0.6.8`, for example—but it must remain strictly above the newest stable `vX.Y.Z` tag. After a release, sync uses the higher of the current plan and the released version's patch successor. CI refuses a declaration at or below newest stable or a split fixed group.
-- **0.x: the category states the tier a change needs.** We track standard semver for the `0.x.y` range, where a minor is the stable breaking tier (under a caret range like `^0.1.8`, npm resolves `<0.2.0`). A `[breaking]` Changeset declares `minor`: it can ship only in a minor release. A change confined to a surface that was explicitly marked experimental before its first stable publication uses `[experimental]` and declares `patch`, even when that experimental API changes incompatibly. Every other category (`feat`, `fix`, `component`, `perf`, `docs`, `chore`) also declares `patch`. If stable defaults, behavior, props, imports, CLI commands, or machine schemas break, the change remains `[breaking]`. `major` is never used while 0.x — it would jump to `1.0.0`. `pnpm changeset:new` writes the right bump from the category you pick; `pnpm check:changesets` enforces the coupling both ways. A Changeset's bump never chooses the release version.
-- All publishable packages are a `fixed` group, so they release together at one version. Only genuinely-affected packages get a changelog entry.
-- **Pull requests to main check Changeset format, not the release.** `pnpm check:changesets` and the coverage check run on every pull request; neither compares your Changeset with a release version, so a `[breaking]` Changeset can merge while main declares a patch.
-- **The release branch admits Changesets against the declared version.** If main declares the patch after the latest stable release (`0.6.7` after `0.6.6`), the release refuses an incompatible Changeset. There are two ways forward, and the refusal prints both:
- - **Keep the release patch-compatible** (the usual answer): leave the released surface working and deprecate it instead. Ship the replacement, keep the old usage equivalent, and let the removal ship in a minor release.
- - **Plan the minor**: a release owner bumps main's version to the minor (`0.7.0`) before the cut. A release that declares `0.7.0` consumes a `[breaking]` Changeset into `0.7.0` changelogs; it does not move to `0.8.0`.
-
- As a contributor you never change the declared version — say what you intend in the PR and a maintainer handles it. The rule is `spec:AST-017` FR46–FR50.
+### Release versions
+
+- **Main declares the next version.** The fixed group's version in main's
+ `package.json` files is the next planned release. Before a cut, an owner may
+ raise or lower it while it stays strictly above newest stable. While an
+ untagged cut is active, main may stay equal to that cut or rise, but cannot be
+ lowered below it. After the tag, ordinary PRs must be strictly above stable;
+ trusted merge-back is the only equality exception and publishes no canary.
+- **0.x: the category states the tier a change needs.** A `[breaking]`
+ Changeset declares `minor` and is admitted only while main already declares
+ the next minor. `[experimental]` and every other category declare `patch`.
+ A Changeset never chooses the plan. CI refuses `[breaking]` on a patch plan
+ and refuses a minor-to-patch lowering PR that would strand pending breaking
+ work. The routes are to keep the old usage compatible through deprecation, or
+ have an owner explicitly plan the minor.
+- All publishable packages are a `fixed` group, so they release together at one
+ version. Only genuinely affected packages get a changelog entry.
+- As a contributor you never change the declared version. State compatibility
+ intent and add the right Changeset; a maintainer owns release planning. The
+ governing contract is `spec:AST-017` FR46–FR51.
### How a release is cut
-A release branch `release/vX.Y.Z` is cut from main, where `X.Y.Z` is the version main declares at that commit. On that branch only:
+First, the canonical full-scope `release-check` must pass on an exact commit from
+current `main`; the release branch is cut only from that checked SHA while it remains
+in current main history. A minor cut also requires Cindy, the release owner, to
+explicitly sign off on the exact `vX.Y.0` immediately before the branch is created.
+Scheduled or standing authority does not cover a minor.
+
+A release branch `release/vX.Y.Z` is then cut from that commit, where `X.Y.Z` is the
+version main declares. On that branch only:
```bash
pnpm version-packages # changelogs at the declared version + codemod promotion + formatting
```
-`scripts/release/version-packages.mjs` admits the pending Changesets against the declared version, writes their changelog entries under it, and deletes them; it never changes a package version. `format-changelogs.mjs` then rewrites each package CHANGELOG into the doc-site format (h1 version, `#### <Category>` sections in canonical order, and a `#### Contributors` section aggregated from the changeset `@handle`s). It's idempotent and has a `--check` mode for CI drift detection. After publication, syncing the release back to main carries the changelogs, removes the consumed Changesets, and moves main to the release's next patch unless an owner already set it higher; main's versions never move backward.
+`scripts/release/version-packages.mjs` admits the frozen Changesets against the
+declared version, writes their changelog entries under it, and deletes them; it
+never changes a package version. The command then promotes staged codemods,
+refreshes exact internal pins, and formats changelogs with contributor credit.
+Refresh and verify `pnpm-lock.yaml` before the Version Packages PR merges. After tag and publication, one trusted
+`chore/merge-vX.Y.Z-to-main` PR squashes the exact branch-owned outputs and
+frozen deletions onto current main while preserving every post-cut change and
+main's declaration. A separate owner PR then declares the next plan across the
+fixed group, exact internal pins, and lockfile—patch successor by default,
+minor only when the owner explicitly names it.
+
+Before stable publication, a patch release self-grades its complete generated
+changelogs and draft GitHub Release notes against the public Blog Review Rubric's
+`update` profile. Every criterion must pass; failures are fixed on the release
+branch and the complete text is re-graded. A minor release instead requires Cindy's
+explicit human editorial approval of the changelogs, release notes, and public blog.
## Finding Something to Work On
diff --git a/docs/release.md b/docs/release.md
index 225765814f..57a04fa755 100644
--- a/docs/release.md
+++ b/docs/release.md
@@ -1,94 +1,100 @@
-## Releasing to npm via Trusted Publishing (OIDC)
-
-astryx publishes its 12 public `@astryxdesign/*` packages to the public npm registry from GitHub Actions using **npm trusted publishing (OIDC)** — there is **no long-lived `NPM_TOKEN`** anywhere in CI. The publish job exchanges a short-lived GitHub OIDC token for a registry credential at publish time, and stamps **provenance** onto every package. A misconfigured trust relationship fails the publish loudly; there is no token to fall back to.
-
-### How it fits together
-
-- **Main declares the version; the release branch versions.** Main's `package.json` carries the next planned version and publishes only canaries of it. On the marked release branch, `pnpm run version-packages` (= `scripts/release/version-packages.mjs && promote-codemod-next && sync-internal-deps && format-changelogs`) admits the pending Changesets against that declared version, writes changelogs under it, and promotes release-staged codemods. It never changes a package version, edits only files on disk, needs no npm auth, and is untouched by trusted publishing.
-- **Publishing is pnpm-native and tokenless.** CI runs `pnpm publish ... --provenance --access public --no-git-checks` (not `changeset publish`, whose `npm whoami` precheck breaks under tokenless OIDC). pnpm natively fetches the OIDC token and attaches provenance.
-- **Trust is per-package.** npm allows exactly **one** trust configuration per package, registered against the **calling** workflow. Each of the 12 packages must be configured individually.
-
-### Version-package codemod promotion
-
-Core codemods for unreleased breaking changes are staged in
-`packages/cli/assets/codemods/transforms/next/`, not in a guessed future version
-folder. During the Version Packages PR, `pnpm version-packages` runs
-`scripts/promote-codemod-next.mjs` immediately after the changelogs are written;
-`packages/core/package.json` already carries the declared release version.
-
-The promotion step copies every entry from `next` except `README.md` into
-`packages/cli/assets/codemods/transforms/v<released-version>/`, removes the
-promoted files from `next`, and registers the new version folder in
-`packages/cli/assets/codemods/registry.mjs`. Review those generated files in the
-Version Packages PR the same way you review changelog output.
-
-### The publish workflow (`.github/workflows/deploy.yml`)
-
-The `publish` job runs on push to `main` after `test` passes. The two requirements for OIDC are already present:
-
-```yaml
-permissions:
- contents: read
- id-token: write # required for npm trusted publishing (OIDC)
-steps:
- - uses: actions/setup-node@v6
- with:
- node-version: 22
- registry-url: 'https://registry.npmjs.org' # writes .npmrc pointing at the registry
-```
-
-The publish step uses pnpm-native publishing and carries **no** `NODE_AUTH_TOKEN` / `secrets.NPM_TOKEN`:
-
-```yaml
-- name: Publish changed packages
- run: pnpm -r publish --provenance --access public --no-git-checks
-```
-
-`pnpm -r publish` resolves `workspace:*`/`catalog:` deps to real versions, skips already-published versions (so re-running is a no-op), respects `"private": true`, and publishes in dependency order.
-
-> Why the `workflow_ref` claim matters: npm matches its stored trust config against the OIDC token's `workflow_ref` claim, which GitHub sets to the **calling** (entry) workflow — `deploy.yml` here — not any reusable workflow. astryx's publish runs directly in `deploy.yml` (no `workflow_call` indirection), so the trusted workflow filename to register is **`deploy.yml`**. If publishing is ever refactored into a reusable workflow, keep `deploy.yml` in the trust config (the caller) and grant `id-token: write` to both workflows.
-
-### Version requirements
-
-- **pnpm:** the repo pins `[email protected]`. The 11.x line must be **≥ 11.1.3**, which is where the pnpm 11.0–11.1.2 OIDC 404 regression was fixed (11.10.0 satisfies this). pnpm 10.16+ / 11.1.3+ both support OIDC + provenance. (Previously pinned to `[email protected]`, the Lexical-proven known-good 10.x floor whose line shells out to `npm publish`; see the upgrade PR for the move to 11.x.)
-- **npm (in the runner):** Node 22.14+/24.x runners bundle npm ≥ 11.5.1, which is what the 10.x publish path needs. No action required in CI.
-- **npm (on the maintainer's machine, for setup only):** the setup script requires **npm ≥ 11.10** for `npm trust github`. Run `npm i -g npm@latest` before setup.
-
-### The trusted-publishing maintainer script
-
-`scripts/npm/setup-trusted-publishing.mjs` is a one-time/occasional script a maintainer runs **locally** (with an interactive npm session) to prepare every public package for trusted publishing. It is decoupled from CI — its only job is to make the CI publish succeed. It discovers the same 12 publishable packages CI does (`pnpm-workspace.yaml` globs, minus `private` packages and the `.changeset/config.json` `ignore` list).
-
-There is no package.json script alias for it; run the file directly with Node:
-
+# Releasing to npm with trusted publishing
+
+The public [Release Process](https://github.com/facebook/astryx/wiki/Release-Process)
+is the operational authority. This page explains the repository and npm mechanics.
+
+Astryx publishes its public `@astryxdesign/*` packages from GitHub Actions through
+npm trusted publishing (OIDC). CI carries no long-lived npm publish token. Every
+stable package is built from an immutable release tag and published with provenance.
+
+## Release sequence
+
+1. Run the canonical full-scope `release-check` on an exact commit from current
+ `main`. Cut only from that checked SHA while it remains in current `main`
+ history. A minor cut additionally requires Cindy, the release owner, to
+ explicitly sign off on the exact `vX.Y.0` immediately before the branch is
+ created; scheduled or standing authority never substitutes for that sign-off.
+2. Create the single marked `release/vX.Y.Z` branch. Its version is the fixed-group
+ version declared by the cut commit. The marker and plan freeze the cut SHA,
+ Changeset paths and hashes, branch identity, and plan digest.
+3. On that branch, run `pnpm version-packages`. It admits the frozen Changesets
+ against the declared tier, writes changelogs under that already-declared version,
+ promotes staged codemods, refreshes exact internal pins, and deletes only the
+ frozen Changesets. It never chooses or bumps the version. Refresh and verify the
+ lockfile before the Version Packages PR merges.
+4. Merge the generated PR to the release branch, run exact-head branch CI, and
+ clear the public editorial gate. For a patch, self-grade the complete generated
+ changelogs and draft GitHub Release notes against the public Blog Review Rubric's
+ `update` profile, record the result, and fix and re-grade every failed criterion.
+ A minor requires Cindy's explicit human editorial approval of the changelogs,
+ release notes, and required public blog. Then tag and publish that exact branch
+ head. Stable publication from `main` is refused.
+5. Squash the published branch outputs back into current `main` through
+ `chore/merge-vX.Y.Z-to-main`. The trusted validator requires the immutable tag,
+ active branch head, and plan digest; exact generated bytes and frozen deletions;
+ and preservation of every post-cut Changeset, commit, unrelated field, and main's
+ current version declaration. Branch lifecycle files never land on `main`.
+6. In a separate owner PR, declare the next plan across the fixed-group versions,
+ exact internal pins, and lockfile. The released version's patch successor is the
+ default. A minor successor is used only when the owner explicitly names it.
+
+While an untagged cut is active, main may keep the cut version or move higher but
+cannot be lowered below it. After the tag exists, ordinary main PRs must stay
+strictly above the newest stable tag. Trusted merge-back is the only equality
+exception. The canary workflow succeeds without publishing from equality; the
+separate next-plan PR exits that state immediately after merge-back.
+
+## Changesets and codemods
+
+Feature PRs add normal Changesets with `pnpm changeset:new`. Pending Changesets do
+not choose the release version. While packages are `0.x`, `[breaking]` work is
+admissible only when main already declares the next minor; a patch declaration
+refuses it. A PR that lowers a minor plan to a patch is itself refused while a
+`[breaking]` Changeset is pending.
+
+Core codemods for unreleased changes are staged in
+`packages/cli/assets/codemods/transforms/next/`. During the Version Packages PR,
+`pnpm version-packages` runs `scripts/promote-codemod-next.mjs` after changelogs are
+written. It copies every staged entry except `README.md` into
+`transforms/v<declared-version>/`, clears the promoted files from `next`, and updates
+the registry. Review those generated files with the changelogs.
+
+## Stable and canary publication
+
+Both publication paths live in `.github/workflows/release.yml`, because npm permits
+one trusted GitHub workflow per package.
+
+- **Stable:** explicit dispatch from the immutable `vX.Y.Z` tag with the exact
+ release branch, version, head, tag, and plan digest. It publishes `latest`.
+- **Canary:** automatic main push. It publishes
+ `<declared-version>-canary.<short-sha>` to `canary` only while the declaration is
+ strictly above the newest stable tag. It never authorizes or mutates stable release
+ state.
+
+The publish step uses pnpm-native publishing:
+
+```sh
+pnpm publish ./packages/<package> \
+ --tag latest --provenance --access public --no-git-checks
```
-node scripts/npm/setup-trusted-publishing.mjs [flags]
-```
-
-It has three modes, gated by flags:
-
-| Mode | Flag | What it does |
-| ------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Audit** (default) | _(none)_ | For each public package: probe the registry (HEAD), report which already exist and which already have a matching trust config, and print a manual-setup guide. No writes. |
-| **Bootstrap** | `--bootstrap` | npm trusted publishing cannot be configured on a name that does not exist (no PyPI-style pending publisher). For each package not yet on npm, publish a deprecated placeholder `0.0.0-bootstrap.0` stub under the `bootstrap` dist-tag (never `latest`) to claim the name. |
-| **Setup trust** | `--setup-trust` | Run `npm trust github <pkg> --file deploy.yml --repo facebook/astryx --allow-publish -y` for each package, skipping ones already correctly configured. `--replace` revokes a conflicting config first. |
-
-Other flags: `--dry-run`, `--registry <url>`, `--stub-version <v>`, `--workflow <file>` (default `deploy.yml`; single filename, no commas), `--repo <owner/name>` (default `facebook/astryx`). Because the script is invoked directly via `node`, pass flags straight through (no `--` separator).
-**Preflights:** when it will write, it runs `npm whoami` (fails with a `npm login` hint if unauthenticated); for `--setup-trust` it also enforces npm ≥ 11.10 and verifies `npm trust` exists.
+## Trusted-publisher setup
-**2FA / the "skip for 5 minutes" prompt:** reading and writing trust config requires account-level 2FA. npm only runs its interactive web-auth/OTP flow when **both** stdin and stdout are TTYs, but per-package trust reads must capture stdout (a pipe). So the script does **one** fully-interactive warm-up read first and instructs you to choose **"Skip two-factor authentication for the next 5 minutes"** at that prompt, so all subsequent reads/writes in the run complete within that window without re-prompting.
+Trust is configured per package and must point at `release.yml`. A new public package
+must exist on npm before trust can be registered, so an npm organization owner runs:
-**Idempotency & conflicts:** already-correctly-configured packages are skipped (no needless OTP). A non-matching existing config is reported as a CONFLICT (npm returns E409 if you POST a second config); re-run with `--replace` to revoke-then-add. E429 rate limits are retried with exponential backoff.
-
-### Typical first-time run
-
-```
+```sh
npm i -g npm@latest
npm login --registry https://registry.npmjs.org
-node scripts/npm/setup-trusted-publishing.mjs # audit only
-node scripts/npm/setup-trusted-publishing.mjs --bootstrap --setup-trust # claim names + register trust
+node scripts/npm/setup-trusted-publishing.mjs
+node scripts/npm/setup-trusted-publishing.mjs \
+ --bootstrap --setup-trust --workflow release.yml
```
-After the first OIDC publish succeeds, the bootstrap stubs are superseded by the real versions (they remain only under the deprecated `bootstrap` dist-tag).
+The default invocation is audit-only. `--bootstrap` claims a missing package name with
+a deprecated `0.0.0-bootstrap.0` version under the `bootstrap` dist-tag; it never
+publishes `latest`. `--setup-trust` registers `release.yml`. Use `--replace` only when
+an existing trust record is intentionally being replaced.
-> Sequencing note: the legacy `NPM_TOKEN` secret stays in place until the pnpm-native OIDC change in `deploy.yml` has merged AND the first OIDC publish has succeeded with provenance. Remove `NPM_TOKEN` only AFTER that first green OIDC publish — never before — otherwise any push to main in the gap runs the still-token-based `pnpm changeset publish` (and the canary `npm publish`) with an empty token and breaks main.
+The repo pins pnpm 11. The CI Node line must bundle npm 11.5.1 or later for OIDC
+publishing; the local trust setup command requires npm 11.10 or later.
diff --git a/packages/cli/CONTRIBUTING.md b/packages/cli/CONTRIBUTING.md
index 0b95df0067..3b86d458f2 100644
--- a/packages/cli/CONTRIBUTING.md
+++ b/packages/cli/CONTRIBUTING.md
@@ -303,7 +303,7 @@ pnpm -F @astryxdesign/cli typecheck:strict
```
This is a **required CI gate**: it runs on every PR and in the merge queue (the `build`
-check in `ci.yml`) and again before every deploy (the `test` job in `deploy.yml`), so the
+check in `ci.yml`) and again in the post-merge validation gate in `deploy.yml`, so the
CLI must stay strict-clean — a new un-annotated parameter or type error fails CI. Run it
locally before pushing. (The emitted `templates/**/*.tsx` import built workspace packages,
so run `pnpm build` first or you'll see spurious "cannot find module" errors from unbuilt
diff --git a/packages/cli/README.md b/packages/cli/README.md
index 1ad9e03ec6..3230c6f0e2 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -611,14 +611,16 @@ Do not guess that version in ordinary feature PRs. Add new codemods to
- leave `transforms/next/README.md` in place; it documents the staging area and
is never promoted.
-During the Version Packages PR, `pnpm version-packages` runs
-`scripts/promote-codemod-next.mjs` after `changeset version`. The script copies
-all staged entries except the README into `transforms/v<new-core-version>/`,
-registers that version in `packages/cli/assets/codemods/registry.mjs`, and clears
-the promoted files from `next`.
-
-This mirrors Changesets: feature PRs stage migration work without knowing the
-future release number; the release PR assigns the exact version.
+During the release branch's Version Packages PR, `pnpm version-packages` runs
+`scripts/promote-codemod-next.mjs` after it writes changelogs under the version
+already declared at the cut. The script copies all staged entries except the
+README into `transforms/v<declared-core-version>/`, registers that version in
+`packages/cli/assets/codemods/registry.mjs`, and clears the promoted files from
+`next`.
+
+Feature PRs stage migration work without guessing a version. The marked release
+branch assigns the exact cut declaration; the later merge-back carries those
+exact promoted files to main without regenerating them.
## Integrations
diff --git a/packages/cli/assets/codemods/transforms/next/README.md b/packages/cli/assets/codemods/transforms/next/README.md
index 04f7b8d63f..106862d73f 100644
--- a/packages/cli/assets/codemods/transforms/next/README.md
+++ b/packages/cli/assets/codemods/transforms/next/README.md
@@ -2,29 +2,27 @@
Put new core codemods here while normal feature PRs are in flight.
-Why: the folder that ships a codemod is the **target package version** that will
-include the breaking change. Feature PRs usually do not know that version yet;
-the Version Packages PR decides it after `changeset version` resolves all pending
-changesets. This `next` folder works like Changesets: contributors stage work
-here, then the release/versioning step promotes it into the actual versioned
-folder.
+The folder that ships a codemod is the target package version containing the
+change. Feature PRs do not choose that version: main's fixed-group declaration is
+the owner plan, and the marked release branch freezes it at cut. Contributors stage
+work here; the release branch promotes it into the exact declared version folder.
## Authoring rules
- Add new transform modules directly under this directory.
-- Add or update this directory's `index.mjs` so it exports the transforms in the
- order they should run.
-- Keep tests next to the transform, following existing version-folder patterns.
-- Do **not** guess a future `v0.x.y` folder in feature PRs.
+- Add or update `index.mjs` so it exports transforms in run order.
+- Keep tests beside each transform, following existing version-folder patterns.
+- Do **not** guess a future `v0.x.y` folder in a feature PR.
- Do **not** put release-specific content in this README; it stays in `next`.
## Release promotion
-`pnpm version-packages` runs `scripts/promote-codemod-next.mjs` after
-`changeset version`. The script copies every entry in this directory except this
-README into `packages/cli/assets/codemods/transforms/v<new-core-version>/` and
-removes the promoted files from `next`.
+On the marked release branch, `pnpm version-packages` runs
+`scripts/promote-codemod-next.mjs` after writing changelogs under the cut's declared
+version. It copies every entry except this README into
+`packages/cli/assets/codemods/transforms/v<declared-core-version>/`, registers the
+folder, and removes the promoted files from `next`.
-After promotion, the Version Packages PR should review the generated version
-folder and add it to `packages/cli/assets/codemods/registry.mjs` if it is a new
-version folder.
+The Version Packages PR reviews the generated folder with the changelogs. After
+publication, trusted merge-back carries those exact promoted files to current main;
+it does not regenerate them.
diff --git a/scripts/changeset-new.mjs b/scripts/changeset-new.mjs
index 9d3c2cf439..9cafb69a0d 100755
--- a/scripts/changeset-new.mjs
+++ b/scripts/changeset-new.mjs
@@ -9,8 +9,8 @@
* 1. Repo-wide changes / per-package changelogs — auto-detects which
* publishable packages your working tree touched and pre-selects them,
* so you don't hand-enumerate the frontmatter. Only genuinely-affected
- * packages get the changelog entry; the `fixed` lockstep co-bumps the
- * rest so versions stay aligned without polluting their changelogs.
+ * packages get the changelog entry; the owner-declared `fixed` version
+ * keeps the stable group aligned without polluting other changelogs.
* 2. semver for 0.x — derives the bump from the category. A [breaking]
* change bumps the minor (0.x.y -> 0.(x+1).0, the breaking tier under
* caret ranges); every other category, including [experimental], bumps
@@ -20,9 +20,9 @@
* authoring time (defaulting to your `gh` / git identity) and writes them
* into the changeset body, where the custom changelog module reads them.
*
- * Output is a normal `.changeset/<id>.md` — fully compatible with the stock
- * `changeset version`. The only convention is the body format, validated by
- * scripts/check-changesets.mjs.
+ * Output is a normal `.changeset/<id>.md`, compatible with the pinned
+ * Changesets parser and the custom declared-version `pnpm version-packages`
+ * step. The body convention is validated by scripts/check-changesets.mjs.
*
* Flags (all optional; missing values are prompted):
* --category <key> breaking|experimental|component|feat|fix|perf|docs|chore
diff --git a/scripts/format-changelogs.mjs b/scripts/format-changelogs.mjs
index 5bff74265a..0d2456e2ed 100755
--- a/scripts/format-changelogs.mjs
+++ b/scripts/format-changelogs.mjs
@@ -1,10 +1,11 @@
#!/usr/bin/env node
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * Post-`changeset version` changelog formatter — `node scripts/format-changelogs.mjs`.
+ * Release-branch changelog formatter — `node scripts/format-changelogs.mjs`.
*
- * `changeset version` (with our custom .changeset/changelog.cjs) writes raw
- * entries per package in the form:
+ * The custom `pnpm version-packages` step uses the pinned Changesets libraries
+ * to write raw entries under the version already declared at the cut. Those
+ * entries have the form:
*
* ## 0.0.16
*
diff --git a/scripts/promote-codemod-next.mjs b/scripts/promote-codemod-next.mjs
index 7412889419..3b98ebeaec 100755
--- a/scripts/promote-codemod-next.mjs
+++ b/scripts/promote-codemod-next.mjs
@@ -1,9 +1,10 @@
#!/usr/bin/env node
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * Promote staged codemods from transforms/next into the just-bumped release
- * version folder. Run after `changeset version`, when package.json contains
- * the actual version this release will publish.
+ * Promote staged codemods from transforms/next into the release version folder
+ * declared at the cut. `pnpm version-packages` runs this after its custom
+ * release-branch versioner writes changelogs at that declaration; package.json
+ * already contains the exact version and is never bumped here.
*
* The target version folder MAY already exist and already contain codemods —
* e.g. a codemod PR that merged earlier in the release cycle seeded
diff --git a/scripts/score-ledger.mjs b/scripts/score-ledger.mjs
index f5c9497c21..195751a7b7 100644
--- a/scripts/score-ledger.mjs
+++ b/scripts/score-ledger.mjs
@@ -59,9 +59,9 @@ export const WIKI_BRANCH = 'master';
/**
* The one place the ledger is readable by a human: the sandbox page, which
- * fetches the JSON at runtime. Deployed from `main` by .github/workflows/
- * deploy.yml to the stable (unversioned) GitHub Pages path — /pr/<n>/ paths
- * are PR previews and must never be linked from anything durable.
+ * fetches the JSON at runtime. The Vercel project deploys current `main` to the
+ * stable unversioned path; `/pr/<n>/` paths are PR previews and must never be
+ * linked from anything durable.
*/
export const SCORES_PAGE_URL =
'https://astryx.atmeta.com/sandbox/pages/component-scores/';
@@ -201,7 +201,7 @@ const AUDIT_MODE_BY_ALIAS = new Map(
/** Resolve a scorecard or legacy ledger mode to its lifecycle policy. */
export function auditModePolicy(mode) {
return typeof mode === 'string'
- ? AUDIT_MODE_BY_ALIAS.get(mode.trim().toLowerCase()) ?? null
+ ? (AUDIT_MODE_BY_ALIAS.get(mode.trim().toLowerCase()) ?? null)
: null;
}
@@ -313,7 +313,9 @@ export function flatPackageComponents(srcDir, repoRoot = ROOT) {
const packageConfig = COMPONENT_PACKAGES.find(
pkg => path.resolve(repoRoot, pkg.src) === path.resolve(srcDir),
);
- return packageConfig ? flatPackageComponentNames(repoRoot, packageConfig) : [];
+ return packageConfig
+ ? flatPackageComponentNames(repoRoot, packageConfig)
+ : [];
}
/**
@@ -366,7 +368,10 @@ export const LEDGER_FETCH_TIMEOUT_MS = 10_000;
* failing a pull request on network flake or on the wiki being momentarily
* unavailable.
*/
-export async function loadLedger(source, {timeoutMs = LEDGER_FETCH_TIMEOUT_MS} = {}) {
+export async function loadLedger(
+ source,
+ {timeoutMs = LEDGER_FETCH_TIMEOUT_MS} = {},
+) {
try {
let text;
if (isUrl(source)) {
@@ -455,7 +460,9 @@ export function buildRoster(ledger, components = listComponents()) {
});
}
return roster.sort(
- (a, b) => a.component.localeCompare(b.component) || a.package.localeCompare(b.package),
+ (a, b) =>
+ a.component.localeCompare(b.component) ||
+ a.package.localeCompare(b.package),
);
}
@@ -476,7 +483,8 @@ export const openBlockCount = entry =>
? entry.blocks.count
: 0;
-export const blockList = entry => (entry && entry.blocks && entry.blocks.open) || [];
+export const blockList = entry =>
+ (entry && entry.blocks && entry.blocks.open) || [];
const isAudited = entry => !!entry && entry.status === 'audited';
@@ -592,7 +600,9 @@ export function compareEntry(component, baseEntry, headEntry) {
* one result per package rather than an arbitrary pick.
*/
export function runRatchet(components, baseLedger, headLedger, roster = null) {
- const base = baseLedger ? indexLedger(baseLedger) : {byId: new Map(), byName: new Map()};
+ const base = baseLedger
+ ? indexLedger(baseLedger)
+ : {byId: new Map(), byName: new Map()};
const head = indexLedger(headLedger);
const live = roster || listComponents();
@@ -610,7 +620,8 @@ export function runRatchet(components, baseLedger, headLedger, roster = null) {
// Not a live component. It may still have a ledger row (a rename, say);
// otherwise check it as an unknown, which passes.
const rows = head.byName.get(item) || [];
- if (rows.length > 0) targets.push(...rows.map(e => ({component: item, package: e.package})));
+ if (rows.length > 0)
+ targets.push(...rows.map(e => ({component: item, package: e.package})));
else targets.push({component: item, package: null});
}
@@ -673,7 +684,11 @@ export function buildQueue(roster, limit = Infinity) {
const unaudited = roster
.filter(r => r.live && !isAudited(r.entry))
.sort((a, b) => a.component.localeCompare(b.component))
- .map(r => ({component: r.component, package: r.package, why: 'never audited'}));
+ .map(r => ({
+ component: r.component,
+ package: r.package,
+ why: 'never audited',
+ }));
const audited = roster
.filter(r => isAudited(r.entry))
@@ -711,32 +726,47 @@ export function buildStats(roster) {
const sections = {};
for (const id of SECTION_IDS) {
- const states = {scored: 0, limited: 0, not_measured: 0, na: 0, unpublished: 0};
+ const states = {
+ scored: 0,
+ limited: 0,
+ not_measured: 0,
+ na: 0,
+ unpublished: 0,
+ };
const scores = [];
for (const r of audited) {
const s = readSection(r.entry, id);
if (s.state in states) states[s.state]++;
- if (s.state === 'scored' && typeof s.score === 'number') scores.push(s.score);
+ if (s.state === 'scored' && typeof s.score === 'number')
+ scores.push(s.score);
}
sections[id] = {
weight: SECTION_WEIGHTS[id],
states,
mean: scores.length
- ? Math.round((scores.reduce((a, b) => a + b, 0) / scores.length) * 100) / 100
+ ? Math.round(
+ (scores.reduce((a, b) => a + b, 0) / scores.length) * 100,
+ ) / 100
: null,
n: scores.length,
};
}
- const dates = audited.map(r => r.entry.lastAudited).filter(Boolean).sort();
- const scores = audited.map(r => r.entry.score).filter(n => typeof n === 'number');
+ const dates = audited
+ .map(r => r.entry.lastAudited)
+ .filter(Boolean)
+ .sort();
+ const scores = audited
+ .map(r => r.entry.score)
+ .filter(n => typeof n === 'number');
return {
total: live.length,
audited: audited.length,
unaudited: live.length - audited.filter(r => r.live).length,
percentAudited: live.length
- ? Math.round((audited.filter(r => r.live).length / live.length) * 1000) / 10
+ ? Math.round((audited.filter(r => r.live).length / live.length) * 1000) /
+ 10
: 0,
byPackage: LEDGER_PACKAGES.reduce((acc, p) => {
const inPkg = live.filter(r => r.package === p.name);
@@ -748,9 +778,11 @@ export function buildStats(roster) {
}, {}),
grades,
openBlocks: audited.reduce((sum, r) => sum + openBlockCount(r.entry), 0),
- componentsWithBlocks: audited.filter(r => openBlockCount(r.entry) > 0).length,
+ componentsWithBlocks: audited.filter(r => openBlockCount(r.entry) > 0)
+ .length,
meanScore: scores.length
- ? Math.round((scores.reduce((a, b) => a + b, 0) / scores.length) * 10) / 10
+ ? Math.round((scores.reduce((a, b) => a + b, 0) / scores.length) * 10) /
+ 10
: null,
oldestAudit: dates[0] || null,
newestAudit: dates[dates.length - 1] || null,
@@ -900,7 +932,10 @@ Only record what you actually measured.`;
// ---------------------------------------------------------------------------
/** The reused shallow clone. One per user, not one per run. */
-export const WIKI_CACHE_DIR = path.join(os.tmpdir(), 'astryx-score-ledger-wiki');
+export const WIKI_CACHE_DIR = path.join(
+ os.tmpdir(),
+ 'astryx-score-ledger-wiki',
+);
function git(cwd, ...argv) {
return execFileSync('git', argv, {
@@ -933,7 +968,16 @@ export function ensureWikiClone(dir = WIKI_CACHE_DIR, remote = WIKI_REMOTE) {
git(dir, 'fetch', '--depth', '1', 'origin', WIKI_BRANCH);
} else {
fs.rmSync(dir, {recursive: true, force: true});
- git(os.tmpdir(), 'clone', '--depth', '1', '--branch', WIKI_BRANCH, remote, dir);
+ git(
+ os.tmpdir(),
+ 'clone',
+ '--depth',
+ '1',
+ '--branch',
+ WIKI_BRANCH,
+ remote,
+ dir,
+ );
}
git(dir, 'checkout', '-B', WIKI_BRANCH, `origin/${WIKI_BRANCH}`);
git(dir, 'reset', '--hard', `origin/${WIKI_BRANCH}`);
@@ -957,8 +1001,13 @@ export function wikiCommitUrl(sha, remote = WIKI_REMOTE) {
* added only when the bare name is ambiguous — `Chat` exists in core and lab,
* and a message that does not say which one is a message you cannot read back.
*/
-export function commitMessage(entry, {regression = null, ambiguous = false} = {}) {
- const name = ambiguous ? `${entry.package}/${entry.component}` : entry.component;
+export function commitMessage(
+ entry,
+ {regression = null, ambiguous = false} = {},
+) {
+ const name = ambiguous
+ ? `${entry.package}/${entry.component}`
+ : entry.component;
const subject =
`scores: ${name} ${entry.grade} (${fmtScore(entry.score)}), ` +
`rubric ${entry.rubricVersion}`;
@@ -981,9 +1030,13 @@ function unifiedDiff(before, after, label) {
fs.writeFileSync(a, before);
fs.writeFileSync(b, after);
try {
- execFileSync('diff', ['-u', '--label', `a/${label}`, '--label', `b/${label}`, a, b], {
- encoding: 'utf8',
- });
+ execFileSync(
+ 'diff',
+ ['-u', '--label', `a/${label}`, '--label', `b/${label}`, a, b],
+ {
+ encoding: 'utf8',
+ },
+ );
return '';
} catch (e) {
// `diff` exits 1 when the files differ. That is the expected path.
@@ -1067,7 +1120,9 @@ function commitAndPush(dir, file, apply, {attempts = 2} = {}) {
tryGit(root, 'rebase', '--abort');
lastFailure = pulled.out;
if (attempt < attempts) {
- console.log('score-ledger: the wiki moved under us — re-applying onto the new tip.');
+ console.log(
+ 'score-ledger: the wiki moved under us — re-applying onto the new tip.',
+ );
git(root, 'fetch', '--depth', '1', 'origin', WIKI_BRANCH);
git(root, 'reset', '--hard', `origin/${WIKI_BRANCH}`);
continue;
@@ -1081,9 +1136,13 @@ function commitAndPush(dir, file, apply, {attempts = 2} = {}) {
return {sha, url: wikiCommitUrl(sha), applied};
}
lastFailure = pushed.out;
- const raced = /non-fast-forward|fetch first|rejected|stale info/i.test(pushed.out);
+ const raced = /non-fast-forward|fetch first|rejected|stale info/i.test(
+ pushed.out,
+ );
if (!raced || attempt >= attempts) break;
- console.log('score-ledger: push rejected as non-fast-forward — re-applying and retrying once.');
+ console.log(
+ 'score-ledger: push rejected as non-fast-forward — re-applying and retrying once.',
+ );
git(root, 'fetch', '--depth', '1', 'origin', WIKI_BRANCH);
git(root, 'reset', '--hard', `origin/${WIKI_BRANCH}`);
}
@@ -1126,7 +1185,9 @@ export function isEvidenceItem(item) {
if (!item || typeof item !== 'object' || Array.isArray(item)) return false;
if (typeof item.label !== 'string') return false;
return Object.entries(item).every(
- ([k, v]) => EVIDENCE_FIELDS.has(k) && (v === undefined || v === null || typeof v === 'string'),
+ ([k, v]) =>
+ EVIDENCE_FIELDS.has(k) &&
+ (v === undefined || v === null || typeof v === 'string'),
);
}
@@ -1137,7 +1198,8 @@ export function isEvidenceItem(item) {
* the ratchet to every BLOCK in it.
*/
export function isBlocksShape(blocks) {
- if (!blocks || typeof blocks !== 'object' || Array.isArray(blocks)) return false;
+ if (!blocks || typeof blocks !== 'object' || Array.isArray(blocks))
+ return false;
return typeof blocks.count === 'number' && Array.isArray(blocks.open);
}
@@ -1170,7 +1232,8 @@ export function applyScorecard(existing, scorecard, {component, pkg}) {
...(existing || {}),
...scorecard,
};
- if (!next.package) throw new Error(`${component}: no package — pass --package`);
+ if (!next.package)
+ throw new Error(`${component}: no package — pass --package`);
// Checked before the grade, because a bare array (the shape a scorecard
// naturally takes if you think of blocks as a list) reads as zero open
// BLOCKs to `openBlockCount`. Left unchecked it does three things at once:
@@ -1205,8 +1268,10 @@ export function applyScorecard(existing, scorecard, {component, pkg}) {
'(any open BLOCK caps the grade at C)',
);
}
- if (!next.rubricVersion) throw new Error(`${component}: rubricVersion is required`);
- if (!next.lastAudited) throw new Error(`${component}: lastAudited is required`);
+ if (!next.rubricVersion)
+ throw new Error(`${component}: rubricVersion is required`);
+ if (!next.lastAudited)
+ throw new Error(`${component}: lastAudited is required`);
const mode = auditModePolicy(next.mode);
if (!mode) {
throw new Error(
@@ -1226,10 +1291,18 @@ export function applyScorecard(existing, scorecard, {component, pkg}) {
}
for (const b of blockList(next)) {
if (!b || typeof b.id !== 'string' || typeof b.summary !== 'string') {
- throw new Error(`${component}: every BLOCK needs {id, summary} (issue optional)`);
+ throw new Error(
+ `${component}: every BLOCK needs {id, summary} (issue optional)`,
+ );
}
- if (b.issue !== undefined && b.issue !== null && !Number.isInteger(b.issue)) {
- throw new Error(`${component}: BLOCK ${b.id} issue must be an integer or null`);
+ if (
+ b.issue !== undefined &&
+ b.issue !== null &&
+ !Number.isInteger(b.issue)
+ ) {
+ throw new Error(
+ `${component}: BLOCK ${b.id} issue must be an integer or null`,
+ );
}
if (b.issue === undefined) b.issue = null;
}
@@ -1280,7 +1353,10 @@ const flagValue = v => (typeof v === 'string' ? v : null);
function componentsFromArgs(args) {
const known = new Set(listComponents().map(c => c.component));
if (flagValue(args.components)) {
- return args.components.split(',').map(s => s.trim()).filter(Boolean);
+ return args.components
+ .split(',')
+ .map(s => s.trim())
+ .filter(Boolean);
}
if (flagValue(args.analysis)) {
const analysis = JSON.parse(fs.readFileSync(args.analysis, 'utf8'));
@@ -1306,7 +1382,9 @@ async function cmdCheck(args) {
return 0;
}
- const {ledger, error} = await loadLedger(flagValue(args.ledger) || DEFAULT_LEDGER_URL);
+ const {ledger, error} = await loadLedger(
+ flagValue(args.ledger) || DEFAULT_LEDGER_URL,
+ );
if (!ledger) {
// Never fail a pull request because the ledger could not be read. The
// ledger lives in the wiki; a fetch failure is infrastructure, not a
@@ -1371,10 +1449,16 @@ async function cmdCheck(args) {
const live = listComponents();
const standings = components.flatMap(name => {
const matches = resolveName(name, live);
- const targets = matches.length ? matches : [{component: name, package: null}];
+ const targets = matches.length
+ ? matches
+ : [{component: name, package: null}];
return targets.map(t => {
- const label = matches.length > 1 ? `${t.package}/${t.component}` : t.component;
- return standingFor(label, byId.get(`${t.package}/${t.component}`) || null);
+ const label =
+ matches.length > 1 ? `${t.package}/${t.component}` : t.component;
+ return standingFor(
+ label,
+ byId.get(`${t.package}/${t.component}`) || null,
+ );
});
});
const audited = standings.filter(s => s.status === 'audited');
@@ -1468,7 +1552,9 @@ async function cmdStats(args) {
`${name} ${stats.byPackage[name].audited}/${stats.byPackage[name].total}`,
).join(' · '),
);
- console.log(` Grades: A ${g.A} · B ${g.B} · C ${g.C} · D ${g.D} · F ${g.F}`);
+ console.log(
+ ` Grades: A ${g.A} · B ${g.B} · C ${g.C} · D ${g.D} · F ${g.F}`,
+ );
console.log(` Mean score: ${fmtScore(stats.meanScore)} (audited only)`);
console.log(
` Open BLOCKs: ${stats.openBlocks} across ${stats.componentsWithBlocks} components`,
@@ -1478,7 +1564,9 @@ async function cmdStats(args) {
);
console.log(` Rubric vers.: ${stats.rubricVersions.join(', ') || '—'}`);
if (stats.orphanRows.length) {
- console.log(` Orphan rows: ${stats.orphanRows.join(', ')} (no live component)`);
+ console.log(
+ ` Orphan rows: ${stats.orphanRows.join(', ')} (no live component)`,
+ );
}
console.log('');
console.log(' Sections (audited rows only)');
@@ -1507,7 +1595,9 @@ async function cmdStats(args) {
async function cmdRecord(args) {
const component = flagValue(args.record);
if (!component) {
- console.error('score-ledger --record <Component>: the component name is required');
+ console.error(
+ 'score-ledger --record <Component>: the component name is required',
+ );
return 1;
}
@@ -1515,12 +1605,15 @@ async function cmdRecord(args) {
// retry re-applies this same scorecard onto a newer ledger.
const src = flagValue(args.from);
if (!src) {
- console.error('score-ledger --record: --from <scorecard.json|-> is required');
+ console.error(
+ 'score-ledger --record: --from <scorecard.json|-> is required',
+ );
return 1;
}
let scorecard;
try {
- const text = src === '-' ? fs.readFileSync(0, 'utf8') : fs.readFileSync(src, 'utf8');
+ const text =
+ src === '-' ? fs.readFileSync(0, 'utf8') : fs.readFileSync(src, 'utf8');
scorecard = JSON.parse(text);
} catch (e) {
console.error(
@@ -1586,9 +1679,15 @@ async function cmdRecord(args) {
}
repoDir = ensureWikiClone();
ledgerPath = path.join(repoDir, LEDGER_FILENAME);
- console.log(`score-ledger: wiki clone at ${repoDir} (${WIKI_REMOTE}, ${WIKI_BRANCH})`);
+ console.log(
+ `score-ledger: wiki clone at ${repoDir} (${WIKI_REMOTE}, ${WIKI_BRANCH})`,
+ );
} else if (push) {
- const top = tryGit(path.dirname(path.resolve(ledgerPath)), 'rev-parse', '--show-toplevel');
+ const top = tryGit(
+ path.dirname(path.resolve(ledgerPath)),
+ 'rev-parse',
+ '--show-toplevel',
+ );
if (!top.ok) {
console.error(
`score-ledger --record: --push needs ${ledgerPath} to live in a git clone of the wiki ` +
@@ -1599,7 +1698,9 @@ async function cmdRecord(args) {
repoDir = top.out;
}
} catch (e) {
- console.error(`score-ledger --record: could not prepare the wiki clone — ${e.message}`);
+ console.error(
+ `score-ledger --record: could not prepare the wiki clone — ${e.message}`,
+ );
return 1;
}
@@ -1694,12 +1795,16 @@ async function cmdRecord(args) {
if (dryRun) {
const diff = unifiedDiff(applied.raw, applied.text, LEDGER_FILENAME);
- console.log(diff || `(${LEDGER_FILENAME} is already exactly this — no change)`);
+ console.log(
+ diff || `(${LEDGER_FILENAME} is already exactly this — no change)`,
+ );
console.log('--- commit message ---');
console.log(applied.message.subject);
if (applied.message.body) console.log(`\n${applied.message.body}`);
console.log('----------------------');
- console.log('score-ledger: --dry-run — nothing written, nothing committed, nothing pushed.');
+ console.log(
+ 'score-ledger: --dry-run — nothing written, nothing committed, nothing pushed.',
+ );
warnOnRecord(component, applied);
return 0;
}
@@ -1806,7 +1911,7 @@ export function issueBody(component, entry, block, repo = DEFAULT_REPO) {
'Resolving this requires:',
'',
`1. Re-run the audit for ${component} after the fix — the whole component, ` +
- "not the diff (the rubric's \"Grading a whole component\" section).",
+ 'not the diff (the rubric\'s "Grading a whole component" section).',
'2. Put the visual results in the PR description — before/after screenshots of the ' +
'affected states. The rendered-design section is graded from those.',
'3. Update the ledger with the new score and clear this BLOCK ' +
@@ -1831,14 +1936,18 @@ export function issueBody(component, entry, block, repo = DEFAULT_REPO) {
async function cmdFileIssues(args) {
const component = flagValue(args['file-issues']);
if (!component) {
- console.error('score-ledger --file-issues <Component>: the component name is required');
+ console.error(
+ 'score-ledger --file-issues <Component>: the component name is required',
+ );
return 1;
}
const push = Boolean(args.push);
let ledgerPath = flagValue(args.ledger);
let repoDir = null;
if (ledgerPath && isUrl(ledgerPath)) {
- console.error('score-ledger --file-issues: --ledger must be a local path — it writes back.');
+ console.error(
+ 'score-ledger --file-issues: --ledger must be a local path — it writes back.',
+ );
return 1;
}
try {
@@ -1852,9 +1961,15 @@ async function cmdFileIssues(args) {
}
repoDir = ensureWikiClone();
ledgerPath = path.join(repoDir, LEDGER_FILENAME);
- console.log(`score-ledger: wiki clone at ${repoDir} (${WIKI_REMOTE}, ${WIKI_BRANCH})`);
+ console.log(
+ `score-ledger: wiki clone at ${repoDir} (${WIKI_REMOTE}, ${WIKI_BRANCH})`,
+ );
} else if (push) {
- const top = tryGit(path.dirname(path.resolve(ledgerPath)), 'rev-parse', '--show-toplevel');
+ const top = tryGit(
+ path.dirname(path.resolve(ledgerPath)),
+ 'rev-parse',
+ '--show-toplevel',
+ );
if (!top.ok) {
console.error(
`score-ledger --file-issues: --push needs ${ledgerPath} to live in a git clone of the ` +
@@ -1865,7 +1980,9 @@ async function cmdFileIssues(args) {
repoDir = top.out;
}
} catch (e) {
- console.error(`score-ledger --file-issues: could not prepare the wiki clone — ${e.message}`);
+ console.error(
+ `score-ledger --file-issues: could not prepare the wiki clone — ${e.message}`,
+ );
return 1;
}
@@ -1876,7 +1993,9 @@ async function cmdFileIssues(args) {
return 1;
}
const matches = resolveName(component);
- const pkg = flagValue(args.package) || (matches.length === 1 ? matches[0].package : null);
+ const pkg =
+ flagValue(args.package) ||
+ (matches.length === 1 ? matches[0].package : null);
if (!pkg) {
console.error(
`score-ledger --file-issues: pass --package for ${component} (it resolves to ` +
@@ -1886,7 +2005,9 @@ async function cmdFileIssues(args) {
}
const entry = indexLedger(ledger).byId.get(`${pkg}/${component}`);
if (!isAudited(entry)) {
- console.error(`score-ledger: ${component} has no audited row — record it first.`);
+ console.error(
+ `score-ledger: ${component} has no audited row — record it first.`,
+ );
return 1;
}
const mode = auditModePolicy(entry.mode);
@@ -1900,7 +2021,10 @@ async function cmdFileIssues(args) {
}
const gh = (...argv) =>
- execFileSync('gh', argv, {encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe']}).trim();
+ execFileSync('gh', argv, {
+ encoding: 'utf8',
+ stdio: ['ignore', 'pipe', 'pipe'],
+ }).trim();
const filed = [];
for (const block of blockList(entry)) {
@@ -1908,20 +2032,41 @@ async function cmdFileIssues(args) {
// Idempotent: never re-file. Reopen if the issue was closed while the
// BLOCK is still on the row.
if (args['dry-run']) {
- console.log(` ${block.id}: already filed as #${block.issue} — skipping`);
+ console.log(
+ ` ${block.id}: already filed as #${block.issue} — skipping`,
+ );
continue;
}
try {
- const state = gh('issue', 'view', String(block.issue), '--repo', repo, '--json', 'state', '--jq', '.state');
+ const state = gh(
+ 'issue',
+ 'view',
+ String(block.issue),
+ '--repo',
+ repo,
+ '--json',
+ 'state',
+ '--jq',
+ '.state',
+ );
if (state === 'CLOSED') {
- gh('issue', 'reopen', String(block.issue), '--repo', repo, '--comment',
- `Reopening: \`${block.id}\` is still an open BLOCK on the ${component} ledger row.`);
+ gh(
+ 'issue',
+ 'reopen',
+ String(block.issue),
+ '--repo',
+ repo,
+ '--comment',
+ `Reopening: \`${block.id}\` is still an open BLOCK on the ${component} ledger row.`,
+ );
console.log(` ${block.id}: reopened #${block.issue}`);
} else {
console.log(` ${block.id}: already filed as #${block.issue}`);
}
} catch (e) {
- console.log(`::warning::score-ledger: could not check issue #${block.issue}: ${e.message}`);
+ console.log(
+ `::warning::score-ledger: could not check issue #${block.issue}: ${e.message}`,
+ );
}
continue;
}
@@ -1931,10 +2076,23 @@ async function cmdFileIssues(args) {
console.log(`\n--- would file ---\n${title}\n\n${body}\n`);
continue;
}
- const url = gh('issue', 'create', '--repo', repo, '--title', title, '--label', 'hardening', '--body', body);
+ const url = gh(
+ 'issue',
+ 'create',
+ '--repo',
+ repo,
+ '--title',
+ title,
+ '--label',
+ 'hardening',
+ '--body',
+ body,
+ );
const number = Number(url.split('/').pop());
if (!Number.isInteger(number)) {
- console.error(`score-ledger: could not parse an issue number out of "${url}"`);
+ console.error(
+ `score-ledger: could not parse an issue number out of "${url}"`,
+ );
return 1;
}
block.issue = number;
@@ -1943,7 +2101,8 @@ async function cmdFileIssues(args) {
}
if (!filed.length) {
- if (args['dry-run']) console.log('score-ledger: --dry-run — no issue was created.');
+ if (args['dry-run'])
+ console.log('score-ledger: --dry-run — no issue was created.');
return 0;
}
@@ -1954,7 +2113,9 @@ async function cmdFileIssues(args) {
if (!push) {
fs.writeFileSync(ledgerPath, `${JSON.stringify(ledger, null, 2)}\n`);
- console.log(`score-ledger: wrote ${ledgerPath} — commit and push it, or re-run with --push.`);
+ console.log(
+ `score-ledger: wrote ${ledgerPath} — commit and push it, or re-run with --push.`,
+ );
return 0;
}
@@ -1979,7 +2140,10 @@ async function cmdFileIssues(args) {
if (n && !block.issue) block.issue = n;
}
fresh.updated = new Date().toISOString().slice(0, 10);
- return {text: `${JSON.stringify(fresh, null, 2)}\n`, message: {subject, body: ''}};
+ return {
+ text: `${JSON.stringify(fresh, null, 2)}\n`,
+ message: {subject, body: ''},
+ };
};
try {
@@ -2013,7 +2177,10 @@ async function main() {
}
// Only run when invoked directly, so tests can import the pure functions.
-if (process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1])) {
+if (
+ process.argv[1] &&
+ fileURLToPath(import.meta.url) === path.resolve(process.argv[1])
+) {
main().then(
code => process.exit(code),
err => {
diff --git a/scripts/sync-internal-deps.mjs b/scripts/sync-internal-deps.mjs
index f5f3573b86..fe02e43e9c 100755
--- a/scripts/sync-internal-deps.mjs
+++ b/scripts/sync-internal-deps.mjs
@@ -1,27 +1,18 @@
#!/usr/bin/env node
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * Post-`changeset version` internal-dependency sync — `node scripts/sync-internal-deps.mjs`.
+ * Declared-version internal-dependency sync — `node scripts/sync-internal-deps.mjs`.
*
- * All published packages ship in lockstep at the same version (the `fixed`
- * group in .changeset/config.json). Internal `@astryxdesign/*` packages
- * reference each other with exact version specifiers (e.g. a theme's
- * `@astryxdesign/core` peer, or a theme's `@astryxdesign/cli` devDependency).
+ * All stable packages already carry the fixed-group version declared by main and
+ * frozen at the cut. Internal `@astryxdesign/*` packages reference each other
+ * with exact version specifiers (for example, a theme's `@astryxdesign/core`
+ * peer or `@astryxdesign/cli` devDependency).
*
- * We set `bumpVersionsWithWorkspaceProtocolOnly: true` so a breaking 0.x
- * release stays on the minor `0.(x+1).0` instead of cascading the whole fixed
- * group to `1.0.0` (an out-of-range peer would otherwise force every
- * dependent to a major bump). The trade-off is that Changesets then only
- * rewrites `workspace:`-protocol specifiers on version — it leaves our exact
- * `@astryxdesign/*` specifiers pointing at the previous version.
- *
- * This script closes that gap: after the bump, every exact-version internal
- * `@astryxdesign/*` specifier (in dependencies, devDependencies, and
- * peerDependencies of every workspace package) is repinned to the freshly
- * bumped version of the referenced package. Non-exact specifiers (`*`,
- * ranges, `workspace:*`, etc.) are left untouched — only literal exact
- * versions are managed, which is exactly the set Changesets used to keep in
- * sync before the workspace-protocol-only setting.
+ * The custom release-branch versioner keeps stable package versions at that
+ * declaration while writing affected changelogs. This script repins every exact
+ * internal specifier in dependencies, devDependencies, and peerDependencies to
+ * the referenced package's declared version. Non-exact specifiers (`*`, ranges,
+ * `workspace:*`, and similar) remain untouched.
*/
import fs from 'node:fs';
@@ -52,7 +43,7 @@ for (const dir of PKG_DIRS) {
}
}
-// Map each internal package name -> its current (post-bump) version.
+// Map each internal package name -> its current declared version.
const versionByName = new Map();
for (const pkgPath of pkgPaths) {
const pkg = read(pkgPath);