mirror of
https://github.com/coder/coder.git
synced 2026-09-22 05:05:20 +08:00
Nick Vigilante
d485786dfe
## Problem The `docs-preview` comment bot links to exactly one changed page under `docs/`. See https://github.com/coder/coder/pull/27161#issuecomment-4937078346, where the PR touched a few dozen pages but the comment only surfaced one preview link, with no way to track which of the other pages had actually been reviewed. ## Changes Scope: this PR only touches `.github/workflows/**`. - List a preview link for **every** added/modified Markdown file under `docs/` in the PR, not just the first. - Filter that list to files that resolve to a route in `docs/manifest.json` (fetched as a raw blob at the PR head sha). Anything else (`docs/.style/**` contributor tooling, or a page not wired into navigation) is dropped so the comment never links to a 404. - Render each page as a Markdown checklist item a reviewer can check off in the GitHub UI as they review the rendered coder.com preview. (GitHub's native per-file "Viewed" state tracks the raw diff and can't deep-link to the preview, which is why the workflow keeps its own state.) - Round-trip checked state across pushes: a page's checkbox stays checked as long as its blob sha hasn't changed since the comment was last updated, and resets to unchecked the moment new content lands on that page (a checked box means "I've reviewed the current revision," not some earlier one). State is stored as a hidden base64 `path -> sha` marker and recovered defensively (a malformed or non-object marker resets safely to unchecked). - Keep the comment under GitHub's 65,536-character limit by building and measuring the exact posted body, then binary-searching the largest leading prefix of pages that fits; omitted pages are summarized with a link to the PR Files tab. - Extended `test-docs-preview-mapper.sh` with regression tests for the manifest-path normalization, checkbox-line parsing, checked-state carryover, base64 state round-trip, and comment-size capping. Linear: [DOCS-541](https://linear.app/codercom/issue/DOCS-541/docs-preview-pr-comment-list-all-changed-pages-with-per-page-viewed) <details> <summary>How this was tested</summary> GitHub Actions can't easily be run locally, so I extracted the `run:` script logic and exercised it against a fake `gh` CLI backed by JSON fixtures, covering: 1. First run: several changed pages, one under `docs/.style/`, one not in the manifest, one image, one removed file. Only the manifest-resolvable pages show up, all unchecked. 2. Second run: a page with an unchanged sha stays checked; a page whose sha changed resets to unchecked even though it was previously checked; a brand-new page starts unchecked. 3. No eligible Markdown files on a push, and Markdown files present but none resolving to a manifest route: the stale comment gets deleted. 4. State round-trip: a valid base64 `path -> sha` marker is recovered; an undecodable marker and a valid-but-non-object marker both reset safely to `{}`; an emitted marker survives a full round-trip. 5. Comment-size cap: a repo-scale case of 400 long paths with a long branch keeps the largest prefix that fits under budget (176/400 at ~64.8 KB) and confirms one more page would exceed the 65 KB budget. `shfmt`, `shellcheck`, `actionlint`, and `bash .github/workflows/test-docs-preview-mapper.sh` all pass. </details> ## What this looks like <img width="900" height="380" alt="docs-preview-demo" src="https://github.com/user-attachments/assets/daf71781-1a88-4d90-a063-8f1ebcc84b42" /> --- *This PR description and the underlying changes were prepared with Coder Agents assistance.*