ci(docs): collect documentation writer review data#7343
Conversation
|
Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually. Contributors can view more details about this message here. |
📝 WalkthroughWalkthroughAdds a Documentation Writer Review receipt contract, a TypeScript checker and reporting CLI, contributor guidance, tests, npm scripts, and an advisory GitHub Actions workflow that validates receipts against pull request and repository revisions. ChangesDocumentation review receipts
Estimated code review effort: 4 (Complex) | ~45 minutes Sequence Diagram(s)sequenceDiagram
participant PullRequest as Pull request
participant Workflow as GitHub Actions workflow
participant DocsReviewReceipt as docs-review-receipt.mts
participant Repository as Repository
Workflow->>Repository: Read changed files and AGENTS.md blob SHA
Workflow->>DocsReviewReceipt: Run receipt check with PR event data
DocsReviewReceipt->>PullRequest: Parse Documentation Writer Review section
DocsReviewReceipt->>Repository: Compare recorded revision metadata
DocsReviewReceipt-->>Workflow: Return receipt status and advisory findings
Suggested labels: 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Comment |
PR Review Advisor — InformationalAdvisor assessment: Informational / medium confidence Model lanes
Nemotron output stays in workflow artifacts and does not change the assessment above. E2E guidanceAdvisory only. E2E / PR Gate selects and runs jobs independently. Recommended E2E: This automated review informs maintainers. Warnings and suggestions do not require a response. A maintainer decides whether to merge. |
|
🌿 Preview your docs: https://nvidia-preview-pr-7343.docs.buildwithfern.com/nemoclaw |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
🧹 Nitpick comments (3)
scripts/docs-review-receipt.mts (1)
425-432: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win
isCodeFileandisDocumentationFileoverlap on.mdxfiles.A non-
docs/.mdxfile satisfies both predicates:isCodeFilereturnstrue(not underdocs/, not.md) whileisDocumentationFilealso returnstrue. A documentation-only.mdxchange outsidedocs/is therefore classified as code-changing and triggers a spurious receipt requirement/advisory warning. Define code files as the complement of documentation files to keep the two mutually exclusive.♻️ Proposed fix
-function isCodeFile(file: string): boolean { - return !file.startsWith("docs/") && !file.toLowerCase().endsWith(".md"); -} +function isCodeFile(file: string): boolean { + return !isDocumentationFile(file); +}🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@scripts/docs-review-receipt.mts` around lines 425 - 432, Update isCodeFile to define code files as the complement of isDocumentationFile, ensuring non-docs .mdx files are classified only as documentation. Preserve isDocumentationFile’s existing handling of docs/ paths, .md, and .mdx extensions..github/workflows/docs-review-receipt.yaml (1)
49-54: 🔒 Security & Privacy | 🔵 Trivial | 💤 Low valueOptional: pass step outputs as
envrather than interpolating${{ }}into the shell.The interpolated values are git-derived (a fixed
RUNNER_TEMPpath and a hex blob SHA), so this is low-risk on apull_requesttrigger with read-only permissions, but binding them toenvkeeps them as data and clears the template-injection lint.🔒 Proposed hardening
- name: Check documentation writer review receipt continue-on-error: true env: CHANGED_FILES: ${{ steps.receipt-inputs.outputs.changed_files }} AGENTS_BLOB: ${{ steps.receipt-inputs.outputs.agents_blob }} run: >- node --experimental-strip-types --no-warnings scripts/docs-review-receipt.mts check --event "$GITHUB_EVENT_PATH" --changed-files "$CHANGED_FILES" --agents-blob "$AGENTS_BLOB" --mode advisory🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.github/workflows/docs-review-receipt.yaml around lines 49 - 54, Update the documentation receipt check step to expose the receipt-inputs outputs through environment variables such as CHANGED_FILES and AGENTS_BLOB, then pass those quoted variables to the node command instead of directly interpolating the GitHub expressions in run. Preserve the existing arguments and advisory mode.Source: Linters/SAST tools
test/docs-review-receipt.test.ts (1)
264-264: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winUse the POSIX
:PATH separator instead ofpath.delimiter(also at Line 300).These tests run only on Linux CI runners, so prefer the established
:separator when constructingprocess.env.PATH.♻️ Proposed change (apply to Lines 264 and 300)
- env: { ...process.env, PATH: `${bin}${path.delimiter}${process.env.PATH ?? ""}` }, + env: { ...process.env, PATH: `${bin}:${process.env.PATH ?? ""}` },Based on learnings: prefer the POSIX PATH separator
:when constructingprocess.env.PATHin tests; do not replace it withpath.delimiter, because these tests only run on Linux runners in CI.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@test/docs-review-receipt.test.ts` at line 264, Replace path.delimiter with the POSIX “:” separator when constructing process.env.PATH in both test environment setups in docs-review-receipt.test.ts, preserving the existing bin and process.env.PATH entries.Source: Learnings
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In @.github/workflows/docs-review-receipt.yaml:
- Around line 49-54: Update the documentation receipt check step to expose the
receipt-inputs outputs through environment variables such as CHANGED_FILES and
AGENTS_BLOB, then pass those quoted variables to the node command instead of
directly interpolating the GitHub expressions in run. Preserve the existing
arguments and advisory mode.
In `@scripts/docs-review-receipt.mts`:
- Around line 425-432: Update isCodeFile to define code files as the complement
of isDocumentationFile, ensuring non-docs .mdx files are classified only as
documentation. Preserve isDocumentationFile’s existing handling of docs/ paths,
.md, and .mdx extensions.
In `@test/docs-review-receipt.test.ts`:
- Line 264: Replace path.delimiter with the POSIX “:” separator when
constructing process.env.PATH in both test environment setups in
docs-review-receipt.test.ts, preserving the existing bin and process.env.PATH
entries.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: c0897d94-35cb-42c0-ab6e-1af55b4d6376
📒 Files selected for processing (7)
.github/PULL_REQUEST_TEMPLATE.md.github/workflows/docs-review-receipt.yamlAGENTS.mdCONTRIBUTING.mdpackage.jsonscripts/docs-review-receipt.mtstest/docs-review-receipt.test.ts
prekshivyas
left a comment
prekshivyas
left a comment
There was a problem hiding this comment.
Two correctness fixes are needed before merge:
- Reject duplicate singleton receipt fields. Conflicting
Resultlines currently pass because only the first match is parsed. - Treat
.mdxfiles outsidedocs/as documentation-only; they are currently classified as both code and docs. Please add regression tests for both cases.
Also rerun the documentation writer review and refresh the stale head/AGENTS.md receipt metadata at the current head. The red GPT advisor is a tooling failure, not a code regression.
cv
left a comment
cv
left a comment
There was a problem hiding this comment.
Reviewed the refreshed head and the prior requested changes. Duplicate singleton fields and external-MDX classification are fixed with regressions, the duplicate-checkbox edge case is now covered, workflow inputs are passed through the environment, and the documentation-writer receipt is bound to cb504b0 after an independent docs review. Nine-category security review passes; this is an advisory contributor workflow and adds no supported product surface. GitHub-hosted checks remain authoritative for final merge readiness.
Requested correctness fixes are present on cb504b0 with regressions, and the documentation-writer receipt was rerun and refreshed to this head. Dismissing the now-stale blocking review after maintainer re-review and approval.
cv
left a comment
cv
left a comment
There was a problem hiding this comment.
Re-reviewed exact refreshed head 3c952a0 against current main 02cf73d. The base refresh is conflict-free and leaves the effective seven-file PR diff unchanged. Documentation-writer review was rerun and the receipt is now bound to this head; prior security, product-scope, and correctness conclusions remain valid. Awaiting fresh GitHub-hosted checks.
<!-- markdownlint-disable MD041 --> ## Summary Adds the canonical dated `## v0.0.93` release entry to `docs/changelog/2026-07-23.mdx`. The entry records user-visible behavior, release validation, and documentation controls merged after `v0.0.92`, while preserving the pending DGX OS `7.6.x` Station Express qualification caveat. ## Changes - Adds the parser-safe dated release entry with a summary, grouped details, and published-route links. - Reconciles the `v0.0.92..origin/main` commit range with merged `v0.0.93` PRs. - Records that no-OTA DGX OS `7.6.x` passed bounded host preflight, while full Station Express end-to-end qualification remains pending. - Leaves existing product pages unchanged because the source PRs already document their supported behavior. ### Source summary - #7285 -> `docs/changelog/2026-07-23.mdx`: Records the existing-vLLM ownership choice and resumable Station handoff. - #7419 -> `docs/changelog/2026-07-23.mdx`: Records bounded no-OTA DGX OS `7.6.x` recognition and its pending end-to-end qualification. - #7268 -> `docs/changelog/2026-07-23.mdx`: Records optional Hugging Face authentication, output sanitization, and resumable HTTP `429` recovery. - #7442 -> `docs/changelog/2026-07-23.mdx`: Records clean SIGINT handling at hidden credential prompts. - #7299 -> `docs/changelog/2026-07-23.mdx`: Records Intel macOS rejection before ref resolution or network work. - #7296 -> `docs/changelog/2026-07-23.mdx`: Records the DGX Spark non-interactive local-vLLM selection order. - #7342 -> `docs/changelog/2026-07-23.mdx`: Records delegated protected E2E approvals in the grouped release-validation bullet. - #7373 -> `docs/changelog/2026-07-23.mdx`: Records base-image publication gating before final-main fanout. - #7388 -> `docs/changelog/2026-07-23.mdx`: Records semantic phase runtime summaries. - #7397 -> `docs/changelog/2026-07-23.mdx`: Records progress coverage hardening. - #7391 -> `docs/changelog/2026-07-23.mdx`: Records centralized larger-runner routing. - #7423 -> `docs/changelog/2026-07-23.mdx`: Records one retry for confirmed hosted-runner loss. - #7399 -> `docs/changelog/2026-07-23.mdx`: Records runner-comparison telemetry. - #7270 -> `docs/changelog/2026-07-23.mdx`: Records staging Brev Launchable validation. - #7426 -> `docs/changelog/2026-07-23.mdx`: Records filtering of irrelevant base-image run history. - #7333 -> `docs/changelog/2026-07-23.mdx`: Records aligned Quickstart platform guidance. - #7343 -> `docs/changelog/2026-07-23.mdx`: Records documentation-writer receipt collection. - #7400 -> `docs/changelog/2026-07-23.mdx`: Records the documentation-writer receipt requirement for docs-only PRs. - #7413 -> `docs/changelog/2026-07-23.mdx`: Records removal of redundant receipt PR metadata. - #7405 -> `docs/changelog/2026-07-23.mdx`: Records corrected inference CLI references. - #7389 -> `docs/changelog/2026-07-23.mdx`: Records completion of the v0.0.91 documentation audit. `#7384` is an internal refactor with no intended runtime behavior change. `#7401` updates internal CodeQL Actions dependencies. `#7376` is already contained in `v0.0.92`, so it is outside the release-entry scan range despite its retained planning label. ## Type of Change - [ ] Code change (feature, bug fix, or refactor) - [ ] Code change with doc updates - [x] Doc only (prose changes, no code sample modifications) - [ ] Doc only (includes code sample changes) ## Quality Gates - [ ] Tests added or updated for changed behavior - [x] Existing tests cover changed behavior — justification: `test/changelog-docs.test.ts` validates dated changelog structure, SPDX syntax, and version headings. - [ ] Tests not applicable — justification: - [x] Docs updated for user-facing behavior changes - [ ] Docs not applicable — justification: - [ ] Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging) - [ ] Sensitive-path review completed or maintainer-approved waiver recorded — reviewer/approval link/justification: - [ ] Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue: ## Documentation Writer Review - [x] Documentation writer subagent reviewed the completed changes - Result: `docs-updated` - Evidence: Reviewed `docs/changelog/2026-07-23.mdx` against `WRITING.md`, `docs/CONTRIBUTING.md`, `docs/.docs-skip`, `docs/index.yml`, the six user-visible source PRs, and the remaining grouped release commits. The review corrected an ambiguous qualification claim, confirmed all published routes, preserved the DGX OS `7.6.x` caveat, and found no remaining action. - Agent: Codex Desktop <!-- docs-review-head-sha: ec0a866 --> <!-- docs-review-agents-blob-sha: 9c9b36d --> ## DGX Station Hardware Evidence - [ ] Tested on DGX Station - Tested commit: Not applicable. This PR does not change `scripts/prepare-dgx-station-host.sh`. - Station profile/scenario: Not applicable. - Result: Not applicable. - Supporting evidence: Not applicable. ## Verification - [x] PR description includes a `Signed-off-by:` line and every commit appears as `Verified` in GitHub - [x] Normal `pre-commit`, `commit-msg`, and `pre-push` hooks passed, or `npm run check:diff` passed when hooks were skipped or unavailable - [x] Targeted behavior tests pass for the current change set, or tests are marked not applicable above — `npx vitest run test/changelog-docs.test.ts`: 1 file and 6 tests passed. - [ ] Applicable broad gate passed — Not applicable to one native changelog file. - [x] Quality Gates section completed with required justifications or waivers - [x] No secrets, API keys, or credentials committed - [ ] `npm run docs` builds without warnings (doc changes only) — completed with 0 errors and 2 existing Fern warnings. - [x] Doc pages follow the [style guide](https://github.com/NVIDIA/NemoClaw/blob/main/docs/CONTRIBUTING.md) (doc changes only) - [ ] New doc pages include SPDX header and frontmatter (new pages only) — not applicable because native changelog entries use a parser-safe MDX SPDX comment without frontmatter. --- Signed-off-by: Carlos Villela <cvillela@nvidia.com> <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Added the v0.0.93 changelog covering onboarding and validation improvements. * Documented support for additional DGX Station Express workstation releases and clearer handling of existing vLLM workloads. * Added guidance for optional Hugging Face authentication, resumable rate-limit recovery, and DGX Spark provider selection. * Clarified installer behavior on Intel macOS, release validation requirements, hosted-runner retries, documentation checks, and supported CLI quickstart paths. <!-- end of auto-generated comment: release notes by coderabbit.ai -->
3 participants
Summary
Code-changing PRs can now record a structured documentation writer review receipt in the PR description.
An advisory check validates each receipt, and maintainers can export JSON, CSV, or summary data to measure adoption during the pilot.
Changes
AGENTS.mdversion.AGENTS.mdversion. A new development commit makes the receipt stale until the documentation writer review runs again..mdxfiles outsidedocs/.CONTRIBUTING.md.Maintainers need durable, tool-independent adoption data. The PR description is the current durable source; a checkbox alone cannot detect a stale review or support historical aggregation.
test/docs-review-receipt.test.tsprotects the receipt and report behavior.Type of Change
Quality Gates
Documentation Writer Review
docs-updatedCONTRIBUTING.md,.github/PULL_REQUEST_TEMPLATE.md, andAGENTS.mddocument the receipt fields, singleton-field rule, revision binding, rerun behavior, and reporting workflow; no user-facingdocs/page applies.DGX Station Hardware Evidence
Verification
Signed-off-by:line and every commit appears asVerifiedin GitHubpre-commit,commit-msg, andpre-pushhooks passed, ornpm run check:diffpassed when hooks were skipped or unavailablenpx vitest run test/docs-review-receipt.test.tspassed 10 tests;npm run typecheck:cliand the normal commit and push hooks passed.npm run checktimed out after 15 minutes. Every reported structural, lint, secret-scan, Markdown, source-shape, test-size, and skill check passed; the buffered full coverage stage did not return a result. CI is the authoritative broad result.npm run docsbuilds without warnings (doc changes only) — passed with zero errors and one existing Fern warning.Signed-off-by: Miyoung Choi miyoungc@nvidia.com
Summary by CodeRabbit
docs-review:checkanddocs-review:reportnpm scripts.