Repository navigation
docs: reshape every sub-project README to one reference shape - #263
Open
fernandomg wants to merge 10 commits into
Open
fernandomg wants to merge 10 commits into
fernandomg wants to merge 10 commits into
Conversation
- intro, pointer paragraph and install blocks first - one usage block with a comment per case; the ledger escape hatch in its own section - scripts and the state-machine rationale last, under Working on the package - the gap table and the lighter-store note move to architecture.md; partylayer goes - src/index.ts drops the header comment that sent readers to the README for the rationale
- each session-dependent hook's example opens with the guard it needs, as an if-return - useConnect says closing the picker rejects with ConnectCancelledError - ConnectCancelledError says when error records a close, and to detect a cancel on the rejection
- Installation with npm and pnpm blocks naming the full peer set - caveats as GitHub alerts; the flash note links the Theme runtime section - package links go to the package root - Scripts and Build & dev loop move last, under Working on the package - architecture.md records the two-Reacts case
- npm and pnpm install blocks at the top of Usage - links to canton-dappbooster point at the package root
- README: requirements, both package managers, the flags table, the npm separator note - README: Installer development dropped - starter: install and dev per package manager, one block each - daml-tooling and localnet: scripts as a Script table, caveats as alerts
- the dApp menu stays 2.5 s; the idle cap is 3 s so that pause survives - the command types at 0.05 s per character - the recording ends a second into the install spinner, or when the install finishes - the time limit is gone
- kit blockquote, one-paragraph intro, pointers to daml/README.md, architecture.md and CLAUDE.md - NOTE on why the model ships as source: it must be built against the network's Splice - How it works: a sequence diagram of create, accept and claim with the approvals per party - Run the app split into the installer path and your own network, scripts as a table - Use the app: wallet, the wallet-kernel WARNING and the faucet as subsections - Working on the package: the package.json scripts and how the installer and the monorepo use it - daml/README.md: one line per paragraph, the redeploy caveat as a WARNING, no script internals - CLAUDE.md: the daml/ placement rule, moved out of the daml README
- kit blockquote, one-paragraph intro, the vendored DARs and their sources, the doc pointers - NOTE on why there is no daml/: nothing in the DARs depends on the network's Splice - How it works: a sequence diagram of create, accept and claim with one approval per write - Run the app split into the installer path and your own network, scripts as a table - Use the app: wallet and the faucet as subsections - Working on the package: the package.json scripts, stack:up and stack:down included
- CLAUDE.md: a README introduces, gets the reader running and points on; caveats as alerts - CLAUDE.md: no document is an orphan, every .md reachable from the root README by links or names - CONTRIBUTING.md: the installer's try and try:clean, and a Where to read next section - README.md: a Contributing link, the one root README edit this change makes - architecture.md: each package row links its own architecture.md
…starter - the installer ends by installing the project, which the kit libraries need Node 24.15.0 for - the starter declares the same engines floor the examples and the libraries do - the README names one Node version instead of one for the installer and one for the project
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
There was a problem hiding this comment.
Note
Copilot was unable to complete this review at the selected tier due to model policy or plan restrictions.
🟡 Changes recommended
A root README.md edit is included even though the repo guidance discourages changing the root README unless explicitly requested, so this should be reverted or relocated to the appropriate contributing/subproject documentation before approval.
1 open issue
What changed in this PR
This pull request standardizes documentation across the monorepo by reshaping sub-project READMEs into a consistent reference structure (what it is / how to run / where to read next / maintainer notes last), while also refreshing a few related docs and aligning Node engine requirements (notably for canton-create and its starter scaffold).
Changes:
- Reshapes package/example READMEs to a consistent format (npm vs pnpm fences, script tables, alert-style caveats, and “read next” links to
architecture.md/CLAUDE.md). - Updates
canton-connectdocumentation and JSDoc examples to consistently demonstrate session/ready guards and clarifies lifecycle/cancellation guidance. - Aligns Node engine requirements to
>=24.15.0for the installer and starter scaffold and refreshes the installer demo recording/artifact.
This pull request requires changes.
| File | Summary |
|---|---|
README.md |
Adds a Contributing pointer to CONTRIBUTING.md (note: review feedback suggests avoiding root README changes unless explicitly requested). |
example-dapps/token-vesting/README.md |
Reshapes README to the reference structure; adds “How it works” Mermaid sequence and standardized run/use sections. |
example-dapps/amulet-vesting/README.md |
Reshapes README to the reference structure; adds “How it works” Mermaid sequence and standardized run/use sections. |
example-dapps/amulet-vesting/daml/README.md |
Tightens Daml build/deploy guidance and moves key caveats into alert-style callouts. |
example-dapps/amulet-vesting/CLAUDE.md |
Adds local authoring guidance about the Daml package folder layout decision. |
CONTRIBUTING.md |
Adds the installer “try” workflow documentation and a “Where to read next” map. |
CLAUDE.md |
Clarifies what READMEs are for and adds repo-wide “no orphan docs” guidance. |
canton-theme/README.md |
Standardizes install/usage instructions and normalizes links. |
canton-dappbooster/README.md |
Reshapes to the reference README structure (installation, usage, and maintainer/dev content last). |
canton-dappbooster/architecture.md |
Adds an operational note about dual-React pitfalls and a resolve.dedupe mitigation. |
canton-create/scripts/record-demo.ts |
Adjusts demo capture timings to keep the dApp menu visible longer and end on the install spinner. |
canton-create/scaffold/starter/README.md |
Reshapes starter README; splits npm/pnpm instructions and consolidates “learn more” links. |
canton-create/scaffold/starter/package.json |
Aligns the scaffolded starter’s Node engine floor to >=24.15.0. |
canton-create/scaffold/localnet/README.md |
Reshapes localnet README to the standard format, including scripts table and caution note. |
canton-create/scaffold/daml-tooling/README.md |
Reshapes Daml tooling README and adds a redeploy warning alert. |
canton-create/README.md |
Reshapes installer README; updates requirements and adds clarifying notes/links. |
canton-create/package.json |
Raises canton-create Node engine requirement to >=24.15.0 (review feedback flags this as a user-visible compatibility change needing reconciliation in PR messaging). |
canton-create/demo.svg |
Updates the checked-in demo artifact to match the refreshed recording. |
canton-connect/src/index.ts |
Removes an outdated/redundant header comment from the barrel export file. |
canton-connect/src/hooks/useWalletStatus.ts |
Tweaks JSDoc example formatting/guarding for readability and consistency. |
canton-connect/src/hooks/useSignMessage.ts |
Updates JSDoc example to include a session/account guard pattern. |
canton-connect/src/hooks/usePartyType.ts |
Updates JSDoc example to gate calls on readiness (isReady). |
canton-connect/src/hooks/useLedger.ts |
Updates JSDoc example to gate ledger usage on readiness (isReady). |
canton-connect/src/hooks/useExecute.ts |
Updates JSDoc example to include session/account guard usage. |
canton-connect/src/hooks/useConnect.ts |
Clarifies cancellation behavior in JSDoc. |
canton-connect/src/hooks/useAccount.ts |
Updates JSDoc example to gate rendering/usage based on account presence. |
canton-connect/src/connectError.ts |
Expands cancellation docs for ConnectCancelledError (review feedback requests wording alignment with the example regarding reliable cancellation signals). |
canton-connect/README.md |
Reshapes README to the reference structure and refreshes usage guidance and scripts. |
canton-connect/architecture.md |
Expands lifecycle/state-machine rationale and documents SDK gaps more explicitly. |
architecture.md |
Adds “see also” pointers to subprojects’ architecture.md docs. |
Review effort: Balanced
This branch was successfully deployed
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
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
Closes #255
Each sub-project README had grown its own shape: maintainer notes before usage, peers explained in prose, caveats buried in paragraphs, scripts listed three different ways, and pages nothing linked to. A reader trying a package met whichever one its last author left.
canton-dappbooster/README.mdis now the reference shape, and every other README follows it: what the unit is, how to run it, where to read next, maintainer content last.Changes
architecture.mdandCLAUDE.mdCLAUDE.mdstates what a README is for and that no.mdmay be an orphan;CONTRIBUTING.mdgains the installer'stryloop and a reading mapDeviations
pnpm devAcceptance criteria
The issue states none.
Test plan
Automated tests
pnpm docs:checkcompiles every fence in the two library READMEs and every JSDoc example.pnpm -C canton-connect testandpnpm -C canton-create test.Manual verification
.mdin the repo should be reachable from the root README.Breaking changes
None.
Checklist
Screenshots
None.