opensource/coder
3
0
Fork 0
mirror of https://github.com/coder/coder.git synced 2026-10-31 19:36:41 +08:00
Code Issues Packages Projects Releases Wiki Activity
16,016 Commits 479 Branches 422 Tags
d014d4c372fb7dfdb3b0ea00a9935fec9b9528f9
Commit Graph
6 Commits
Author SHA1 Message Date
Nick Vigilante d485786dfe ci(.github/workflows): list all changed doc pages with review checkboxes (#27166) 
## 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.*
 2026-07-21 15:16:29 -05:00
Nick Vigilante 182bdc871a docs: scaffold docs/.style for the prose style guide (#25466) 
Adds a private contributor-tooling directory at `docs/.style/` that will
host the canonical prose style guide and the custom Vale rules used to
enforce it. The directory's contents do not deploy to `coder.com/docs`.

This PR is the scaffold only. The Vale configuration, the rule set, and
the per-rule style-guide sections all land in follow-up PRs.

## What changes

- New `docs/.style/` directory with:
  - `README.md` explaining the convention
  - `style-guide.md` as a table-of-contents scaffold
- `styles/Coder/README.md` placeholder so Git tracks the empty Vale
rules dir
- `.github/workflows/deploy-docs.yaml`: skip the workflow on
`.style`-only pushes, and exclude `.style` paths from the
surgical-reindex git diff on mixed commits. Defense-in-depth on top of
the manifest-driven coder.com routing.
- `.github/.linkspector.yml`: add `docs/.style` to `excludedDirs`
- `AGENTS.md` and `.claude/docs/DOCS_STYLE_GUIDE.md`: cross-link to the
new style guide for agents

## Verification

- `make pre-commit-light` clean (`fmt/markdown`, `lint/markdown`,
`lint/typos`, `lint/emdash`, `lint/actions/actionlint`,
`lint/shellcheck`).
- `markdown-table-formatter --check` and `markdownlint-cli2` both
process the new files (existing globs are `find docs -name '*.md'`).
- `actionlint` clean on the modified workflow.
- coder.com exclusion works because route discovery and Algolia indexing
are manifest-driven; this directory is not in `docs/manifest.json`. The
workflow changes are defense in depth.

<details>
<summary>Implementation plan and decision log</summary>

### Decisions

- **Location**: `docs/.style/` (leading dot, mirrors `.github/`,
`.vscode/`, `.claude/`). Vale's `StylesPath` will be
`docs/.style/styles/`; `.vale.ini` lands at repo root in a follow-up.
- **Existing public page `docs/about/contributing/documentation.md`**:
untouched in this PR. Nick's separate information-architecture rework
will redirect it to GitHub at the right time.
- **Placeholder for empty `styles/Coder/`**: real `README.md`, not
`.gitkeep`. Discoverable on GitHub, lints with the existing tooling,
lists the planned starter rules.
- **CONTRIBUTING.md**: not touched. It's a 2-line redirect to
`coder.com/docs/CONTRIBUTING`; bloating it would defeat the redirect.
- **`.claude/docs/DOCS_STYLE_GUIDE.md`**: kept as the structure/research
companion. A blockquote at the top points at the new canonical prose
guide.

### coder.com exclusion mechanism (verified by inspection)

Direct inspection of `coder/coder.com`:

- Route discovery in
[`src/utils/docs/docs.ts`](https://github.com/coder/coder.com/blob/master/src/utils/docs/docs.ts)
iterates `routes` from `docs/manifest.json`. Files not in the manifest
never become routes.
- The Algolia surgical indexer at
[`src/utils/algoliaDocs/surgical.ts`](https://github.com/coder/coder.com/blob/master/src/utils/algoliaDocs/surgical.ts)
explicitly skips paths not in the manifest, incrementing `pathsSkipped`.

Net result: not adding anything from `docs/.style/` to `manifest.json`
is the only thing that has to be true for the exclusion to work. The
`deploy-docs.yaml` tweaks are defense in depth.

### deploy-docs.yaml changes (pre-mortem)

1. Trigger path negation `!docs/.style/**` skips the workflow on
`.style`-only pushes. GitHub Actions only suppresses when every changed
file matches a negation, so mixed commits still trigger.
2. The git-diff pathspec `:(exclude)docs/.style/**` drops `.style` paths
from the surgical-reindex payload on mixed commits.

Risks considered:

- **Test contract**: `.github/workflows/test-deploy-docs-diff.sh` only
exercises the downstream awk parser, not the git-diff invocation. The
exclusion happens at git-diff time; the parser sees the same
`<status>\0<path>\0` format. No test change needed.
- **First push to a brand-new branch**: the workflow falls back to
whole-branch reindex when `BEFORE_SHA` is all zeros. Whole-branch
reindex re-extracts records from the manifest, which still excludes
`.style` files because they are not in the manifest.
- **Workflow-dispatch**: takes the whole-branch path; same reasoning.
Safe.

### Why a real README in `styles/Coder/` instead of `.gitkeep`

It explains intent, lists the upcoming rules, and lints with the
existing tooling. The cost is one extra Markdown file; the upside is
that a contributor browsing GitHub sees the plan without clicking
around.

</details>

---

*Filed via [Coder Agents](https://coder.com/docs/ai-coder/agents) on
Nick's behalf.*


Linear: DOCS-180
 2026-06-17 13:19:37 +00:00
Nick Vigilante e32fdc813b ci: rerun docs preview job on subsequent pushes (#25456) 
Fixes DOCS-174: the docs-preview workflow only fired on `pull_request:
opened`. Subsequent pushes left the preview comment stale.

## Changes

- Add `synchronize` and `reopened` to trigger types so subsequent pushes
retrigger the workflow.
- Add a workflow-level `concurrency` group keyed by PR number with
`cancel-in-progress: true` so rapid successive pushes don't race the
comment-upsert lookup.
- Replace always-create comment logic with an upsert: find the existing
comment containing `<!-- docs-preview -->` and PATCH it; fall through to
create only when none exists or the PATCH itself fails (comment was
deleted between find and update).
- Filter the upsert lookup to comments authored by `github-actions[bot]`
so a human comment containing the marker is never silently overwritten.
- Decouple the `gh api` lookup from the `head -n 1` pipe so API failures
(network, auth, rate-limit) propagate immediately instead of being
swallowed by `|| true`.
- Delete the stale preview comment when a `synchronize` push drops all
Markdown changes (e.g. a follow-up push that removes the file an earlier
push had previewed but still touches `docs/`). The previous preview
comment would otherwise point at a deleted page.
- Extract the marker and the comment-selector jq into a single
`DOCS_PREVIEW_MARKER` variable and a `list_docs_preview_comments` shell
function so the stale-cleanup and upsert branches share one source of
truth.

## Out of scope

Vercel ISR cache invalidation for feature branch previews requires a
coder.com change (the `algolia-docs-sync` endpoint only accepts `main`
and `release/*` refs). Tracked separately in DOCS-174 out-of-scope
notes.

Pulls that fully revert their `docs/` changes in a follow-up push won't
fire this workflow at all (GitHub's `paths` filter requires a path match
in the diff), so a stale preview comment can survive on that specific
edge. Removing the `paths` filter to handle it would run the workflow on
every PR push, which is disproportionate. Acknowledged in
[CRF-12](https://github.com/coder/coder/pull/25456#discussion_r3313738550).

<details>
<summary>Implementation notes</summary>

**Marker and selector deduplication**: The marker string and jq selector
previously appeared at three sites (comment body, stale-cleanup API
call, upsert API call). They're now consolidated into
`DOCS_PREVIEW_MARKER` plus a `list_docs_preview_comments` shell function
so a future marker change updates one place.

**Comment body construction**: The double-quoted multi-line string form
with escaped backticks (`` \` ``) for the inline-code spans is
shellcheck-clean. An earlier draft used `printf -v comment_body` with a
single-quoted format string containing backticks, which triggered
SC2016; the printf-three-pieces workaround that replaced it has since
been simplified to the direct double-quoted form.

**Upsert logic**: `gh api --paginate` fetches all PR comments, jq
filters to `github-actions[bot]`-authored comments containing the
marker, and the workflow PATCHes the first match. If the PATCH fails
(404 because the comment was deleted between find and update), the
script falls through to `gh pr comment` to create a new one. Self-heals
on the next push if both paths somehow fail.

**Stale-cleanup logic**: Same selector as upsert, but in the early-exit
branch when no Markdown files exist in this push. `DELETE` failures are
logged and execution continues (the next push will re-attempt or post a
fresh comment), so a transient API failure won't fail the CI job.

</details>

> Generated by Coder Agents on behalf of @nickvigilante
 2026-05-28 10:03:21 -04:00
david-fraley 27b527dc7f ci(.github/workflows/docs-preview.yaml): deep-link preview to first changed page (#24832) 2026-04-30 20:11:48 +00:00
Jakub Domeracki e3a1fb0c89 ci: pass github.repository through env var (#24605) 
*Disclaimer: implemented by a Coder Agent using Claude Opus 4.*

---

Move `github.repository` from direct `${{ }}` interpolation in the
`run:`
block to an `env:` var, consistent with how `BRANCH` and `PR_NUMBER` are
already handled. This eliminates a `zizmor` template-injection finding.

Follows up on #24283.
 2026-04-22 12:57:22 +02:00
Danny Kopping d3cc23d8ba ci: post docs preview link on PRs that change docs (#24283) 
*Disclaimer: implemented by a Coder Agent using Claude Opus 4.6*

---

Adds a lightweight workflow that posts a docs preview link as a PR
comment
whenever a pull request touches files under `docs/`. The preview is
served
by coder.com's branch-preview feature at `/docs/@<branch>`.

The branch name is URL-encoded so names with slashes (e.g.
`user/feature`) produce correct links like
`/docs/@user%2Ffeature` instead of broken paths.

The comment is created on open and updated in-place on subsequent pushes
using the `peter-evans/find-comment` + `create-or-update-comment`
pattern
already used by the `pr-deploy` workflow.

---

Depends on https://github.com/coder/coder.com/pull/708
 2026-04-22 09:46:00 +02:00