opensource/coder
3
0
Fork 0
mirror of https://github.com/coder/coder.git synced 2026-09-21 20:51:01 +08:00
Code Issues Packages Projects Releases Wiki Activity
15,888 Commits 479 Branches 387 Tags
97cb722fb87faa513bc3372eda24799b8dbaef41
Commit Graph
64 Commits
Author SHA1 Message Date
Atif Ali 062c0fdd3b docs: rebrand Windsurf doc page to Devin Desktop (#28205) 
## Summary

Cognition (maker of Devin) rebranded the Windsurf Editor as Devin
Desktop on June 2, 2026, after acquiring it from Codeium in July 2025.
Our docs still referred to the editor as Windsurf and linked to a dead
`codeium.com` domain.

## Changes

- Renamed `docs/user-guides/workspace-access/windsurf.md` to
`devin-desktop.md`, rewritten to lead with Devin Desktop branding, note
the Codeium -> Windsurf -> Devin Desktop history, and use current links
(`windsurf.com`, `docs.windsurf.com`) instead of dead `codeium.com`
ones.
- Updated `docs/manifest.json` and
`docs/user-guides/workspace-access/index.md` to reference the new page.
- Updated remaining Windsurf mentions to Devin Desktop in
`docs/ai-coder/ide-agents.md`, `docs/ai-coder/index.md`,
`docs/reference/glossary.md`, and
`docs/ai-coder/ai-gateway/clients/index.md`.
- Added `windsurf.com`/`devin.ai` to `.github/.linkspector.yml` ignore
patterns; both rate-limit repeated automated requests with 429s (same
class of issue as the `codeium.com`/`marketplace.visualstudio.com` fix
in #28203).
- Switched every module reference from `windsurf` to the new
`devin-desktop` registry module (`docs/about/contributing/modules.md`,
the three `get-started/customize-your-template/*.md` Terraform
tutorials, and the main doc page's module link), since the new module
actually renders `display_name = "Devin Desktop"` / `slug =
"devin-desktop"` in the UI (the old `windsurf` module hardcodes
"Windsurf Editor").

<details>
<summary>Scope notes / sequencing</summary>

The `devin-desktop` module referenced here is being added in
[coder/registry#1050](https://github.com/coder/registry/pull/1050) (not
yet merged/released). That PR is itself gated on
[coder/coder#28214](https://github.com/coder/coder/pull/28214)
(whitelisting the `devin:` URI scheme) shipping in a released Coder
version first. This docs PR can merge independently, the module link
will 404 until #1050 is released, same as any
docs-ahead-of-registry-release sequencing.

The Terraform code samples now show `module "devin-desktop"` because
that module's `display_name`/`slug` are properly parameterized (unlike
`windsurf`, which hardcodes "Windsurf Editor"/`windsurf` regardless of
what's passed in), so the docs stay accurate to the rendered UI.

</details>

## Validation

- `make lint` (docs lint, markdownlint, repo checks) passes.
- Manually verified the new outbound links (`docs.windsurf.com`) return
200; `windsurf.com`/`devin.ai` are rate-limited (429) from this
environment too, hence the added ignore patterns.

Stacked on #28203 (targets that branch so the diff here stays scoped to
the rebrand; will retarget to `main` once #28203 merges).

> 🤖 This PR was created with the help of Coder Agents, and needs a human
review. 🧑💻
 2026-08-18 15:17:02 +05:00
Jake Howell ea8ba0c678 refactor: remove MUI and Emotion (#27821) 
> 🤖 This PR was modified by Coder Agents on behalf of Jake Howell.

Until we meet again.

## Stack

- #27636
- #27718 
- #27719 
- #27722
- #27723
- #27724
- #27728
- #27730
- #27732
- #27762
- #27763
- #27786
- #27787
- #27788
- #27789
- #27790
- #27791 
- #27817 
- #27820
- #28009

## Final removal (`c39b664`)

Removes the last of MUI and Emotion now that every surface has been
migrated:

- **Dependencies**: drops `@mui/material` and
`@emotion/{cache,css,react,styled}` from `package.json` /
`pnpm-lock.yaml`, and deletes the `@types/emotion.d.ts` and
`@types/mui.d.ts` module augmentations.
- **Theming**: replaces the Emotion `CacheProvider`, MUI `ThemeProvider`
/ `StyledEngineProvider`, and `CssBaseline` in `ThemeProvider` with a
lightweight `theme/context.tsx` that exposes `ThemeContextProvider` and
a `useTheme` hook.
- **Global styles**: moves the base `body` styles (background, text
color, font, antialiasing) that `CssBaseline` previously provided into
`index.css`, and drops the temporary MUI modal/popover scrollbar-gutter
workaround.
- **Cleanup**: removes the MUI → shadcn / Emotion → Tailwind migration
guidance from `site/AGENTS.md`, updates the Storybook `preview.tsx`, and
adjusts assorted components (`Command`, `Slider`, `Switch`, `Tabs`,
`SyntaxHighlighter`, timing charts) and theme files to consume the new
context instead of MUI/Emotion.
 2026-08-17 14:04:48 +07:00
Nick Vigilante 1d189cc204 docs: fix P2/P3 typos and syntax errors from drift sweep (#28101) 
## Summary

High-confidence textual subset of the DOCS-637 **P2/P3** drift batch (31
findings total). These 8 fixes are pure typo / grammar / syntax
corrections verified directly against the doc source, so they carry no
risk of misreconstructed command output.

## Changes (6 files)

| Page | Fix |
|------|-----|
| `docs/admin/templates/extending-templates/variables.md` | Remove
doubled word: "file in in the template directory" → "file in the
template directory". |
| `docs/admin/networking/port-forwarding.md` | Grammar: heading "From an
coder_app resource" → "From a coder_app resource". |
| `docs/user-guides/workspace-access/index.md` | Malformed heading
"Through with the CLI" → "Through the CLI". |
| `docs/about/contributing/modules.md` | Conventional-commit example
missing the required space: `feat(git-clone):add` → `feat(git-clone):
add`. |
| `docs/ai-coder/tasks-migration.md` | Add missing closing double-quotes
on Terraform `source`/`version` in two snippets that would fail
`terraform` parsing. |
| `docs/admin/users/idp-sync.md` | Role Sync section said "group sync
settings" (copy-paste from the Group Sync section); remove an invalid
trailing comma from a JSON output example. |

## Deferred (remaining ~23 P2/P3 items, not in this PR)

The rest of the batch is stale **command-output** samples (column/schema
changes, sample values) and items that need a content decision (e.g.
`--psk` now deprecated in favor of `--key`; `--address` deprecated; an
undocumented retention flag). Those need live-output reconstruction or a
call on direction, so they're left for follow-up work, consistent with
the issue's "handle after the P0/P1 fixes land" guidance. One catalog
row (`reverse-proxy-nginx.md:57`, certbot `ws=apache`) is already
handled by #28086 and is excluded here.

Linear: https://linear.app/codercom/issue/DOCS-646

> This PR was created with AI assistance (Coder Agents).
 2026-08-14 12:44:55 -04:00
Ben Potter 79723db2d2 docs: replace enterprise-base image references with example-base (#27025) 
Follow-up to #27018, sweeping the remaining
`codercom/enterprise-base:ubuntu` references to
`codercom/example-base:ubuntu` and `coder/enterprise-images` links to
[coder/images](https://github.com/coder/images). The `example-` prefix
is the recommended one for new deployments per the coder/images README.

Covers the 11 docs pages flagged by doc-check on #27018 plus the
embedded `examples/templates/docker` and `examples/templates/kubernetes`
starter templates (image string only; the `image` variable lives in the
coder/registry templates, see coder/registry#943).

OpenShift imagestream names in `docs/install/openshift.md` keep the
`enterprise-base` local name; only the upstream image reference changed.

Part of DEVREL-201.

🤖 Generated with Coder Agents using Claude, on behalf of @bpmct
 2026-08-04 13:47:55 -07:00
Nick Vigilante c84aa564ba docs: normalize code-fence languages for Shiki compatibility (#27161) 
Normalizes non-standard code-fence language tags across `docs/**` so a
strict highlighter (Shiki, used by Fumadocs) won't fail the build on an
unrecognized language, and unifies redundant synonym tags onto one
canonical form per language. The current renderer (Speed-Highlight)
detects the language from the code content, not the fence label, so this
drift wasn't visible until now.

## Changes

- `hcl` -> `tf` (199 fences, including indented ones nested in
numbered/bulleted lists). Shiki ships `hcl` and `terraform` as two
distinct grammars (not aliases); every `hcl`-tagged fence in `docs/**`
is actually Terraform resource/data/provider syntax, so the more
specific `terraform` grammar is correct for all of them. `tf` is Shiki's
own alias for that grammar, and it's also what GitHub's own markdown
renderer resolves to the same HCL/Terraform highlighting.
- `pwsh`/`powershell` -> `ps1`. Both `ps` and `ps1` are registered
PowerShell aliases in Shiki, but on GitHub's renderer only `.ps1` is a
registered file extension (`.ps` isn't), so `ps1` renders identically to
`powershell` there today while bare `ps` would silently lose
highlighting.
- `env` -> `dotenv` (a dedicated Shiki grammar for `KEY=VALUE` files)
- `text`/`output`/`none`/`url` -> `txt`. Same built-in plain-text
fallback either way, just shorter.
- `Dockerfile` -> `dockerfile` (lowercase)
- `bash`/`shell` -> `sh` (732 fences). Shiki and GitHub both alias all
three to a single shell grammar; this was already the style guide's
stated preference, just not enforced across the existing corpus until
now.
- `markdown` -> `md` (4 fences). Alias of the same grammar in both Shiki
and GitHub.
- `jsonc` -> `json` (1 fence). The block has no comments or trailing
commas, so it doesn't need the comments-capable grammar.
- `ts` -> `tsx` (2 fences, `docs/about/contributing/frontend.md`).
Verified the actual content tokenizes identically under both grammars,
and a sibling block in the same file already needs `tsx` for real JSX,
so unifying to one tag is safe for this file. Documented a caveat: `tsx`
mis-tokenizes the legacy angle-bracket type-assertion syntax
(`<Type>value`), which is invalid in real `.tsx` files anyway, so use
`value as Type` instead.
- `yml` -> `yaml` (1 fence)
- Updated `docs/.style/style-guide/formatting.md` to document all
canonical tags

`promql` (2 fences) and `caddyfile` (2 fences) are left as-is. Shiki
doesn't bundle a grammar for either, so they need a custom grammar
registration when the site adopts Shiki, rather than degrading to `txt`.
Tracked as follow-up work under DOCS-118 and
[DOCS-544](https://linear.app/codercom/issue/DOCS-544/vendor-a-local-promql-grammar-for-shiki-syntax-highlighting)
(promql).

Does not touch `offlinedocs/`.

Linear:
[DOCS-476](https://linear.app/codercom/issue/DOCS-476/normalize-docs-code-fence-languages-de-risk-shikifumadocs)

<details>
<summary>How the fence tags were verified</summary>

Each tag was tested against a real `shiki@latest` highlighter instance
(`codeToHtml`/`codeToTokens`) and cross-checked against GitHub's
`@wooorm/starry-night` grammar sources (the renderer that actually
displays these `.md` files today, in repo browsing and PR diffs), since
that's what determines whether brevity is safe before Shiki adoption:

```text
FAIL  env        -- Language `env` is not included in this bundle.
FAIL  Dockerfile -- Language `Dockerfile` is not included in this bundle.
FAIL  promql     -- Language `promql` is not included in this bundle.
FAIL  caddyfile  -- Language `caddyfile` is not included in this bundle.
FAIL  pwsh       -- Language `pwsh` is not included in this bundle.
FAIL  output     -- Language `output` is not included in this bundle.
```

`hcl` doesn't error in Shiki, since it's a real grammar, but that's
exactly the trap: it was silently rendering every fence with the generic
HCL grammar instead of the Terraform-specific one. Every `hcl`-tagged
fence in `docs/**` was manually checked against `origin/main` and is
genuinely Terraform content.

For `ts`/`tsx`, tokenizing the actual doc content confirmed identical
output under both grammars; a synthetic test with the legacy
angle-bracket cast syntax confirmed `tsx` degrades on that specific
construct, which the style guide now calls out.

The first normalization pass only matched fence tags at column 0
(`^```tag$`), missing tags indented inside numbered/bulleted lists. A
follow-up pass caught the remaining occurrences at any indentation
level.

</details>


---

*This PR description and the underlying changes were prepared with Coder
Agents assistance.*
 2026-07-15 14:07:09 -04:00
Nick Vigilante 61e52532c0 docs: wrap placeholder syntax in backticks in CLI help and swagger annotations (#27194) 
## Problem

Generated reference docs (`docs/reference/cli/*`,
`docs/reference/api/*`) contained raw placeholder and JSON syntax that
came straight from Go CLI help strings and swagger annotations. HTML
renderers treat the angle-bracket tokens (`<team-slug>`, `<uuid>`,
`<KEY>`, etc.) as unknown tags and drop them, so readers see
broken/half-missing text today. The same strings also break MDX parsing.

## Fix

Wrap the placeholder/JSON syntax in backticks **at the source** (Go help
strings and swagger annotation comments), then `make gen`. Rendered docs
now show the placeholders as inline code instead of dropping them.

### Source changes

| File | Placeholder wrapped | Surfaces in |
|------|--------------------|-------------|
| `codersdk/deployment.go` | `` `<organization-name>/<team-slug>` `` |
`cli/server.md`, `coder --help`, settings UI |
| `codersdk/deployment.go` | `` `CODER_AI_GATEWAY_PROVIDER_<N>_*` ``, ``
`CODER_AI_GATEWAY_PROVIDER_<N>_<KEY>` `` | `api/schemas.md` |
| `cli/tokens.go` | `` `<type>:<uuid>` `` | `cli/tokens_create.md`,
`coder --help` |
| `coderd/aitasks.go` | `` `owner:<…>` ``, `` `organization:<…>` ``, ``
`status:<status>` `` | `api/tasks.md` |
| `coderd/exp_chats.go` | `` `pr_status:<…>` `` and sibling filter
tokens | `api/chats.md` |
| `coderd/provisionerdaemons.go`, `coderd/provisionerjobs.go` | ``
`{'tag1':'value1','tag2':'value2'}` `` | `api/organizations.md`,
`api/provisioning.md` |

Everything else in the diff (`coderd/apidoc/*`, `docs/reference/**`,
`*.golden`, `site/src/api/typesGenerated.ts`) is `make gen` output.

## Reviewer notes (the "considered pass" from the ticket)

- **Product-visible:** this changes `coder server --help` and `coder
tokens create --help` output, and the `server-config.yaml` reference
comment. Backticks in terminal help are literal but read fine as
placeholder markers.
- **Settings UI:** the `deployment.go` `Description` also renders in the
deployment settings page. If that field is not Markdown-rendered,
literal backticks will show there. Happy to drop the `deployment.go`
change if you'd rather keep the UI text clean and fix `server.md`
another way.
- **Out of scope here:** `docs/reference/cli/agent-firewall.md`
(`<host>`/`<glob>`) is generated from the external
`github.com/coder/boundary` module, not this repo. It needs an upstream
fix + module bump; not included in this PR.

<details>
<summary>Implementation notes / decision log</summary>

- Scope taken from DOCS-551: source-level backtick pass for generated
reference docs only. Hand-written Markdown fixes are tracked separately
(companion ticket).
- Swagger `@Param` descriptions are Go comments, so the existing `\|`
pipe-escaping in the chats `q` filter is preserved inside the new
backticks (still required for the Markdown table cell to render `|`).
- Verified after `make gen`: generated docs render placeholders as code
spans, table pipes intact; `gofmt` clean; changed Go packages build; no
emdash/endash introduced.
- Deliberately left the `AIProviderConfig` type-level doc comment
untouched because it does not surface in any generated doc (kept the
diff to doc-feeding comments).

</details>

Linear: DOCS-551

---

_Opened by Coder Agents on behalf of @nickvigilante._



---

## Evidence: placeholders dropped on the live docs site

Verified **2026-07-14** against the live site (`coder.com/docs`, i.e.
`main`, pre-merge) by loading each affected page in headless Chrome and
reading the post-hydration DOM (confirmed identical in the raw page
payload). Each simple `<token>` placeholder is parsed as an **empty
custom HTML element**, so the browser renders nothing for it and the
placeholder text disappears from the page.

### What readers see today (before this PR)

| Page (live) | Source Markdown | Rendered on the live site |
|-------------|-----------------|---------------------------|
| [`cli/server`](https://coder.com/docs/reference/cli/server) — OAuth2
GitHub Allowed Teams | `Structured as: <organization-name>/<team-slug>.`
| `Structured as: /.` |
|
[`cli/tokens_create`](https://coder.com/docs/reference/cli/tokens_create)
— `--allow` | `Repeatable allow-list entry (<type>:<uuid>, e.g.
workspace:1234-...).` | `Repeatable allow-list entry (:, e.g.
workspace:1234-...).` |
| [`api/tasks`](https://coder.com/docs/reference/api/tasks) — `q` | `...
status:<status>` | `... status:` (nothing after the colon) |
| [`api/schemas`](https://coder.com/docs/reference/api/schemas) —
AIBridgeConfig (`anthropic`/`bedrock`/`openai`) |
`CODER_AI_GATEWAY_PROVIDER_<N>_*` | `CODER_AI_GATEWAY_PROVIDER__*` |
| [`api/schemas`](https://coder.com/docs/reference/api/schemas) —
AIBridgeConfig (`providers`) | `CODER_AI_GATEWAY_PROVIDER_<N>_<KEY>` |
`CODER_AI_GATEWAY_PROVIDER__` |

[`api/chats`](https://coder.com/docs/reference/api/chats) (`q`) drops
five tokens the same way — `title:<substring>`, `diff_url:<url>`,
`pr:<number>`, `pr_title:<text>`, and the trailing `title:<value>`. The
live parameter description reads (note the dangling `title:`,
`diff_url:`, `pr:`, `pr_title:`):

```text
Search query. Supports title: (case-insensitive, quote multi-word values), archived:bool, has_unread:bool, pr_status:<draft|open|merged|closed> as repeated or comma-separated values, source:<created_by_me|shared_with_me>, diff_url: (quote values containing colons), pr: (exact PR number match), repo:<owner/repo> (case-insensitive substring match against git remote origin or URL), pr_title: (case-insensitive PR title substring). Bare terms are not supported; use title: for title filtering.
```

<details>
<summary>Raw rendered DOM from the live site (headless Chrome,
post-hydration)</summary>

```html
<!-- reference/cli/server -->
Structured as: <organization-name>/<team-slug>.</team-slug></organization-name>

<!-- reference/cli/tokens_create -->
Repeatable allow-list entry (<type>:<uuid>, e.g. workspace:1234-...).</uuid></type>

<!-- reference/api/tasks : only status:<status> drops; the /-containing tokens are escaped and survive -->
Search query for filtering tasks. Supports: owner:&lt;username/uuid/me&gt;, organization:&lt;org-name/uuid&gt;, status:<status></status>

<!-- reference/api/schemas : anthropic / bedrock / openai rows -->
Deprecated: Use Providers with indexed CODER_AI_GATEWAY_PROVIDER_<n>_* env vars instead.</n>

<!-- reference/api/schemas : providers row -->
Providers holds provider instances populated from CODER_AI_GATEWAY_PROVIDER_<n>_<key> env vars and/or the deprecated LegacyOpenAI/LegacyAnthropic/LegacyBedrock fields above.</key></n>
```

The parser auto-inserts closing tags
(`</team-slug></organization-name>`) and lowercases the tag name (`<N>`
becomes `<n>`), leaving `__` where `<N>_` used to be. Every wrapped
placeholder renders correctly as inline code on the [docs preview for
this
branch](https://coder.com/docs/@vigilante%2Fdocs-551-backtick-placeholder-syntax-in-generated-reference-docs-cli/reference/cli/server).

</details>

### Accuracy note — cases that do *not* drop on live

These render fine today, so they are **not** evidence of dropping (the
PR still wraps them for consistency / MDX-safety):

-
[`api/organizations`](https://coder.com/docs/reference/api/organizations)
and
[`api/provisioning`](https://coder.com/docs/reference/api/provisioning):
`{'tag1':'value1','tag2':'value2'}` renders verbatim — curly braces are
not an HTML tag.
- Tokens containing `/` or `|` are escaped by the renderer and stay
visible (as literal `<...>`): `<username/uuid/me>`, `<org-name/uuid>`,
`<owner/repo>`, `<draft|open|merged|closed>`,
`<created_by_me|shared_with_me>`. Backticks still improve their
readability, but they were never dropped.
 2026-07-14 13:39:58 -04:00
Jeremy Ruppel 79fc8541ed docs: update template creation docs for template builder (#26993) 
## Summary

Update documentation across 9 files to present the template builder as
the primary template creation method, replacing the old starter
templates flow as the default entry point.

The template builder is a guided wizard that lets admins select base
infrastructure, add registry modules, configure variables, and produce
validated Terraform without writing HCL.

## Changes

**Primary docs (significant rewrites):**
- `docs/admin/templates/creating-templates.md`: Added "Using the
template builder" as the first section with full 5-step wizard
documentation, screenshots, airgap/registry notes, and alternative
creation links. Moved CLI starter template flow to its own section.
Fixed "You can the" typo.
- `docs/get-started/index.md`: Rewrote Steps 4-6 to use the builder with
the Docker base template instead of the Coder Quickstart (which is not a
builder base template). Generalized workspace parameter instructions.
- `docs/start/first-template.md`: Rewrote to use the builder. Removed
old starter templates references, TODO notes, typo, and commented-out
sections.

**Secondary docs (targeted edits):**
- `docs/admin/templates/index.md`: Replaced starter templates section
with builder-first "Create a template" section.
- `docs/admin/templates/managing-templates/index.md`: Renamed "Starter
templates" to "Creating templates" pointing to the builder.
- `docs/install/airgap.md`: Added "Template builder" section documenting
`CODER_DISABLE_TEMPLATE_BUILDER` and
`CODER_TEMPLATE_BUILDER_REGISTRY_URL`.
- `docs/tutorials/template-from-scratch.md`: Added TIP callout
recommending the builder. Fixed `coder templates create` -> `coder
templates push` inconsistency.
- `docs/admin/integrations/devcontainers/envbuilder/add-envbuilder.md`:
Updated Dashboard tab to reference the builder and "Upload an existing
template" alternative.
- `docs/about/screenshots.md`: Updated caption and image reference for
template builder.

**Screenshots added:**
- `templatebuilder_01_bases.png` (base selection step)
- `templatebuilder_02_modules.png` (module selection step)
- `templatebuilder_03_module_customization.png` (module settings step)
- `templatebuilder_04_customizations.png` (template customizations step)

<details>
<summary>Implementation plan</summary>

# Plan: Update docs/ for Template Builder Launch

## Summary

The Template Builder is a new guided wizard at `/templates/new/builder`
that lets admins create templates by selecting a base infrastructure
template, composing it with registry modules, configuring variables, and
producing a validated Terraform bundle without writing HCL. The docs
need to be updated to present this as the primary/recommended template
creation path, while preserving the existing paths (upload, CLI,
duplicate) as alternatives.

## Key behavioral facts from the code

- **Route**: `/templates/new/builder` (new), `/templates/new` (old,
still exists)
- **Entry point**: The "New Template" button on the Templates page links
to `/templates/new/builder` when the builder is enabled; otherwise falls
back to `/starter-templates`
- **5-step wizard**:
  1. **Select base infrastructure** (e.g., Docker, AWS EC2, Kubernetes)
  2. **Base template parameters** (optional, skipped if base has none)
3. **Select modules** (IDE, AI Agent, Source Control, etc.;
multi-select, grouped by category)
4. **Module settings** (optional, skipped if no configurable variables)
5. **Template customizations** (name, display name, description, icon,
organization)
- **Alternative creation links** are shown on step 1: "Start from
scratch", "Upload an existing template", "Browse community templates",
"Use template agent skill"
- **Disabled via**: `CODER_DISABLE_TEMPLATE_BUILDER` env var /
`--disable-template-builder` flag. When disabled, redirects to old
`/templates/new` flow
- **Registry URL override**: `CODER_TEMPLATE_BUILDER_REGISTRY_URL`
(default: `registry.coder.com`)
- **Requires outbound access** to `registry.coder.com` for `terraform
init` at compose time
- **Modules are bundled** with the Coder release binary; the builder
does not fetch metadata from the registry at runtime
- **Sensitive variables** (secrets) are not collected by the builder;
they are deferred to workspace creation time
- **Module conflicts** show a warning but do not block creation
- **One-way**: No re-entry into the builder for existing templates; edit
HCL directly after creation

## Files to update

### Tier 1: Primary creation flow docs (significant rewrites)

#### 1. `docs/admin/templates/creating-templates.md`

**Current state**: Documents three creation paths: "From a starter
template" (primary), "From an existing template", "From scratch
(advanced)".

**Changes**:
- Add a new section **"Using the template builder"** as the first and
primary section (before "From a starter template").
- Describe the 5-step wizard flow: select base infrastructure, configure
base parameters, select modules, configure module settings, set template
customizations.
- Mention that the builder is enabled by default and requires outbound
access to `registry.coder.com`.
- Note that sensitive variables are collected from developers at
workspace creation, not during template building.
- Add a callout about disabling the builder for airgapped deployments
(`CODER_DISABLE_TEMPLATE_BUILDER`).
- Note the `CODER_TEMPLATE_BUILDER_REGISTRY_URL` option for self-hosted
registry mirrors.
- Keep existing "From a starter template", "From an existing template",
and "From scratch" sections largely intact, but reframe them as
alternative paths.
- Update the "From a starter template" Web UI instructions to note the
new entry point routing (the "New Template" button now goes to the
builder when enabled).
- Fix existing typo: "You can the [Coder CLI]" should be "You can use
the [Coder CLI]".

#### 2. `docs/start/first-template.md`

**Current state**: Beginner tutorial walking through creating a template
from the Docker starter template via the old flow. Has a typo (`s` at
end of line 32), commented-out workspace creation section, and TODO
notes.

**Changes**:
- Rewrite steps 2 and 3 to use the Template Builder as the primary path.
- Step 2: Navigate to **Templates**, select **New Template**, which
opens the Template Builder.
- Step 3: Walk through the builder wizard steps (select Docker base,
optionally select modules like code-server, configure template
name/description, create).
- Remove the typo on line 32 (`s`).
- Keep the "Modify your template" section (step 6) intact since it
covers post-creation editing which is unchanged.
- Remove or update the reference to "Starter Templates" as a separate
page since the builder subsumes that entry point.

#### 3. `docs/get-started/index.md`

**Current state**: Quickstart guide. Step 4 says "Select **Templates** →
**New Template**" then pick "Coder Quickstart" from starter templates.

**Changes**:
- Update Step 4 to describe using the Template Builder.
- The flow becomes: Select **Templates** → **New Template** → builder
opens → select **Coder Quickstart** as the base template → optionally
add modules → set name/description → **Create Template**.
- Update the "What just happened?" explanation to mention the builder
composed and validated the Terraform.
- Screenshot reference `create-quickstart-template.png` will need a new
screenshot (note this in the PR; screenshots are out of scope for this
change but should be flagged).

### Tier 2: Secondary references (targeted edits)

#### 4. `docs/admin/templates/index.md`

**Current state**: Overview page mentioning starter templates as the
primary creation path.

**Changes**:
- Update the "Starter templates" section to mention the Template Builder
as the recommended way to create templates, with starter templates
serving as base templates within the builder.
- Update the link to point to the builder section: `[Create a template
with the template
builder](./creating-templates.md#using-the-template-builder)`.
- Update the screenshot reference and caption. The "Starter Templates"
page screenshot may no longer be the first thing admins see.

#### 5. `docs/admin/templates/managing-templates/index.md`

**Current state**: Documents starter templates, editing, updating,
deleting.

**Changes**:
- Update the "Starter templates" section to mention the Template Builder
as the primary creation path, with starter templates available as base
templates within it.
- Update the image reference from `starter-templates.png` if it shows
the old flow.

#### 6. `docs/tutorials/template-from-scratch.md`

**Current state**: Detailed tutorial for writing a template from scratch
with Terraform.

**Changes**:
- Add a brief note at the top recommending the Template Builder for
users who want to create templates without writing Terraform, with a
link to
`docs/admin/templates/creating-templates.md#using-the-template-builder`.
- In section "7. Create the template in Coder" → "Dashboard" tab, update
the UI steps. The "Upload template" option is now accessed via the old
creation flow at `/templates/new` (or through the "Upload an existing
template" link in the builder's alternatives).
- Fix the inconsistency where text says `coder templates create` but the
code block uses `coder templates push`.

#### 7.
`docs/admin/integrations/devcontainers/envbuilder/add-envbuilder.md`

**Current state**: Documents creating envbuilder templates via
Dashboard, CLI, and Registry tabs.

**Changes**:
- In the Dashboard tab, update the instructions. The "Create Template"
button now opens the builder by default. Users need to use the "Upload
an existing template" alternative link or navigate to `/templates/new`
directly.
- Update "From scratch" reference since that option is now an
alternative link in the builder.
- The CLI and Registry tabs remain unchanged.

#### 8. `docs/install/airgap.md`

**Current state**: Documents air-gapped installations. No mention of
Template Builder.

**Changes**:
- Add a note in the relevant section about the Template Builder
requiring outbound access to `registry.coder.com`.
- Document `CODER_DISABLE_TEMPLATE_BUILDER` for fully air-gapped
deployments.
- Document `CODER_TEMPLATE_BUILDER_REGISTRY_URL` for deployments using a
self-hosted registry mirror.

#### 9. `docs/about/screenshots.md`

**Current state**: Contains a caption "Template administrators can
either create a new Template from scratch or choose a Starter Template".

**Changes**:
- Update the caption to mention the Template Builder as the primary
creation method.
- Screenshot reference may need updating (flag for new screenshot).

### Tier 3: Minor/link-only updates

#### 10. `docs/admin/users/organizations.md`

- If it references the old "Create Template" screen with an org picker,
add a note that the Template Builder also includes organization
selection in its final step.

#### 11. `docs/ai-coder/tasks.md`

- If it mentions creating templates, add a passing reference to the
Template Builder as an option.

## Files NOT to update

- `docs/reference/api/templatebuilder.md`: Auto-generated API reference.
Already correct.
- `docs/reference/api/schemas.md`: Auto-generated. Already correct.
- `docs/reference/cli/server.md`: Auto-generated. Already has
`--disable-template-builder` and `--template-builder-registry-url`.
- `docs/reference/cli/templates_create.md`: Already deprecated.
- `docs/reference/cli/templates.md`: No changes needed.

## Implementation order

1. `docs/admin/templates/creating-templates.md` (primary creation docs,
most content)
2. `docs/get-started/index.md` (quickstart)
3. `docs/start/first-template.md` (beginner tutorial)
4. `docs/admin/templates/index.md` (overview)
5. `docs/admin/templates/managing-templates/index.md` (managing
overview)
6. `docs/install/airgap.md` (airgap note)
7. `docs/tutorials/template-from-scratch.md` (from-scratch tutorial)
8. `docs/admin/integrations/devcontainers/envbuilder/add-envbuilder.md`
(envbuilder)
9. `docs/about/screenshots.md` (screenshot captions)
10. Minor link/reference updates in tier 3 files

## Style notes

- Follow the Diataxis framework; keep tutorials as tutorials, reference
as reference.
- Use present tense, active voice, second person.
- Bold for UI elements: **Templates**, **New Template**, **Create
Template**.
- No emdash/endash.
- Do not add screenshots; flag where new screenshots are needed as
comments/TODOs.
- Run `make fmt/markdown` and `make lint/markdown` after all changes.
- Verify all pages are already in `docs/manifest.json` (no new pages
being added, only existing pages being updated).

</details>

> 🤖 Generated by Coder Agents
 2026-07-06 11:15:59 -04:00
McKayla はな 1302e78283 ci: remove chromatic (#26777) 2026-06-29 08:57:07 -06:00
Nick Vigilante b95f2531b5 feat: populate docs prose style guide as a landing page plus subpages (#26632) 
Replace the `docs/.style/style-guide.md` scaffold with the populated
prose style guide,
structured as a `README.md` landing page plus one subpage per topic so
GitHub auto-renders the landing when readers open the style-guide
folder.

## Layout

```text
docs/.style/
  style-guide/
    README.md                          (landing: intro, section list, editing conventions, Vale enforcement)
    audience-and-scope.md              (one audience, one outcome, declared up front; canonical personas)
    voice-and-tone.md
    word-choice.md
    accessibility-and-inclusion.md     (new)
    capitalization-and-punctuation.md
    formatting.md                      (text formatting + block elements + screenshots sparingly)
    numbers-units-and-dates.md
    editor-setup.md                    (placeholder)
```

Every repo reference to the old path is rewired to the new path:
`AGENTS.md` (and its `CLAUDE.md` / `.cursorrules` symlinks),
`.claude/docs/DOCS_STYLE_GUIDE.md`,
`docs/about/contributing/documentation.md`, `docs/.style/README.md`,
`docs/.style/styles/Coder/README.md`, and a comment in
`.github/workflows/ci.yaml`. The touched paragraph in each of those
files is reformatted to one sentence per line per the touch-paragraph
rule (refer to [Conventions the guide
dogfoods](#conventions-the-guide-dogfoods)).

## What each page covers

- **Audience and scope** (new): every page targets **one audience
working toward one outcome**; the **install-vs-deploy Coder example**
(workspace user vs platform engineer); pick one audience per page (write
two pages and cross-link rather than tagging sections); pick one outcome
per page (`Configure SSO with Okta` is one outcome, `Configure SSO` is
not); declare audience and scope up front (the H1 names the outcome; the
first paragraph names the audience); **canonical Coder personas**
inlined as four primary (Dave the Developer, Ada the Infrastructure
Admin, Perry the Platform Engineer, Steven the Sponsor) and six
secondary (Melissa the Machine Learner, Tommy the Tester, Caitlin the
Citizen Developer, Felipe the FinOps, Sergio the Security Officer, Tara
the Team Leader), each with a `Coder surface:` line covering the
relevant CLI/workspace/template/RBAC surfaces.
- **Voice and tone**: address the reader directly, avoid first-person
singular, reserve first-person plural for **Coder Technologies the
company** (with an explicit ban on `we` for the product itself and on
combined `you and the docs`), active voice, present tense with a
**conditional/predictive `will` exception** (`If you do X, Y will
happen`), **no sentence-ending prepositions** with a clunky-exception
note.
- **Word choice**: Coder product and feature names with the **Coder CLI
always in backticks (`coder`)** rule, brand names with a parallel
**Terraform CLI in backticks (`terraform`)** rule, **Dev Container**
terminology (proper-noun specification vs lowercase instance, parallel
to Coder / workspace), **phrasal verbs and their noun forms generalized
as a table** (set up/setup, log in/login, sign in/sign-in, log
out/logout, back up/backup, roll out/rollout, start up/startup, shut
down/shutdown, with the `Quickstart` exception), `refer to` / `check
out` / `visit` over `see`, `Learn more` versus `Next steps` with an
**ableism rationale** (`steps` as a physical-mobility metaphor),
`tutorial` versus `walkthrough` with an **ableism rationale**,
**`select` over `click`**, **`Don&#39;t assume simplicity or
difficulty`** (covers both `simple`/`easy` and `complex`/`non-trivial`),
**`Avoid weasel words`** (vague attributions in the Wikipedia sense like
`many believe`, `experts agree`, `studies show`), plain language for
product actions with an **industry-term exception scope** for the Linux
`kill` command, the `SIGKILL` signal, and the `disabled` config flag
state.
- **Accessibility and inclusion** (new): WCAG 2.1 Level AA as the
minimum target with AAA as a stretch goal; heading structure (one H1 per
page, no skipped levels, **substantive content between headings**);
inclusive pronouns; inclusive-language substitutions including a
**dedicated `sanity check` row** with `smoke testing` / `confidence
testing` / `acceptance testing` alternatives; descriptive link text; alt
text and decorative-image conventions; **plain English for international
readers** (no idioms; common Latin abbreviations `e.g.`, `i.e.`, `etc.`,
`vs.`, and `et al.` allowed, less common ones not); page descriptions in
`docs/manifest.json` (the docs site does not yet support YAML front
matter); reading level; color contrast deferred to the docs site theme.
- **Capitalization and punctuation**: sentence-case headings, no
gerund-leading headings with **documented exceptions** (`Pricing`,
`Billing`, `Logging`, `String formatting`, etc.), **trailing heading
punctuation in three tiers** (periods and exclamation marks forbidden at
error severity, question marks allowed sparingly at suggestion severity,
characters inside backticks exempt for both), no em or en-dashes with a
**corrected example** showing parenthetical em-dash use rather than
series-joining, Oxford comma, US-style quotation, semicolons sparingly,
rare exclamation marks, numeric ranges.
- **Formatting**: text formatting (bold for UI with **explicit
greater-than separator rule for navigation paths**, italics for
emphasis, code font for identifiers presented as a **bulleted list**)
and block elements (code blocks with language fences plus **link to the
Prism supported-languages reference**, callouts with tightened
scenarios, tabs with the actual `` syntax and a **macOS/Linux/Windows
example**, lists with a **five-item prose-list cap rule** and an
**explicit terminal-punctuation rule** (complete sentences end in
periods, phrases completing a lead-in paragraph end in periods,
single-word labels carry no terminal punctuation, no mixing styles in
one list), tables with a **narrow-table guideline** that reconsiders the
structure when many columns are needed, links including the rule that
**non-docs codebase links also use relative paths**, images,
**screenshots sparingly** with a maintenance-burden rationale and an
adapted quote from Lorna Jane Mitchell&#39;s `Short tech writing style
guide for developers`), with cross-references to the accessibility page
for link text and alt text.
- **Numbers, units, and dates**: digits everywhere preference,
non-breaking space between number and unit with **separate pre-render
(Markdown source) and post-render (visible output) demonstrations** plus
a **window-shrink tip** for confirming the rule visually, `Month Day,
Year` date format, 12-hour time with AM/PM, ordinals exception.
- **Editor setup**: placeholder.

## Conventions the guide dogfoods

- **One sentence per line**. Source lines follow a one-sentence-per-line
policy: each sentence sits on its own Markdown source line, sentences
are not split across lines, and lines do not wrap to a fixed column
width. The same convention applies corpus-wide through an **incremental
touch-paragraph rule**: when a contributor edits any line inside a
paragraph, the whole paragraph is reformatted to one sentence per line
as part of the same edit. Bullet items, numbered list entries, and
blockquote lines are each their own paragraph for the rule. Headings,
fenced code blocks, and tables are out of scope. `markdownlint`&#39;s
`MD013` is already disabled, so the convention is editorial.
- **No navigational `see`**. Replaced with **refer to** (formal
default), **check out** (informal/tutorials), or **visit** (external
URLs). `See` is reserved for the observational meaning.
- **HTML entities for em-dashes inside demos**. The em-dash demo encodes
`—` / `–` so the source stays ASCII while the rendered output still
shows the character.
- **No semicolons in body prose**. Body prose prefers two sentences over
a semicolon. Semicolons survive only in heading and rule labels where
they act as separators.
- **Common Latin abbreviations allowed in own prose**. `e.g.`, `i.e.`,
`etc.`, `vs.`, and `et al.` (citation contexts) are fine. Less common
Latin abbreviations (`a priori`, `q.v.`, `viz.`, `n.b.`, `cf.`, `ibid.`)
are not. The rule covers punctuation too: prefer parentheses around
`e.g.` and `i.e.` clauses, one period when `etc.` ends a sentence, both
periods when `etc.` ends a parenthetical that ends a sentence.
- **No idioms or industry-jargon idioms**. `deep dive`, `paved path`,
etc. are rewritten in plain language.

## Rule conventions

Each rule pairs a rationale with **Do** / **Don&#39;t** blockquoted
examples and a parenthetical noting the Vale rule that enforces (or will
enforce) the policy. Documentation-only rules are explicitly labeled as
such. Substitution rules use tables.

## Out of scope

- Wiring any new Vale rule. Per-rule PRs land separately per the
rule-authoring doctrine in `docs/.style/README.md`.
- Editor setup page population.
- Redirecting `docs/about/contributing/documentation.md` to the
populated guide (needs a coordinated `coder.com` PR after merge).
- Trimming the `Writing Style` block in
`.claude/docs/DOCS_STYLE_GUIDE.md` and removing the `currently a
scaffold` framing in the agent docs.
- A separate demo PR for the callout types rendered against an existing
docs page.
- Sweeping navigational `see` out of other docs files. The new rule only
dogfoods on the style guide itself; a corpus-wide sweep is a separate
ticket.

## Validation

- `make fmt/markdown`: clean.
- `make lint/markdown`: 0 errors across 494 files.
- `./scripts/check_emdash.sh`: clean.
- Pre-commit-light: passes (fmt + lint + emdash + shellcheck + typos +
actionlint + migrations + helm).
- Dogfood scan: no first-person singular in own prose, no idioms, only
the five allowed Latin abbreviations in own prose, no `walkthrough` or
`Next steps` outside rule definitions and examples, no navigational
`see`, no `click` outside rule definitions and examples, no semicolons
in body prose.

<details>
<summary>CI flake note: <code>check-docs</code> (linkspector)</summary>

The `check-docs` job can fail intermittently on pre-existing external
links in `docs/about/contributing/documentation.md` (lines 29 and 30):
Merriam-Webster occasionally returns HTTP 403 to GitHub Actions runners
and Chicago Manual of Style can time out at 30s. Neither link is touched
by this PR. `docs/.style/` itself is in `.github/.linkspector.yml`
`excludedDirs`, and linkspector annotations confirm zero broken links
from the new pages.

</details>

Resolves DOCS-434.

---

*Filed via [Coder Agents](https://coder.com/docs/ai-coder/agents) on
Nick&#39;s behalf.*
 2026-06-25 21:11:39 +00:00
Nick Vigilante ed908ed019 fix(docs): repoint 7 broken external and anchor links (DOCS-415) (#26572) 
Closes [DOCS-415](https://linear.app/codercom/issue/DOCS-415).

## TL;DR

Repoints 7 broken links across 5 docs files that the 2026-06-22 weekly
`check-docs.yml` Linkspector run flagged. Two other links from the same
run (the dead `nix` ref and the dead `reflectoring.io` ref in
`CONTRIBUTING.md`) were already folded into
[#26341](https://github.com/coder/coder/pull/26341).

## Why

Broken external and anchor links degrade reader trust, leak SEO juice,
and make the docs look stale. The weekly `check-docs` job exists
precisely to catch this kind of rot before customers do; the
surfacing-to-fix turnaround on these 7 is one PR. Run that surfaced
them: [actions/runs/27948011619 job
82697664858](https://github.com/coder/coder/actions/runs/27948011619/job/82697664858).

## Scope

| File | Line(s) | Old target | New target | Why |
|------|---------|-----------|------------|-----|
| `docs/tutorials/best-practices/organizations.md` | 62 | anchor
`#update-template-metadata-by-id` | `#update-template-settings-by-id` |
API endpoint renamed in
[#19228](https://github.com/coder/coder/pull/19228) (Aug 2025). New
heading at line 1105 of `docs/reference/api/templates.md`. |
| `docs/install/registry-mirror-artifactory.md` | 197 | JFrog
`terraform-registry` |
`terraform-opentofu-and-terraform-backend-repositories` | JFrog
consolidated their Terraform / OpenTofu / Backend docs into a single
page. |
| `docs/admin/templates/extending-templates/modules.md` | 76, 206 |
JFrog `set-up-a-terraform-module/provider-registry` and
`terraform-registry` | same consolidated JFrog page (root, no anchor) |
Same JFrog consolidation. Anchor dropped, see decision log. |
| `docs/admin/integrations/dx-data-cloud.md` | 84 |
`https://help.getdx.com/en/` | `https://docs.getdx.com/` | DX migrated
their help center to a separate docs domain. |
| `docs/about/contributing/frontend.md` | 37, 71 |
`https://reactrouter.com/en/main` | `https://reactrouter.com/` | React
Router dropped the `/en/main` prefix. |

## Validation

- All 7 replacement URLs return HTTP 200 (manual `curl -L -o /dev/null
-w '%{http_code}'` per URL; linkspector's puppeteer crashed in the agent
env, so it was run case-by-case)
- `make lint/markdown lint/emdash` clean locally
- Pre-commit hook (`scripts/githooks/pre-commit` -> `make
pre-commit-light`) clean
- No `/docs/` route changes; pure markdown content

## Not triggering `/coder-agents-review`

Docs-only markdown edit, no CI or build config changes; per `AGENTS.md`
the bot review is reserved for product / CI changes. `doc-check` handles
this category.

## Pre-mortem

| Concern | Mitigation |
|---|---|
| Replacement URL also turns out to be broken later | All 7 verified
HTTP 200 today; next weekly `check-docs` run will catch any future
regression. |
| JFrog anchor drop on `modules.md` (76, 206) loses navigation context |
Verified the consolidated JFrog page has no clean section anchor for the
original target; linking the root page is the honest fix. If JFrog ships
a better TOC anchor later, a follow-up can reattach. |
| Anchor rename in `organizations.md` was actually a different rename |
Confirmed via PR #19228 (Aug 2025) which is the exact rename that
produced `## Update template settings by ID`. |

<details>
<summary>Decision log</summary>

**Why drop the anchor on the JFrog `modules.md` links (76 + 206)**:
JFrog's new consolidated page
(`/terraform-opentofu-and-terraform-backend-repositories`) doesn't
expose the original `set-up-a-terraform-module/provider-registry`
section as a fragment-link target. The honest fix is to link the page
root; readers can scroll. The `registry-mirror-artifactory.md:197`
reference uses the same root link for symmetry.

**Why DX `docs.getdx.com` over `help.getdx.com`**: DX's help center at
`help.getdx.com/en/` now returns 404. They moved to a separate
`docs.getdx.com` domain with a different content structure. Linking the
docs root is the closest analog to the original "browse our docs"
intent.

**Why React Router root over `/en/main`**: React Router unified their
docs under the root URL. The `/en/main` prefix is no longer routable.
The root URL is the canonical successor.

</details>


<details>
<summary>CI: <code>audit-docs-paths</code> failure (pre-existing,
unrelated)</summary>

The `audit-docs-paths` job in `.github/workflows/weekly-docs.yaml` fails
on this PR because its `Fetch redirects.json` step issues an
unauthenticated `curl` to a file in private `coder/coder.com` and gets a
404 (exit code 22). Same failure on every recent PR in this repo.
Tracked in [DOCS-409](https://linear.app/codercom/issue/DOCS-409) and
fixed in [#26571](https://github.com/coder/coder/pull/26571), which
authenticates the fetch through the Contents API. My changes are
docs-content only (5 markdown files, 7 line changes) and don't touch the
TS/TSX paths or `redirects.json` that the audit examines, so this is a
pre-existing CI break, not a regression introduced here.

</details>

---

*Generated by Coder Agents on @nickvigilante's behalf.*
 2026-06-22 17:04:19 -04:00
Nick Vigilante ee3572ab9a feat: wire Vale prose linter into docs CI (#25467) 
Wires Vale into docs CI as an advisory (non-blocking) prose-lint step.
Closes [DOCS-40](https://linear.app/codercom/issue/DOCS-40).

> **Integration update (rebased onto `main`).** Since this branch was
opened, `main` consolidated docs linting into the **required**
`lint-docs` job in `ci.yaml` and removed the standalone `docs-ci.yaml`
([#25608](https://github.com/coder/coder/pull/25608)). This PR adds Vale
to that `lint-docs` job instead of resurrecting `docs-ci.yaml`, and the
`docs/.style/` scaffold defers to the merged
[#25466](https://github.com/coder/coder/pull/25466) (DOCS-180). Vale
stays advisory.

> **Post-review refactor.** Following the Coder Agents review, Vale is
now invoked through `mise exec "aqua:errata-ai/vale"` (the same pattern
as `actionlint`/`zizmor`) instead of a bespoke `curl`/`tar` download.
This removed the GNU-only `grep -oP` version extraction and `uname`/arch
mapping that broke on macOS BSD grep, and the prose step now skips paths
a PR deletes. See the resolved review threads for CRF-17/19/20/21/22.

A sample of what this check does is as follows:

<img width="1443" height="1293" alt="image"
src="https://github.com/user-attachments/assets/cf68dbf9-d9df-49ba-8dbf-200875bc289e"
/>

## What changes

- `.vale.ini` at the repo root: Google base + Coder (custom, empty in
v1) + curated write-good. `alex` rules are pulled in a la carte. Inline
comments justify every enable/disable.
- `mise.toml`: pin Vale `3.7.1` via aqua. `mise.lock`: lock that pin
across all platforms so `mise install --locked` (used by `build_image`)
resolves it.
- `Makefile`: a `docs/.style/.vale-synced` sentinel that gates `vale
sync`, and a `lint/prose` target that runs `vale --no-exit`. Both invoke
Vale via `mise exec "aqua:errata-ai/vale" -- vale ...`, so mise owns the
version and the OS/arch download (no hand-rolled install path).
- `.github/workflows/ci.yaml`: append Vale steps to the existing
required `lint-docs` job: `Detect changed Markdown`, `Restore Vale
styles`, `Prepare Vale styles` (`make docs/.style/.vale-synced`), `Vale
prose lint`, and a default-branch-only `Save Vale styles`. They lint
only changed Markdown under `docs/` that still exists on disk, with a
problem matcher for inline PR annotations.
- `.github/vale-problem-matcher.json`: parses `vale --output=line` so
alerts surface as annotations on the Files Changed tab.
- `.gitignore` and the workflow cache `path:`: use
`docs/.style/styles/*` plus a `!docs/.style/styles/Coder` negation so
adding a package does not require parallel edits.
- `.markdownlint-cli2.jsonc`: ignore the synced styles so `make
lint/markdown` does not lint upstream READMEs.

Scaffold prose under `docs/.style/` and
`.claude/docs/DOCS_STYLE_GUIDE.md` / `AGENTS.md` come from the merged
DOCS-180; this PR no longer touches them. Net diff against `main` is the
8 Vale-wiring files only.

## Severity policy (v1)

Rule severity reflects two things together: the rule's false-positive
rate against real Coder docs and the gravity of the rule. Low FPs plus
high gravity argues for `error`; lower gravity or more judgment calls
argue for `warning` or `suggestion`. v1 lands most rules at `warning`
and the wordiness rules at `suggestion`.

A rule promotes to `error` only when (a) its false-positive rate against
real content is effectively zero and (b) the existing-content violation
count for that rule is also zero. Vale exits non-zero only on
error-level alerts regardless of `MinAlertLevel`; the Makefile and CI
invoke Vale with `--no-exit` so the baseline error count from
un-overridden Google rules does not fail the build while real failures
(bad config, missing files) still propagate.

## CI integration

Vale runs as steps appended to the required `lint-docs` job in
`ci.yaml`, gated on changed Markdown:

1. **`Detect changed Markdown`** (`tj-actions/changed-files`) scopes to
changed `**.md`; the prose step re-filters to `docs/` (the `docs/**.md`
glob silently skips dot-prefixed dirs and would miss
`docs/.style/style-guide.md`).
2. **`Restore Vale styles`** (`actions/cache/restore`), keyed off
`hashFiles('.vale.ini', 'mise.toml', 'docs/.style/styles/Coder/**')`.
mise manages the Vale binary, so only the synced styles are cached.
3. **`Prepare Vale styles`** runs `make docs/.style/.vale-synced` (`mise
exec ... vale sync`).
4. **`Vale prose lint`** filters the changed set to `docs/` paths still
present on disk, then runs `mise exec ... vale --no-exit --output=line`,
emitting inline annotations via the problem matcher.
5. **`Save Vale styles`** writes the cache, gated to `refs/heads/main`
only so PR runs cannot poison the cache other branches restore from (the
zizmor `cache-poisoning` concern).

**Every Vale step is `continue-on-error: true`.** This is a deliberate
change from the original standalone-workflow design: now that Vale lives
inside the *required* `lint-docs` job, a transient `vale sync` network
failure (or first-use `mise` install blip) would otherwise block merges.
`continue-on-error` keeps Vale advisory, so only the markdownlint /
table-formatter checks above (`pnpm check-docs`) remain merge-blocking.
`vale --no-exit` additionally keeps the baseline error count from
un-overridden Google rules from failing the step.

## Verification

- `actionlint` clean on `ci.yaml` (local + `make
lint/actions/actionlint`); `zizmor --persona regular` reports no
findings.
- `make lint/prose` on the full `docs/` corpus: ~406 errors, ~5,346
warnings, ~7,928 suggestions across 461 files, exit 0 (`--no-exit`),
Vale `3.7.1` installed by mise.
- Net diff vs `main` is the 8 Vale-wiring files only; the `docs/.style/`
scaffold already matches `main`.

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

### Why this rule set

The Vale evaluation against the full docs corpus (measured 2026-05-18)
produced ~43,940 raw violations across six candidate base styles. The
selection here drops Microsoft and RedHat (overlap with Google, and
RedHat's Spacing rule hammers technical IDs), and proselint (Annotations
rule treats `> [!NOTE]` admonitions as TODO markers).

Within the kept styles:

- **Google** is the base. Disables: `EmDash` (conflicts with `make
lint/emdash`), `Latin` (i.e./e.g. are fine for our audience), `Spacing`
(4,500 errors on `codersdk.SomeType` patterns in the auto-generated API
reference). Softened: `Parens` to `suggestion`, `WordList` to `warning`.
- **write-good** is the base, with `Passive` and `E-Prime` off.
`TooWordy` and `ThereIs` are suggestions; `Weasel` is a warning.
- **alex** is cherry-picked (not in `BasedOnStyles`): `Ablist`,
`Condescending`, `LGBTQ`, `ProfanityLikely`, `Race`, `Suicide` at
warning. The `ProfanityMaybe`/`ProfanityUnlikely` rules trip on
`execute`, `kill`, `failed`, and `attack`, which read as technical
vocabulary in our context.
- **Coder** is in `BasedOnStyles` but the directory is empty in v1.
Rules land through the per-rule tickets in the [Docs style
guide](https://linear.app/codercom/project/docs-style-guide-7828445b9afc)
project.

### Why `mise exec` instead of a download block

Vale is pinned in `mise.toml` like `actionlint` and `zizmor`, so
invoking it via `mise exec "aqua:errata-ai/vale" -- vale ...` makes the
pin the single source of truth and lets mise handle the OS/arch-specific
download. This replaced an earlier ~30-line `curl`/`tar` block whose
GNU-only `grep -oP ...\K` version extraction returned empty on macOS BSD
grep. Note: the bare `vale` short name in `mise exec` ignores the pin
and resolves to the latest release, so the full aqua key is required.

### Why `vale sync` instead of vendoring

The three style packages weigh ~272 KB combined, so vendoring is cheap.
But Vale's ecosystem treats `Packages = ` + `vale sync` as canonical,
the upstream LICENSE files are not in the package tarballs (would need
to be added manually), and the CI cache makes the sync nearly free after
the first run. Sticking with the canonical pattern keeps the repo lean
and the upgrade path obvious.

### Why `lint/prose` is not in `lint:` or `lint-light:`

Vale on the full docs corpus takes ~20s on cold caches. Forcing every
pre-commit through that would be aggressive for a feature that ships as
warnings. `make lint/typos` follows the same pattern (it is in
`lint-light` but not `lint`; CI invokes it directly). v1 keeps Vale
opt-in locally and CI-only by default; promote to `lint:` once the rule
set stabilizes.

### Exit-code handling

Two mechanisms combine, and the choice changed when the step moved into
the required `lint-docs` job:

- `vale --no-exit` suppresses Vale's non-zero exit on alerts, so the
baseline error-level violations from un-overridden Google rules do not
fail the step while the cleanup PRs land. Real failures (config invalid,
file missing) still exit non-zero.
- `continue-on-error: true` on every Vale step. Because the steps now
run inside the *required* `lint-docs` job, a `vale sync`
download/network blip must not block merges. The original (standalone,
non-required) design rejected `continue-on-error` for showing a
misleading yellow badge; in a required job that tradeoff flips, and
advisory-yellow is strictly preferable to merge-blocking-red on an
infrastructure flake. `|| true` in the Makefile was also rejected: it
swallows missing-config failures indiscriminately.

### Pre-mortem

- **Generated docs noise**: `docs/reference/` is dominated by
auto-generated content (clidocgen, apidocgen, auditdocgen,
metricsdocgen). The architectural decision is to fix the generators, not
exclude paths in Vale. Google.Spacing is the only rule silenced
specifically to defer the generator fix; everything else surfaces as
warnings.
- **First-run cost**: `mise` installs the pinned Vale (a single small
binary) and `vale sync` pulls the style packages on a cold run. The
Actions cache keyed off `hashFiles('.vale.ini', 'mise.toml',
'docs/.style/styles/Coder/**')` makes subsequent runs near-instant; the
`Coder/**` hash is defense-in-depth against
[actions/toolkit#713](https://github.com/actions/toolkit/issues/713) so
a future cache release that regresses path-negation cannot serve a stale
`Coder/` from cache.
- **Required-job blast radius**: moving Vale into the required
`lint-docs` job means any Vale step failure would gate merges. Mitigated
by `continue-on-error` on all Vale steps plus a clean skip when no
changed `docs/` Markdown remains on disk, so only `pnpm check-docs`
stays blocking.
- **Cross-platform install**: handled by mise (aqua backend) rather than
a hand-rolled `uname`/arch map, which removes the macOS BSD-grep break
the review flagged.
- **Deleted files**: `all_changed_files` is ACMRD and lists paths a PR
removes; the prose step filters to files still present on disk so Vale
does not error on a missing file.
- **Local-vs-CI parity**: CI lints changed files only; local `make
lint/prose` lints the full tree. This mirrors `make lint/markdown` (full
tree) vs the changed-files CI step. Acceptable for v1.

</details>

---

*Filed via [Coder Agents](https://coder.com/docs/ai-coder/agents) on
Nick's behalf.*
 2026-06-22 14:14:31 -04:00
Nick Vigilante e458692cb8 refactor(docs): convert absolute coder/coder blob/tree/main links to relative (DOCS-351) (#26341) 
Closes [DOCS-351](https://linear.app/codercom/issue/DOCS-351).

> [!WARNING]
> **DO NOT MERGE** until
[DOCS-349](https://linear.app/codercom/issue/DOCS-349)
([coder.com#877](https://github.com/coder/coder.com/pull/877)) has
shipped to production and baked for at least one Vercel cycle.
>
> Without DOCS-349, the relative links in this PR resolve to broken
docs-route URLs (`/docs/helm/coder/values.yaml` -> 404) instead of
GitHub URLs tagged with the displayed docs version. DOCS-349 fixes the
rewriter to classify these as GitHub blob/tree URLs with the page's
resolved ref.

## TL;DR

Converts 121 absolute
`https://github.com/coder/coder/(blob|tree)/main/<path>` links across 39
docs markdown files to relative paths. After this lands AND DOCS-349
deploys, every one of these links will follow the displayed docs version
(mainline tag on bare URLs, explicit tag on `/@vX.Y.Z/`, `main` on
`/@main/`) instead of always pointing to `main`.

## Why

Today a reader on `/docs/@v2.30.0/install/docker` follows a
`compose.yaml` link and arrives at `main`'s `compose.yaml`, which
doesn't necessarily match what the docs page describes. Helm values,
Terraform templates, and source-code references in particular drift
across versions. The fix is to let the coder.com rewriter substitute the
page's resolved ref into the URL; that only works on relative links.

## Example payoff (post-DOCS-349)

| URL | Today (absolute, always `main`) | After (relative + rewriter) |
|---|---|---|
| `/docs/install/docker` |
`https://github.com/coder/coder/blob/main/compose.yaml` |
`https://github.com/coder/coder/blob/v2.34.1/compose.yaml` (today's
mainline) |
| `/docs/@v2.30.0/install/docker` | same as above |
`https://github.com/coder/coder/blob/v2.30.0/compose.yaml` |
| `/docs/@main/install/docker` | same as above |
`https://github.com/coder/coder/blob/main/compose.yaml` |

## Scope

- **121 conversions** across **39 files**.
- Verb breakdown: `tree/main` (directories) and `blob/main` (files),
both flipped to relative paths.
- Line anchors (`#L23-L24`) and query strings preserved verbatim.
- Conversion is mechanical: relative path computed from the doc file's
directory to the target via `os.path.relpath`. Any path starting at the
same directory or below gets a `./` prefix; otherwise `../` chains.

## Rebased on main

The branch was rebased onto `main` after the DOCS-350 hotfix
([#26339](https://github.com/coder/coder/pull/26339)) merged. The hotfix
repointed 3 `docs-backend-contrib-guide` refs in `backend.md` to `main`,
which then needed the same `main` -> relative conversion this PR is
doing for the other 121 links. The conflict was resolved by reapplying
the mechanical conversion to `backend.md` after taking the hotfix's
content. Net result: those 3 links land here as relative, same as
everything else. New HEAD `3f501cb622`.

## Inline fix folded in: dead `nix` link

- `docs/about/contributing/CONTRIBUTING.md:7` -> `../../../nix`

The original absolute URL `https://github.com/coder/coder/tree/main/nix`
already returned 404 today. Repointed to `flake.nix` (modern Nix
entrypoint, what the prose "Nix environment" semantically refers to).
Closes [DOCS-357](https://linear.app/codercom/issue/DOCS-357) here since
the `check-docs` Linkspector job surfaced it during rebase; cheaper to
fix inline than in a separate single-line PR.

## Out of scope (filed separately)

- [DOCS-350](https://linear.app/codercom/issue/DOCS-350): 3 dead
`docs-backend-contrib-guide` branch refs in `backend.md`
([#26339](https://github.com/coder/coder/pull/26339), merged).
- [DOCS-352](https://linear.app/codercom/issue/DOCS-352): 10 SHA-pinned
`(blob|tree)/<sha>` links pending intent review.
- [DOCS-355](https://linear.app/codercom/issue/DOCS-355): code-server
analog (4 absolute `(blob|tree)/main` links in `coder/code-server`).
- [DOCS-356](https://linear.app/codercom/issue/DOCS-356): 2 upstream
content bugs in `coder/code-server/docs/CONTRIBUTING.md` (independent of
this PR).


## Not triggering `/coder-agents-review`

Docs-only edit; per `AGENTS.md` the bot review is reserved for
product/CI changes.

## Pre-mortem

| Concern | Mitigation |
|---|---|
| Merging before DOCS-349 deploys regresses ~120 currently-working links
into 404s on coder.com | Clear DO-NOT-MERGE banner; tracked as blocker
in Linear. |
| Relative path computed incorrectly (off-by-one `..`) | Verified all
114 newly-relative non-md/non-image paths resolve to existing files in
the repo (only exception is the pre-existing dead `nix` link above). |
| Line anchors stripped during conversion | Preserved by the
substitution regex; verified `#L<n>-L<m>` cases in `airgap.md` and
`speed-up-templates.md`. |
| Future code reorgs change file locations | Relative links will start
pointing to nothing. Same failure mode as absolute links pointing to
renamed files; can be caught with a future link-checker job. |

## Validation

```
$ grep -rE 'github\.com/coder/coder/(blob|tree)/main' docs --include="*.md" | wc -l
0
$ git diff --stat origin/main | tail -1
39 files changed, 118 insertions(+), 118 deletions(-)
```

114 newly-relative paths verified to resolve to existing repo files
(Python `os.path.exists` check on each computed target).

<details>
<summary>Decision log + planning context</summary>

**Why relative over `(blob|tree)/{{currentDocsVersion}}/...`
templating**: relative paths require zero markdown-system support and
zero upstream churn beyond this one PR. Templating would require a
preprocessor on `coder.com` side AND a convention upstream authors have
to remember; relative paths just work in a plain editor and
`github.com`'s own renderer too.

**Why `./` prefix on same-directory targets**: makes the conversion
grep-able later (`grep -E '\((\.\./|\./)'`).

**Why preserve `#L<n>-L<m>` anchors verbatim**: the anchor is meaningful
to the linked file's content, not to the URL form; keeping it as-is
preserves authorial intent. If the file later changes such that the line
range drifts, that's a different problem the SHA-pin audit
([DOCS-352](https://linear.app/codercom/issue/DOCS-352)) will surface.

</details>

---

*Generated by Coder Agents on @nickvigilante's behalf.*





## Drive-by external link fix folded in

`docs/about/contributing/CONTRIBUTING.md:296` cited
`https://reflectoring.io/meaningful-commit-messages/` which is returning
HTTP 503 (the host appears to be down site-wide right now). `check-docs`
Linkspector flagged it after the rebase. Replaced with
`https://cbea.ms/git-commit/` (Chris Beams' canonical "If applied, this
commit will..." article, confirmed 200), which is the original source of
the rule the prose recites anyway.
 2026-06-22 11:39:12 -04:00
Nick Vigilante e18c86354c fix(docs/about/contributing): repoint dead docs-backend-contrib-guide refs to main (DOCS-350) (#26339) 
Closes [DOCS-350](https://linear.app/codercom/issue/DOCS-350).

## Problem

Three GitHub links in `docs/about/contributing/backend.md` are pinned to
a feature branch (`docs-backend-contrib-guide`) that no longer exists in
this repo. All three return HTTP 404 on github.com today.

| File:line | Link text | Bad URL |
|---|---|---|
| `docs/about/contributing/backend.md:53` | `cliui` |
`https://github.com/coder/coder/tree/docs-backend-contrib-guide/cli/cliui`
|
| `docs/about/contributing/backend.md:53` | `testdata` |
`https://github.com/coder/coder/tree/docs-backend-contrib-guide/cli/testdata`
|
| `docs/about/contributing/backend.md:75` | `Go functions` |
`https://github.com/coder/coder/blob/docs-backend-contrib-guide/coderd/database/queries.sql.go`
|

## Fix

Repoint each URL's branch segment to `main`. All three targets exist on
`main` unchanged.

## Verification

```
$ curl -fsS -o /dev/null -w '%{http_code}\n' https://github.com/coder/coder/tree/main/cli/cliui
200
$ curl -fsS -o /dev/null -w '%{http_code}\n' https://github.com/coder/coder/tree/main/cli/testdata
200
$ curl -fsS -o /dev/null -w '%{http_code}\n' https://github.com/coder/coder/blob/main/coderd/database/queries.sql.go
200
```

## Not triggering `/coder-agents-review`

Docs-only edit; per `AGENTS.md` the bot review is reserved for
product/CI changes.

## Future-state note

These three URLs are absolute `(blob|tree)/main` references. They will
eventually be flipped to relative paths by
[DOCS-351](https://linear.app/codercom/issue/DOCS-351) once the
coder.com rewriter classifier fix
([DOCS-349](https://linear.app/codercom/issue/DOCS-349)) ships.
Repointing to `main` here is the right interim fix.

---

*Generated by Coder Agents on @nickvigilante's behalf.*
 2026-06-12 12:03:42 -04:00
Garrett Delfosse b95697a370 ci: rewrite release workflow to be fully GitHub Actions-driven (#25162) 
Replace the local interactive release CLI and legacy shell scripts with
a non-interactive Go tool (`scripts/release-action/`) and a rewritten
`release.yaml` workflow. Release managers trigger releases from the
GitHub Actions UI by selecting a branch, picking a release type (`rc`,
`release`, or `create-release-branch`), and optionally providing a
commit SHA.

The Go tool has four subcommands: `calculate-version` (computes next
version from git state), `generate-notes` (release notes from commit log
and PR metadata), `publish` (creates GitHub release with checksums), and
the workflow handles tag creation, branch creation, building, and
downstream publishing.

`scripts/version.sh` fallback now uses `git describe` (nearest ancestor
tag) instead of global latest so dev builds on release branches show the
correct version series.
 2026-06-04 14:38:48 -04:00
Thomas Kosiewski fe257666d7 ci: refactor CI to use mise for shared tool setup (#25727) 2026-06-01 15:55:19 +02:00
Nick VigilanteandClaude Opus 4.8 ca337915cc docs: fix broken and naked relative links (#25825) 
Several relative links in the docs pointed at pages that no longer exist
or rendered incorrectly on coder.com.

Fixes:

- `start/first-template.md`: IDE links repointed from the removed
`../ides.md` / `../ides/web-ides.md` to their current homes under
`user-guides/workspace-access/`.
- `tutorials/example-guide.md`: contributing link repointed to
`../about/contributing/documentation.md`.
- `about/contributing/backend.md`: the `migrations/testdata/fixtures`
and `full_dumps` references (and the `000024_example.up.sql` example)
used relative paths that escape `docs/` and render as bogus
`/docs/coderd/...` routes on the site. Normalized to the canonical
`github.com/coder/coder/(blob|tree)/main/...` form already used by ~120
other source links in the docs.
- Normalized extensionless directory links (`ai-coder/ai-gateway`,
`user-guides/workspace-access`, `install`) to their `/index.md` targets
for consistency with the rest of the docs.

This class of bug is invisible to the local doc checks (`make
lint/markdown` / `pnpm check-docs` only run markdownlint + table
formatting); only CI's Linkspector job validates link targets. Found via
a relative-link audit while investigating the docs preview on #25816.

Source-link version-awareness (so older docs versions don't all point at
`main`) is tracked separately in DOCS-268 and will be handled in the
coder.com render layer.


Linear: DOCS-278

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
 2026-06-01 08:47:29 -04:00
DevCats b89ddb593d docs: add coder-templates skill references to quickstart and template contribution guides (#24383) 
Adds TIP alerts to the quickstart guide and the template contribution
guide linking to the
[coder-templates](https://github.com/coder/registry/blob/main/.agents/skills/coder-templates/SKILL.md)
agent skill from the Coder Registry. This gives contributors and new
users a pointer to AI-assisted template authoring when they first
encounter template creation.
 2026-04-16 12:04:30 -05:00
Kayla はな b149433138 chore: complete jest to vitest migration (#24216) 2026-04-10 14:04:24 -06:00
Garrett Delfosse a3de0fc78d ci: add automatic backport workflow (#24025) 
Adds a GitHub Actions workflow that automatically cherry-picks merged
PRs to the last 3 release branches when the `backport` label is applied.

## How it works

1. Add the `backport` label to any PR targeting `main` (before or after
merge).
2. On merge (or on label if already merged), the workflow discovers the
latest 3 `release/*` branches by semver.
3. For each branch, it cherry-picks the merge commit (`-x -m1`) and
opens a PR.

Created backport PRs follow existing repo conventions:
- **Branch:** `backport/<pr>-to-<version>`
- **Title:** `<original PR title> (#<pr>)` — e.g. `fix(site): correct
button alignment (#12345)`
- **Body:** links back to the original PR and merge commit

If cherry-pick has conflicts, the PR is still opened with instructions
for manual resolution — no conflict markers are committed.

Also:
- Removes `scripts/backport-pr.sh` (replaced by this workflow)
- Removes `.github/cherry-pick-bot.yml` (old bot config)
- Adds a section to the contributing docs explaining how to use the
backport label

> [!NOTE]
> Generated with [Coder Agents](https://coder.com/agents)
 2026-04-08 14:30:48 +00:00
Garrett Delfosse ab77154975 ci: add cherry-pick to latest release workflow (#24051) 
Adds a GitHub Actions workflow that cherry-picks merged PRs to the
latest release branch when the `cherry-pick` label is applied.

## How it works

1. Add the `cherry-pick` label to any PR targeting `main` (before or
after merge).
2. On merge (or on label if already merged), the workflow detects the
latest `release/*` branch.
3. It cherry-picks the merge commit (`-x -m1`) and opens a PR.

This complements the `backport` label (see #24025) which targets the
latest **3** release branches. `cherry-pick` targets only the **latest**
one — useful for getting fixes into the current release.

Created PRs follow existing repo conventions:
- **Branch:** `backport/<pr>-to-<version>`
- **Title:** `<original PR title> (#<pr>)` — e.g. `fix(site): correct
button alignment (#12345)`
- **Body:** links back to the original PR and merge commit

If the cherry-pick encounters conflicts, the workflow aborts the
cherry-pick, creates an empty commit with resolution instructions, and
opens the PR with a `[CONFLICT]` prefix so the author can resolve
manually.

Also:
- Removes `scripts/backport-pr.sh` (replaced by this workflow)
- Removes `.github/cherry-pick-bot.yml` (old bot config)
- Adds a section to the contributing docs explaining the `cherry-pick`
label

> [!NOTE]
> Generated with [Coder Agents](https://coder.com/agents)
 2026-04-08 10:22:33 -04:00
Garrett Delfosse 48bc215f20 chore: tag RCs on main, cut release branch only for releases (#24001) 
RC tags are now created directly on `main`. The `release/X.Y` branch is
only cut when the actual release is ready. This eliminates the need to
cherry-pick hundreds of commits from main onto the release branch
between the first RC and the release.

## Workflow

```
main:  ──●──●──●──●──●──●──●──●──●──
              ↑           ↑     ↑
           rc.0        rc.1    cut release/2.34, tag v2.34.0
                                     \
                               release/2.34:  ──●── v2.34.1 (patch)
```

1. **RC:** On `main`, run `./scripts/release.sh`. The tool detects main
(or a detached HEAD reachable from main), prompts for the commit SHA to
tag, suggests the next RC version, and tags it.
2. **Release:** When the RC is blessed, create `release/X.Y` from `main`
(or the specific RC commit). Switch to that branch and run
`./scripts/release.sh`, which suggests `vX.Y.0`.
3. **Patch:** Cherry-pick fixes onto `release/X.Y` and run
`./scripts/release.sh` from that branch.

## Changes

### `scripts/releaser/release.go`
- Two modes based on branch:
- **`main` (or detached HEAD from main)** — RC tagging. Prompts for the
commit SHA to tag (defaults to HEAD). Always checks out the target
commit so the flow operates in detached HEAD. Suggests the next RC based
on existing RC tags.
- **`release/X.Y`** — Release/patch mode. Suggests `vX.Y.0` if the
latest tag is an RC, or the next patch otherwise.
- Detached HEAD support: if `git branch --show-current` is empty, checks
whether HEAD is an ancestor of `origin/main` and enters RC mode
automatically.
- Commit selection prompt in RC mode: shows current commit, lets the
user confirm or provide a different SHA.
- Warns if you try to tag a non-RC on main, or an RC on a release
branch.
- Skips open-PR check and branch sync check in RC mode (not useful on
main).

### `scripts/releaser/main.go`
- Updated help text.

### `.github/workflows/release.yaml`
- RC tags (`*-rc.*`): skip the release-branch validation (they live on
main).
- Non-RC tags: still require the corresponding `release/X.Y` branch.

### `docs/about/contributing/CONTRIBUTING.md`
- Rewrote the Releases section with the new workflow, release types
table, and ASCII diagram.
- Replaced the old "Creating a release" / "Creating a release (via
workflow dispatch)" subsections.

<details><summary>Decision log</summary>

### Why this approach?

Previously, cutting a release branch early for an RC meant
cherry-picking all of main's progress onto that branch before the actual
release — often hundreds of commits. This approach avoids that entirely:
RCs are just tagged snapshots of main, and the release branch only
exists once you need it for stabilization and backports.

### Files NOT changed

- **`scripts/release/publish.sh`** — `--rc` flag controls GitHub
prerelease marking (tag-level, not branch-level). `target_commitish`
already defaults to `main` when the tag isn't on a release branch.
- **`scripts/release/tag_version.sh`** — No RC-specific branch logic.
- **`scripts/releaser/version.go`** — Version parsing/comparison
unchanged.
- **`docs/install/releases/index.md`** — Public-facing docs describe RC
as a release channel with no branch-level detail.

</details>

> Generated by Coder Agents
 2026-04-07 15:21:22 -04:00
Kayla はな 0e69e0eaca chore: modernize typescript api client/types imports (#23637) 2026-03-25 15:21:19 -06:00
Mathias Fredriksson 78b18e72bf feat: add automatic database migration recovery to scripts/develop (#23466) 
When developers switch branches, the database may have migrations
from the other branch that don't exist in the current binary.
This causes coder server to fail at startup, leaving developers
stuck.

The develop script now detects this before starting the server:

1. Connects to postgres (starts temp embedded instance for
   built-in postgres, or uses CODER_PG_CONNECTION_URL).
2. Compares DB version against the source's latest migration.
3. If DB is ahead, searches git history for the missing down
   SQL files and applies them in a transaction.
4. If git recovery fails (ambiguous versions across branches,
   missing files), falls back to resetting the public schema.

Also adds --reset-db and --skip-db-recovery flags.
 2026-03-24 22:04:56 +02:00
Mathias Fredriksson 89eaf6ad74 docs: document smart hook file classification in CONTRIBUTING (#23370) 
The git hooks now classify staged files and select either the full
or lightweight make target. This was missing from the contributing
guide after #23358 landed.

Also add actionlint config to suppress a pre-existing SC2016 false
positive in the triage workflow. Shellcheck disable directives
don't work inside heredocs when actionlint drives shellcheck.
 2026-03-20 17:36:50 +02:00
Mathias Fredriksson aa6f301305 ci: add conventional commit PR title linting (#23096) 
Restore PR title validation that was removed in 828f33a when
cdr-bot was expected to handle it. That bot has since been disabled.

The new title job in contrib.yaml validates:
- Conventional commit format (type(scope): description)
- Type from the same set used by release notes generation
- Scope validity derived from the changed files in the PR diff
- All changed files fall under the declared scope

Uses actions/github-script (no third-party marketplace actions).

Also fixes feat(api) examples across docs (no api folder exists)
and consolidates commit rules into CONTRIBUTING.md as the single
source of truth.
 2026-03-16 12:24:59 +02:00
Mathias Fredriksson 57af7abf1f test: add testutil.WaitBuffer and replace time.Sleep in tests (#22922) 
WaitBuffer is a thread-safe io.Writer that supports blocking until
accumulated output matches a substring or custom predicate. It
replaces ad-hoc safeBuffer/syncWriter types and time.Sleep-based
poll loops in tests with signal-driven waits.

- WaitFor/WaitForNth/WaitForCond for blocking on output
- Replace custom buffer types in cli/sync_test.go and
  provisionersdk/agent_test.go
- Convert time.Sleep poll loops to require.Eventually/require.Never
  in cli/ssh_test.go, coderd/activitybump_test.go,
  coderd/workspaceagentsrpc_test.go, workspaceproxy_test.go, and
  scaletest tests
 2026-03-12 18:07:52 +02:00
Mathias FredrikssonandCian Johnston 660a3dad21 feat(scripts/githooks): restore pre-push hook with allowlist (#22980) 
The pre-push hook was removed in #22956. This restores it with a
reduced scope (tests + site build) and an allowlist so it only runs
for developers who opt in.

Two opt-in mechanisms:

- git config coder.pre-push true (local, not committed)
- CODER_WORKSPACE_OWNER_NAME allowlist in the hook script

git config takes priority and also supports explicit opt-out for
allowlisted users (git config coder.pre-push false).

Refs #22956

---------

Co-authored-by: Cian Johnston <cian@coder.com>
 2026-03-12 12:13:55 +02:00
Thomas Kosiewski e96cd5cbb2 chore(githooks): remove pre-push hook (#22956) 
## Summary
- remove the `pre-push` git hook script from the repository
- remove the `make pre-push` target and related Makefile documentation
- update contributor and agent docs so they only describe the remaining
`pre-commit` hook

## Validation
- `make pre-commit`
- `git diff --check`

---
_Generated with [`mux`](https://github.com/coder/mux) • Model:
`openai:gpt-5.4` • Thinking: `high`_
 2026-03-11 17:44:19 +01:00
Mathias Fredriksson 752e6ecc16 build: add pre-commit/push hooks mirroring CI checks (#22705) 
This change adds git hooks and Makefile targets that mirror CI required
checks locally, catching issues before they reach CI.

This is for use by AI agents (documented in AGENTS.md).

- **pre-commit** (every commit): gen, fmt, lint, typos, slim binary
  build. Fast checks without Docker or Playwright.
- **pre-push** (before push): full CI suite including site build, tests,
  sqlc-vet, offlinedocs.
  
To use:

```sh
git config core.hooksPath scripts/githooks
```

Works in worktrees (where `.git` is a file). Bypass with `--no-verify`.
 2026-03-06 16:56:11 +02:00
blinkagent[bot]andblink-so[bot] 53ceea918b docs: remove broken image reference in contributing guide (#22013) 
The "Deploy PR manually" image (`deploy-pr-manually.png`) referenced in
the contributing docs has never existed in the repository, resulting in
a broken image on the [docs
site](https://coder.com/docs/about/contributing/CONTRIBUTING#deploying-a-pr).

This PR removes the broken `<Image>` tag and ends the sentence with a
period instead. The `pr-deploy.yaml` workflow link remains intact for
users to navigate to the workflow dispatch page directly.

Created on behalf of @DavidFrawormo

Co-authored-by: blink-so[bot] <211532188+blink-so[bot]@users.noreply.github.com>
 2026-02-09 15:50:47 +00:00
Jake Howell f11a8086b0 fix: migrate all uses of visuallyHidden (#22001) 
Replace all usages of MUI's `visuallyHidden` utility from `@mui/utils`
with Tailwind's `sr-only` class. Both produce identical CSS, so this is
a no-op behaviorally -- just removes another MUI dependency from the
codebase. Also updates the accessibility example in the frontend
contributing docs to match.
 2026-02-09 23:17:03 +11:00
Mathias Fredriksson 61beb7bfa8 docs: rewrite dev containers documentation for GA (#21080) 
docs: rewrite dev containers documentation for GA

Corrects inaccuracies in SSH examples (deprecated `--container` flag),
port forwarding (native sub-agent forwarding is primary), and
prerequisites (dev containers are on by default). Fixes template
descriptions: docker-devcontainer uses native Dev Containers while
AWS/Kubernetes templates use Envbuilder.

Renames admin docs folder from `devcontainers/` to `envbuilder/` to
reflect actual content. Adds customization guide documenting agent
naming, display apps, custom apps, and variable interpolation. Documents
multi-repo workspace support and adds note about Terraform module
limitations with sub-agents. Fixes module registry URLs.

Refs #18907
 2025-12-05 19:42:16 +02:00
Spike Curtis d25ff6c48b docs: add guidelines about PR size (#19700) 
Adds guidelines about PR size to our contributing guide.
 2025-09-08 09:55:48 +04:00
blink-so[bot]andAtif Ali b61a5d7c33 feat: replace the jetbrains-gateway module with the jetbrains toolbox (#19583) 
Co-authored-by: blink-so[bot] <211532188+blink-so[bot]@users.noreply.github.com>
Co-authored-by: Atif Ali <atif@coder.com>
 2025-08-28 20:49:43 +05:00
Steven Masley a19dfa9a0a docs: add generative ai contribution guidelines (#19427) 
Initial language that gives us something to point to if needed.
 2025-08-20 09:13:40 -05:00
Andrew Aquino 72b8ab530e fix(docs): add missing GFM alert directives to blockquotes (#19042) 
I just added support for rendering GFM alerts inside of numbered lists
in coder.com (see https://github.com/coder/coder.com/pull/328), and
noticed that these plain blockquotes should probably be alerts.

This should cover all the missing alerts. I found them by searching for
the regex `^\s*>\s` within docs/**/*.md

Is `[!NOTE]` the correct type for these? Or do we want to use
tip/important/etc?

- @mtojek CONTRIBUTING.md
- @johnstcn support-bundle.md
- @matifali gateway.md
 2025-07-28 15:00:56 -07:00
DevCatsandAtif Ali 6746e16502 docs: add contribution documentation for modules and templates (#18820) 
draft: add contribution docs for modules and templates individually to
be referenced in coder docs manifest.

---------

Co-authored-by: Atif Ali <atif@coder.com>
 2025-07-17 16:23:42 -05:00
ケイラ 52c4b61391 feat: add search to parameter dropdowns (#18729) 2025-07-15 11:23:49 -06:00
Edward AngertandEdwardAngert 040fa30aba docs: update screenshots with new logo (#18830) 
stage 1 of many

- new login screenshot
- remove unused platforms screenshots
- update [screenshots
doc](https://coder.com/docs/@2025-screenshots/about/screenshots)
- update [quickstart
doc](https://coder.com/docs/@2025-screenshots/tutorials/quickstart)

closes #18813 

<details><summary>list of screenshots with old logo or that are
outdated</summary>

|docs/images/|notes?|
|--|--|
|logo-black.png| |
|jupyter-notebook.png| |
|platforms/docker/login.png| |
|platforms/docker/create-workspace.png| |
|platforms/docker/ides.png| |
|platforms/gcp/marketplace.png| |
|platforms/gcp/start.png| |
|platforms/aws/aws-linux.png| |
|platforms/aws/marketplace.png| |
|platforms/kubernetes/template-variables.png| |
|platforms/kubernetes/region-picker.png| |
|platforms/kubernetes/starter-template.png| |
|install/windows-installer.png| |
|install/homebrew.png| |
|screenshots/create-template.png| |
|screenshots/login.png| |
|screenshots/starter_templates.png| |
|screenshots/settings.png| |
|screenshots/audit.png| |
|screenshots/workspace-running-with-topbar.png| |
|screenshots/workspaces_listing.png| |
|screenshots/templates_listing.png| |
|screenshots/welcome-create-admin-user.png| |
|screenshots/workspace_launch.png| |
|screenshots/templates_insights.png| |
|screenshots/healthcheck.png| |
|screenshots/terraform.png| |
|deploy-pr-manually.png| |
|workspace-update.png| |
|custom-app.png| |
|code-server.png| |
|networking/annotatedports.png| |
|networking/portsharingmax.png| |
|networking/portforwarddashboard.png| |
|networking/listeningports.png| |
|agent-metadata.png| |
|jupyter.png| |
|admin/service-banner-maintenance.png| |
|admin/provisioner-tags.png| |
|admin/github-app-register.png| |
|admin/licenses/licenses-screen.png| |
|admin/licenses/licenses-nolicense.png| |
|admin/licenses/add-license-ui.png| |
|admin/service-banner-config.png| |
|admin/group-allowlist.png| |
|admin/networking/workspace-proxies/ws-proxy-picker.png| |
|admin/setup/appearance/application-name-logo-url.png| |
|admin/setup/appearance/announcement_banner_settings.png| |
|admin/setup/appearance/support-links.png| |
|admin/setup/appearance/service-banner-secret.png| |
|admin/quota-buildlog.png| |
|admin/integrations/kube-region-picker.png| |
|admin/integrations/coder-logstream-kube-logs-wrong-image.png| |
|admin/integrations/coder-logstream-kube-logs-pod-crashed.png| |
|admin/integrations/coder-logstream-kube-logs-normal.png| |
|admin/integrations/coder-logstream-kube-logs-quota-exceeded.png| |
|admin/git-auth-template.png| |
|admin/github-app-install.png| |
|admin/users/organizations/role-sync.png| |
|admin/users/organizations/group-sync-empty.png| |
|admin/users/organizations/workspace-list.png| |
|admin/users/organizations/new-organization.png| |
|admin/users/organizations/role-sync-empty.png| |
|admin/users/organizations/template-org-picker.png| |
|admin/users/organizations/organization-members.png| |
|admin/users/organizations/org-dropdown-create.png| |
|admin/users/organizations/default-organization-settings.png| |
|admin/users/organizations/group-sync.png| |
|admin/users/organizations/idp-org-sync.png| |
|admin/users/organizations/admin-settings-orgs.png| |
|admin/users/organizations/custom-roles.png| |
|admin/users/quotas/quota-groups.png| |
|admin/users/create-token.png| |
|admin/users/headless-user.png| |
|admin/provisioners/provisioner-jobs.png| |
|admin/github-app-permissions.png| |
|admin/templates/coder-apps-ui.png| |
|admin/templates/starter-templates.png| |
|admin/templates/create-template.png| |
|admin/templates/schedule/template-schedule-settings.png| |
|admin/templates/schedule/user-quiet-hours.png| |
|admin/templates/coder-metadata-ui.png| |
|admin/templates/duplicate-menu.png| |
|admin/templates/agent-metadata-ui.png| |
|admin/templates/troubleshooting/workspace-build-timings-ui.png| |
|admin/templates/duplicate-page.png| |
|admin/templates/new-duplicate-template.png| |
|admin/templates/import-template.png| |

|admin/templates/extend-templates/prebuilt/replacement-notification.png|
|
|admin/templates/extend-templates/prebuilt/prebuilt-workspaces.png| |

|admin/templates/extend-templates/dyn-params/dynamic-params-compare.png|
|

|admin/templates/extend-templates/dyn-params/enable-dynamic-parameters.png|
|
|admin/templates/extend-templates/template-preset-dropdown.png| |
|admin/monitoring/health-check.png| |
|admin/monitoring/logstream-kube.png| |
|admin/monitoring/notifications/user-notification-preferences.png| |
|admin/monitoring/notifications/notification-admin-prefs.png| |
|admin/workspace-proxy-picker.png| |
|admin/admin-settings-general.png| |
|admin/deployment-id-copy-clipboard.png| |
|icons-gallery.png| |
|start/setup-page.png| |
|start/workspace-schedule-settings.png| |
|start/build-template.png| |
|start/starter-templates.png| |
|start/create-template.png| |
|start/create-workspace.png| |
|start/template-preview.png| |
|start/blank-workspaces.png| |
|start/template-source-code.png| |
|start/first-template.png| |
|start/workspace-ready.png| |
|start/template-edit-source-code.png| |
|start/template-publish.png| |
|start/starter-templates-annotated.png| |
|display-apps.png| |
|workspace-automatic-updates.png| |
|workspaces/autostop.png| |
|workspaces/autostart.png| |
|create-workspace-from-templates-ui.png| |
|ide-row.png| |
|editors.png| |
|delete-template.png| |
|logo-white.png| |
|template-rbac.png| |
|coderapp-port-forward.png| |
|user-guides/terminal-access.png| |
|user-guides/workspace-bulk-actions.png| |
|user-guides/devcontainers/devcontainer-agent-ports.png| |
|user-guides/devcontainers/devcontainer-web-terminal.png| |
|user-guides/create-workspace-ui.png| |
|user-guides/workspace-view-connection-annotated.png| |
|user-guides/remote-desktops/web-rdp-demo.png| |
|user-guides/remote-desktops/amazon-dcv-windows-demo.png| |
|user-guides/desktop/coder-desktop-file-sync-add.png| |
|user-guides/desktop/coder-desktop-session-token.png| |
|user-guides/desktop/coder-desktop-win-pre-sign-in.png| |
|user-guides/desktop/coder-desktop-file-sync-conflicts-mouseover.png| |
|user-guides/desktop/coder-desktop-mac-pre-sign-in.png| |
|user-guides/desktop/coder-desktop-file-sync-watching.png| |
|user-guides/desktop/coder-desktop-win-enable-coder-connect.png| |
|user-guides/desktop/coder-desktop-sign-in.png| |
|user-guides/desktop/coder-desktop-file-sync.png| |
|user-guides/desktop/coder-desktop-file-sync-staging.png| |
|user-guides/desktop/chrome-insecure-origin.png| |
|user-guides/desktop/coder-desktop-workspaces.png| |
|user-guides/jetbrains/toolbox/workspaces.png| |
|user-guides/jetbrains/toolbox/install.png| |
|user-guides/jetbrains/toolbox/login-token.png| |
|user-guides/jetbrains/toolbox/login-url.png| |
|user-guides/schedule-settings-workspace.png| |
|user-guides/dotfiles-module.png| |
|user-guides/workspace-list-ui.png| |
|user-guides/workspace-settings-location.png| |
|template-variables.png| |
|ides/code-web-extensions.png| |
|ides/copilot.png| |
|architecture-multi-region.png| |
|external-apps.png| |
|guides/ai-agents/tasks-ui.png| |
|guides/ai-agents/duplicate.png| |
|guides/ai-agents/landing.png| |
|guides/ai-agents/workspace-page.png| |
|guides/ai-agents/realworld-ui.png| |
|guides/xray-integration/example.png| |
|guides/using-organizations/workspace-list.png| |
|guides/using-organizations/new-organization.png| |
|guides/using-organizations/template-org-picker.png| |
|guides/using-organizations/deployment-organizations.png| |
|guides/using-organizations/organization-members.png| |
|readme-logos.png| |
|metadata-ui.png| |
|secret-metadata-ui.png| |
|projector-intellij.png| |
|schedule.png| |
|ssh-keys.png| |
|template-scheduling.png| |
|templates/general-settings.png| |
|templates/build-template.png| |
|templates/update.png| |
|templates/starter-templates.png| |
|templates/create-template.png| |
|templates/select-template.png| |
|templates/pre-filled-parameters.png| |
|templates/source-code.png| |
|templates/upload-create-your-first-template.png| |
|templates/create-workspace.png| |
|templates/edit-source-code.png| |
|templates/permissions.png| |
|templates/coder-session-token.png| |
|templates/starter-templates-button.png| |
|templates/template-tour.png| |
|templates/edit-files.png| |
|templates/workspace-ready.png| |
|templates/template-menu-settings.png| |
|templates/workspace-apps.png| |
|templates/coder-login-web.png| |
|templates/new-workspace.png| |
|templates/template-variables.png| |
|templates/use-template.png| |
|templates/healthy-workspace-agent.png| |
|templates/update-policies.png| |
|templates/upload-create-template-form.png| |
|templates/develop-in-docker-template.png| |
|templates/publish.png| |
|templates/devcontainers.png| |
|templates/create-template-permissions.png| |
|port-forward-dashboard.png| |
|creating-workspace-ui.png| |
|parameters.png| |
|best-practice/build-timeline.png| |
|file-browser.png| |
|architecture-single-region.png| |
|gateway/plugin-settings-marketplace.png| |
|gateway/plugin-session-token.png| |
|gateway/plugin-connect-to-coder.png| |
|gateway/plugin-select-ide.png| |
|gateway/plugin-ide-list.png| |
|hero-image.png| |

</details>

---------

Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
 2025-07-10 16:01:20 -04:00
Edward AngertandEdwardAngert b882d46d91 docs: fix relative links in about/contributing (#18818) 
hotfix

---------

Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
 2025-07-09 20:04:48 +00:00
Hugo Dutka 3c2f3d640b chore: remove dbmem (#18803) 
Remove the in-memory database. Addresses #15109.
 2025-07-09 09:46:31 +02:00
ケイラ d4208d23aa refactor: show icons for multi-select parameter options (#18594) 2025-06-27 10:54:47 -06:00
Edward AngertandEdwardAngert f1cca03ed3 docs: reorganize the About section (#18236) 
As part of an information architecture overhaul, this PR reorganizes the
About section and adds a Support section (but not content to it yet)

[preview](https://coder.com/docs/@docs-ia-about/about)

this PR is intentionally limited in scope so that we can ship meaningful
changes faster and followup PRs should include:

- [ ] edit + overhaul the About page
- [ ] decide on the `start` directory
- [ ] ~screenshots page updates~ (this should happen July or later)

redirects PR: https://github.com/coder/coder.com/pull/944

---------

Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
 2025-06-12 13:56:45 -04:00
Stephen KirbyandEdwardAngert a3248f9364 chore(docs): move feature stage docs to install directory (#17199) 
I think the feature stages page should be co-located with releases and
not at the entrance of the docs.


[preview](https://coder.com/docs/@move-feature-stages/install/releases/feature-stages)

---------

Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
 2025-04-01 18:44:51 -05:00
Edward AngertandEdwardAngert 4983150ab9 docs: add a table to feature stages doc (#17080) 
adds a table to the feature stages doc to summarize the stages + links
to the heading below for more info


[preview](https://coder.com/docs/@feature-stages-table/about/feature-stages)

---------

Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
 2025-03-24 22:28:02 -04:00
Edward AngertandEdwardAngert b3d675532f docs: copy edit early access section in feature-stages doc (#16730) 
- copy edit EA section with @mattvollmer 's suggestions
- ran the script that updates the list of experiments

---------

Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
 2025-02-27 09:20:03 +05:00
Edward AngertEdwardAngertBen Potter
 		81ef9e9e80 docs: document new feature stages (#16719) 
- [x] translate notes to docs
- [x] move to Home > About > Feature Stages
- [x] decide on bullet point summaries (👍 👎  in comment)

### OOS for this PR

add support page that describes how users can get support. currently,
[this help
article](https://help.coder.com/hc/en-us/articles/25308666965783-Get-Help-with-Coder)
is the only thing that pops up and includes that `Users with valid Coder
licenses can submit tickets` but doesn't show how, nor does it include
the support bundle docs (link or content). it'd be good to have these
things relate to each other

## preview


[preview](https://coder.com/docs/@feature-stages/contributing/feature-stages)

---------

Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
Co-authored-by: Ben Potter <ben@coder.com>
 2025-02-26 15:43:02 -05:00
Muhammad Atif AliEthanEthan DicksonBen PotterStephen KirbyStephen KirbyEdwardAngertEdward Angert
 		419eba5fb6 docs: restructure docs (#14421) 
Closes #13434 
Supersedes #14182

---------

Co-authored-by: Ethan <39577870+ethanndickson@users.noreply.github.com>
Co-authored-by: Ethan Dickson <ethan@coder.com>
Co-authored-by: Ben Potter <ben@coder.com>
Co-authored-by: Stephen Kirby <58410745+stirby@users.noreply.github.com>
Co-authored-by: Stephen Kirby <me@skirby.dev>
Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
Co-authored-by: Edward Angert <EdwardAngert@users.noreply.github.com>
 2024-10-05 10:52:04 -05:00
Ben Potter 808e1c0d89 docs: add screenshots page (#13582) 
* docs: add screenshots page

* fmt
 2024-06-15 15:34:18 -05:00
Eric Paulsen 87a172fb14 docs: add validated architecture (#13561) 
* docs: add validated architecture

* make: fmt

* formatting

* fix 404s

* fix 404s pt 2

* fix 404s pt 3
 2024-06-13 13:00:26 -04:00