docs(CLAUDE.md): document required surfaces for MidenClient + React-SDK API changes#127
Merged
Merged
Conversation
…DK API changes Adds a 'Documenting public-API changes' section to the repo CLAUDE.md that maps every doc surface a contributor has to touch when changing the public API of either the MidenClient resource layer (web-client) or the React SDK. Replaces the vague 'update relevant per-package CLAUDE.md' bullet in the Contributing checklist with a precise mapping table. Surfaces enumerated for each side: TS types (api-types.d.ts), resource JSDoc, README narrative, per-package CLAUDE.md, root CHANGELOG, and the typedoc curation file when applicable. Includes triggers (when to touch each), conventions (terse tone, no speculative docs, cross-link PRs, one source of truth per fact), and a doc-only-PR escape hatch. Triggered by web-sdk#31, where the new transactions.batch API needed docs in five different places — easy to miss without an explicit map.
WiktorStarczewski
added
the
no changelog
…ess map The first pass missed three load-bearing surfaces of the public-docs pipeline: 1. The canonical user-facing site at https://docs.miden.xyz, hosted from 0xMiden/miden-docs, ingesting upstream repos via deploy-docs.yml's docs/external/src/* → docs/builder/<repo>/ copy step. 2. The typedoc-generated API reference at docs/typedoc/web-client/, which is regenerated from docs-entry.d.ts and verified by CI via git diff --exit-code (drift fails the build). 3. docs/external/src/ as the canonical narrative source the deploy-docs workflow ingests. After the web/WASM split this directory needs to exist in this repo (currently a gap — miden-client's docs/external/src no longer carries web/React content), and pages under it need to be added when shipping new public capabilities. Adds a 'Where the docs are published' table at the top of the doc-process section, plus a typedoc-regen workflow snippet, plus README ⇄ Docusaurus parity rule. Expands both the MidenClient and React SDK surface tables to call out docs/external/src/ and docs/typedoc/web-client/ explicitly, and updates the contributing-checklist item 3 to enumerate them.
Newer nightly clippy fires `useless_borrows_in_formatting` on the pre-existing &account_id.to_string() pattern. The lint started firing between origin/main's last green CI run (2026-04-30) and today — nightly clippy rolls forward unpinned in this repo's Makefile. Same fix as web-sdk#31's commit 7f9cf07. Including it here so the CLAUDE.md doc-process change isn't blocked by an unrelated baseline lint regression on the target branch.
After dropping the redundant & in commit 2b27e16, the call fits on one line and cargo +nightly fmt --check fails until we collapse the multi-line layout. Same pattern as the next-targeted PR (which already had it on one line).
WiktorStarczewski
added a commit
that referenced
this pull request
May 4, 2026
The CI step "Check that web client documentation is up-to-date" runs `pnpm typedoc` to regenerate fresh and then `git diff --exit-code` over docs/typedoc/web-client/. Since the dir hasn't been tracked since the web/WASM split, the diff has nothing to compare and the step is a warning-only smoke test — typedoc is intermediate build output, not source. Reverts the 107-file autogen commit from cd4f75d. Keeps the hand-written narrative + scaffolding under docs/external/src/. Will adjust the doc-process rule in CLAUDE.md (PRs #126/#127) to match this policy.
This was referenced May 4, 2026
WiktorStarczewski
added a commit
that referenced
this pull request
May 5, 2026
The first pass of the doc-process section (#126/#127) prescribed 'regenerate typedoc and commit the diff' for any change to the curated public surface. That guidance was wrong: the in-repo 'Check that web client documentation is up-to-date' CI step runs typedoc and then a git diff --exit-code over the regenerated tree, but the directory hasn't been tracked since the web/WASM split — so the diff is empty and the step is a warning-only smoke test, not a gate. typedoc output is build artifact, not source. Updates four spots in the doc-process section: - 'Typedoc — keep in sync with the public API surface' → 'Typedoc — regenerated by CI, don't commit' - The MidenClient surface table row for docs/typedoc/web-client/ now reads 'Don't commit. Regenerated by CI...' - The Conventions bullet 'Regenerate typedoc' became 'Don't commit typedoc' - Contributing checklist item 3 mirrors that Triggered by web-sdk#31 audit feedback: noticed the autogen tree shouldn't have been committed there either. Companion .gitignore addition lands separately on web-sdk#31.
WiktorStarczewski
added a commit
that referenced
this pull request
May 5, 2026
The first pass of the doc-process section (#126/#127) prescribed 'regenerate typedoc and commit the diff' for any change to the curated public surface. That guidance was wrong: the in-repo 'Check that web client documentation is up-to-date' CI step runs typedoc and then a git diff --exit-code over the regenerated tree, but the directory hasn't been tracked since the web/WASM split — so the diff is empty and the step is a warning-only smoke test, not a gate. typedoc output is build artifact, not source. Updates four spots in the doc-process section: - 'Typedoc — keep in sync with the public API surface' → 'Typedoc — regenerated by CI, don't commit' - The MidenClient surface table row for docs/typedoc/web-client/ now reads 'Don't commit. Regenerated by CI...' - The Conventions bullet 'Regenerate typedoc' became 'Don't commit typedoc' - Contributing checklist item 3 mirrors that Triggered by web-sdk#31 audit feedback: noticed the autogen tree shouldn't have been committed there either. Companion .gitignore addition lands separately on web-sdk#31.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a
## Documenting public-API changessection to repoCLAUDE.mdthat maps every doc surface a contributor has to touch when changing the public API of either the MidenClient resource layer (web-client) or the React SDK.Replaces the vague "update relevant per-package CLAUDE.md" bullet in the Contributing checklist with an explicit table for each side: api-types JSDoc → resource impl JSDoc → README narrative → per-package CLAUDE.md → root CHANGELOG (and
docs-entry.d.tswhen a new WASM class becomes public).Why
While shipping
transactions.batchin #31, the new API needed docs in five places — easy to miss without an explicit map. This PR is the map.Extracted from #31 so the doc-process change can land independently and apply to both
mainandnextchannels in parallel.Companion PR
Same change against the other long-lived branch.
Test plan