Skip to content

docs(architecture): audit CLI and distribution group against implementation - #4801

Open
ggbdpq wants to merge 1 commit into
apache:mainfrom
ggbdpq:docs/audit-cli-dist-a8
Open

docs(architecture): audit CLI and distribution group against implementation#4801
ggbdpq wants to merge 1 commit into
apache:mainfrom
ggbdpq:docs/audit-cli-dist-a8

Conversation

@ggbdpq

@ggbdpq ggbdpq commented Sep 4, 2026

Copy link
Copy Markdown
Contributor

Summary

Audits the CLI and distribution group (5 documents) from #3522 against the current implementation (22715e8). No drift found in any of the five; the four hand-maintained documents gain the standard frontmatter block with last_verified, while the generated inventory document is left byte-identical to its base revision.

  • docs/cli-distribution.md — enforcement artifacts exist: scripts/product-release-identity.mjs (with the RELEASE.json identity fields such as sourceCommit), .github/workflows/release.yml, root DISCLAIMER-WIP. The bin/maka / libexec/** names are archive-layout outputs, as the document itself scopes them.
  • docs/cli-npm-release.md + .zh-CN.md — every referenced workflow resolves (npm-publication.yml, desktop-nightly.yml, release-cli-stage.yml, release-cli-finalize.yml), and the pair stays in lockstep on the Trusted Publisher / OIDC staging / 2FA / Finalize provenance flow.
  • docs/windows-support.md — the installer name matches scripts/desktop-release-targets.mjs (Maka-${version}-win-x64.exe); the AppContainer filesystem-worker claim matches the tree; tracking issue roadmap(windows): make Windows a supported platform #2142 is open as stated.
  • docs/windows-test-inventory.md — verified with the repository's own check: npm run windows:inventory passes ("Windows test skip inventory is current (76 declarations)"). The document itself stays untouched: it is generated by scripts/windows-test-inventory.mjs --write, and its --check compares the file byte-for-byte with regenerated output, so hand-added frontmatter on it fails CI (caught by the first CI run; the file is restored to its base revision here).

Verification

Claim Command / route Result
Identity/workflow artifacts ls / grep on the named scripts and .github/workflows/ all resolve
RELEASE.json identity fields grep scripts/product-release-identity.mjs sourceCommit etc. present
npm-release zh/en lockstep heading + flow-keyword comparison 10 sections each; key flow terms parallel
Windows installer name grep scripts/desktop-release-targets.mjs Maka-${version}-win-x64.exe exact
Windows inventory currency npm run windows:inventory exit 0, 76 declarations current
Generated inventory untouched node scripts/windows-test-inventory.mjs --check on the branch exit 0, byte-identical to base
#2142 status issue API open
Format / headers npm run format:check / npm run check:asf-headers exit 0 / changed files pass

Not re-verified (external to the repository): the winget package id BurntSushi.ripgrep.MSVC in the windows-support install steps is an upstream registry reference.

AI use

Prepared with ZCode (GLM-5.3-Flash): read all five documents, bulk-verified every path-like reference, ran the repository's own inventory check, and added the frontmatter to the hand-maintained documents. The commit carries the Generated-by trailer.

Checklist

  • One subsystem group only (CLI and distribution, 5 documents)
  • Refs #3522 in the commit message
  • Paired translations move together (npm-release pair, translation_status: synced)
  • last_verified set to the audit date (2026-09-04)
  • Docs only, no code changes

@github-actions github-actions Bot added the effort/S Under 100 readable lines label Sep 4, 2026
@ggbdpq
ggbdpq force-pushed the docs/audit-cli-dist-a8 branch from 7645ad9 to 0c29bd8 Compare September 4, 2026 22:48
@ggbdpq ggbdpq changed the title docs: audit CLI and distribution group against implementation docs(architecture): audit CLI and distribution group against implementation Sep 4, 2026
…tation

Audit the five CLI and distribution documents from the apache#3522
documentation audit against the current implementation (22715e8).

No drift found in any of the five. Highlights of what was verified:

- cli-distribution.md: every named enforcement artifact exists
  (scripts/product-release-identity.mjs with the RELEASE.json identity
  fields, .github/workflows/release.yml, DISCLAIMER-WIP); the archive
  layout names are packaging-time outputs as the document describes.
- cli-npm-release.md + zh-CN: the workflow filenames resolve
  (npm-publication.yml, desktop-nightly.yml, release-cli-stage.yml,
  release-cli-finalize.yml), and the pair stays in lockstep on the
  Trusted Publisher / OIDC / 2FA / Finalize flow.
- windows-support.md: the installer name matches
  scripts/desktop-release-targets.mjs (`Maka-${version}-win-x64.exe`);
  the AppContainer filesystem-worker claim matches the tree; tracking
  issue apache#2142 is open as stated.
- windows-test-inventory.md: `npm run windows:inventory` (the repo's
  own check) passes with "Windows test skip inventory is current
  (76 declarations)".

The four hand-maintained documents gained the standard frontmatter
block with `last_verified` (the npm-release pair keeps
`translation_status: synced`). windows-test-inventory.md stays
frontmatter-free on purpose: it is generated by
`scripts/windows-test-inventory.mjs --write`, and its `--check`
compares the file byte-for-byte with regenerated output, so manual
frontmatter on it fails CI.

Refs apache#3522

Generated-by: GLM-5.3-Flash (ZCode)
@ggbdpq
ggbdpq force-pushed the docs/audit-cli-dist-a8 branch from 0c29bd8 to 76588b2 Compare September 4, 2026 23:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

effort/S Under 100 readable lines

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant