Skip to content

docs: use ESA npm tag in generated install instructions - #3742

Open
rachitm022 wants to merge 2 commits into
17.x-esafrom
fix/esa-install-tag-docs
Open

rachitm022 wants to merge 2 commits into
17.x-esafrom
fix/esa-install-tag-docs

Conversation

@rachitm022

Copy link
Copy Markdown
Collaborator

Summary

The generated llms.txt for the ESA prerelease currently recommends npm install @adcp/sdk@esa. The 17.x-esa release workflow publishes under the adcp-3.3-esa npm tag, so the generated instruction would fail after release.

Map only the esa prerelease identifier to the configured npm tag. Beta and stable install instructions keep their existing behavior. An empty changeset keeps this documentation generator fix out of the release version calculation.

Verification

  • node --test test/release-version-docs.test.js — 4 passed; release simulation checks both @beta and @adcp-3.3-esa.
  • npm run generate-agent-docs and npm run ci:docs-check — checked-in beta docs are current; the release simulation regenerates ESA docs.
  • npm run typecheck
  • npx prettier --check scripts/generate-agent-docs.ts test/release-version-docs.test.js
  • npx changeset status --since=origin/17.x-esa

This should merge into 17.x-esa before the generated version PR #3741; Changesets can then refresh that PR with the correct install command. This PR does not publish a package.

symlinkSync(path.join(ROOT, 'compliance', 'cache'), path.join(worktree, 'compliance', 'cache'), 'dir');

const originalVersion = JSON.parse(readFileSync(path.join(worktree, 'package.json'), 'utf8')).version;
run('npm', ['run', 'generate-agent-docs']);

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Medium: This pre-changeset version assertion hardcodes @beta, coupling it to the current 17.0.0-beta.22 base. .changeset/pre.json is already on tag esa, so the first release in this lane lands 17.0.0-esa.N on main. From that point every subsequent run branches from an esa-versioned base, generate-agent-docs emits @adcp/sdk@adcp-3.3-esa, and this line fails. Derive the expected tag from originalVersion (read before changeset version) instead of pinning @beta — the esa branch at L150-155 already does the robust thing conditionally.

@aao-secretariat aao-secretariat Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ladon verdict: Approve

Approve — ESA-lane prep PR, clean with one non-blocking medium.

The core change in scripts/generate-agent-docs.ts maps the prerelease tag esa → dist-tag adcp-3.3-esa while preserving existing @beta and stable (major.minor) behavior — logic is correct. The empty changeset is appropriate: a doc-generation script with no published-artifact impact (not under src/lib/**, bin/**, build-affecting scripts/** in a changeset-relevant way, or a package.json files path) does not require a release entry, so the changeset-vs-wire-impact gate is not triggered.

Medium findings

  • test/release-version-docs.test.js:139 — Pre-version assertion hardcodes @beta; will fail once the first esa release lands on main (base version becomes -esa.N). Prefer deriving the expected tag from originalVersion. Worth fixing but not blocking.

Decision path: no critical/high findings (row 1 n/a); gated_paths false (row 2 n/a); high_risk false (rows 3/5 n/a); single medium is test/correctness category, not data-loss/schema/infra (row 4 n/a); no prior escalation (row 6 n/a); no no-auto-approve team match (row 7 n/a); only 1 medium finding, well under the 3-medium threshold (row 8 n/a). Falls through to row 9 → approve.

Medium findings

  • test/release-version-docs.test.js:139 — Pre-version assertion hardcodes @beta, breaks once esa lane lands on main

@aao-secretariat aao-secretariat Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ladon verdict: Approve

Approve.

Clean, minimal fix to the doc-generator script. scripts/generate-agent-docs.ts:590-592 factors out the prerelease tag and remaps only esa → adcp-3.3-esa; beta and stable install strings are unchanged, so the generated npm install @adcp/sdk@... line (L624) now matches the real ESA npm dist-tag instead of the non-existent @esa. The new test adds worktree pre/post-changeset version assertions covering both @beta and @adcp-3.3-esa.

Checked:

  • No critical/high/medium findings from the reviewer.
  • Empty changeset is correct: this is a doc-generator script that does not alter published runtime (src/lib/** / bin/** / published files untouched), so changeset-vs-wire-impact rule does not require a bump.
  • No witness-not-translator, version-pathway, or transport-client concerns — no wire-shape code touched.
  • high_risk false; gated_paths false; no no-auto-approve team match; no prior decision.

Decision table: none of rows 1–8 fire (no findings, no gates) → row 9 approve.

Non-blocking nit (not tracked): adcp-3.3-esa hard-codes the 3.3 train rather than deriving from ADCP_VERSION — will need a touch if the ESA train advances.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant