Commit Graph
2 Commits
Author SHA1 Message Date
Nick Vigilanteanddefault 1271dcb570 docs: inherit feature states from ancestor routes in the docs sidebar (#31975)
## Summary

A feature `state` in `docs/manifest/` now applies to a route and all its
descendants, so each state is set once on the highest route it applies
to.
`docsmanifestgen check` rejects a route that repeats an ancestor's
state, and the repeated states on `main` are removed.

## State model

- Put a state on the highest route it applies to.
- Add a state to a descendant only when it is new, such as an early
access page inside a Premium section.
- The sidebar shows a pill on the route that sets the state and on
descendants whose state differs.
- Every page shows its full state, own plus inherited, under the title.

## Changes

- `docsmanifestgen check` (`make lint/docs-manifest`) fails when a route
repeats an ancestor's state, following include files and overlays, or
lists a state twice.
  It runs only after the manifest builds cleanly.
  Table-driven tests in `scripts/docsmanifestgen/state_test.go`.
- Keep `state: [premium]` on AI Governance and External provisioners
only.
Remove the 27 states their descendants repeat in
`docs/manifest/ai-governance/**` and
`docs/manifest/install/operate/provisioners.yml`, and regenerate
`docs/manifest.json`.
- Document the model in `contributing/documentation.md` (new "Feature
states" section with a YAML example),
`docs/.style/content-guidelines.md`, and the doc-check skill.

> [!IMPORTANT]
> Inherited pills under the page title and the new sidebar behavior need
the matching docs-engine change
([DOCS-1440](https://linear.app/codercom/issue/DOCS-1440)).
> Merge this after that ships, or child pages show no state pill until
it does.

## Testing

- `go test ./scripts/docsmanifestgen/... ./scripts/docgenenv/...`
- `golangci-lint run ./scripts/docsmanifestgen/...`
- `GOOS=windows` and `GOOS=darwin` `go vet ./scripts/docsmanifestgen/`
- `make lint/docs-manifest`, `make lint/markdown`, `make
lint/docs-redirects`
- `make gen/docs-manifest` leaves the tree clean.

<details>
<summary>Decision log: rebase onto main after #31645</summary>

- #31645 (merged 2026-11-04) moved AI Governance to a top-level section
with Agent Firewall and AI Gateway nested under it, and added the
`ai-coder/...` redirects.
That covered this PR's move commits, link and URL updates, and
redirects, which caused the conflicts.
- The branch was rebuilt on `main`: the two move commits were dropped,
and the four state-tooling and guidance commits were cherry-picked.
The manifest cleanup was redone as a new commit against `main`'s layout,
using the new lint's output as the list of repeated states.
- Agent Relay is now top-level with `state: [premium, beta]` and no
child states, so it needs no change.
- Conflicts in `content-guidelines.md` and the doc-check skill were
resolved to keep `main`'s newer text (Vale word-choice updates and
relative redirect syntax) and apply only the feature-states lines.
- The pre-rebase head was `a797f59737`.

</details>

> Generated by Coder Agents on behalf of @nickvigilante.


Supersedes #31481, reopened under a human author for attribution.

---------

Co-authored-by: default <default@example.com>
2026-11-12 13:19:38 -05:00
Nick Vigilante 3d30e201b5 docs: move contributor guides out of the published docs into the repo (#29751)
## Merge order

Merge first; then republish the docs; then coder/coder.com#1100 (the
redirects).

## Summary

The nine pages under `docs/about/contributing/` are for people working
in this repository, not for Coder users or administrators, so they leave
the published documentation.
The repository becomes their canonical home.
Until now the root `CONTRIBUTING.md` and `CODE_OF_CONDUCT.md` were
two-line stubs that only linked to the docs site, so contributors on
GitHub were bounced out to read them.

A companion PR in `coder/coder.com` adds redirects from every retired
`/docs/about/contributing/*` URL to the new GitHub location.
It must merge only after this PR has merged and the docs have
republished.

## Changes

| Old path | New path |
| -- | -- |
| `docs/about/contributing/CONTRIBUTING.md` | `CONTRIBUTING.md`
(replaces the stub) |
| `docs/about/contributing/CODE_OF_CONDUCT.md` | `CODE_OF_CONDUCT.md`
(replaces the stub) |
| `docs/about/contributing/SECURITY.md` | deleted; the root
`SECURITY.md` already holds the policy |
| `docs/about/contributing/AI_CONTRIBUTING.md` |
`contributing/AI_CONTRIBUTING.md` |
| `docs/about/contributing/backend.md` | `contributing/backend.md` |
| `docs/about/contributing/frontend.md` | `contributing/frontend.md` |
| `docs/about/contributing/modules.md` | `contributing/modules.md` |
| `docs/about/contributing/templates.md` | `contributing/templates.md` |
| `docs/about/contributing/documentation.md` |
`contributing/documentation.md` (see note below) |

For every moved file: the docs front matter is stripped and its `title`
becomes the H1, relative links are rewritten for the new depth
(`../../../foo` becomes `./foo` at the root and `../foo` under
`contributing/`; the two links into `docs/admin/` become
`../docs/admin/...`), and the docs-only `<div class="tabs">` wrapper in
`CONTRIBUTING.md` is removed.
`CONTRIBUTING.md` gains a short intro that links the code of conduct,
the security policy and the area guides, since GitHub only auto-surfaces
the root files.

`docs/manifest.json` loses the About → Contributing group and
`docs/images/icons/contributing.svg`, which only that group used.

Inbound references updated:

- `README.md`: contribution guide link now points at `CONTRIBUTING.md`
on GitHub.
- `docs/tutorials/example-guide.md` and
`docs/install/releases/feature-stages.md`: link to
`contributing/documentation.md` on GitHub, since a docs page cannot link
to a repo-only file.
- `docs/.style/style-guide/README.md`: the "Relationship to" section
names the new location.
- `scripts/docshtmlcheck/main.go`: both the package comment and the
user-facing error string name `contributing/documentation.md`.
- `scripts/docshtmlcheck/README.md`: relative link to the new location.
- `coderd/database/migrations/migrate_test.go`: `t.Log` link now points
at `contributing/backend.md#database-fixtures-for-testing-migrations`.
- `.github/pull_request_template.md`: AI contribution guidelines link.
- `.github/workflows/contrib.yaml`: commit-message guidelines link in
the PR title check.
- `.github/workflows/test-docs-preview-mapper.sh`: the mapper test case
that used `docs/about/contributing/CONTRIBUTING.md` now uses
`docs/admin/security/audit-logs.md`.
-
`.claude/docs/{ARCHITECTURE,PR_STYLE_GUIDE,WORKFLOWS,DOCS_STYLE_GUIDE}.md`:
links to `CONTRIBUTING.md`.

`git grep about/contributing` is empty after this change.
`CODEOWNERS` had no entry for the old paths.

Note on `documentation.md`: it is docs-authoring guidance and is parked
in `contributing/` for now.
Folding it into `docs/.style/` is tracked separately and is deliberately
not attempted here.

## Testing

- `go run ./scripts/docshtmlcheck` over `docs/`, and again over
`contributing/`, `CONTRIBUTING.md` and `CODE_OF_CONDUCT.md`: clean.
- `go vet ./scripts/docshtmlcheck/...` and `go test
./scripts/docshtmlcheck/...`: 47 tests pass.
- `go vet ./coderd/database/migrations/...`: clean. `go test` for that
package fails to link on this machine (`tailscale.com/tstime/mono:
invalid reference to runtime.nanotime1`) identically on unmodified
`main`, so it is a local toolchain issue and not exercised here; the
change is a string in a `t.Log`.
- `pnpm check-docs` (markdownlint-cli2 and markdown-table-formatter over
`docs/`, `.claude/docs/`, root `*.md`): 495 files, 0 errors. The same
two tools over `contributing/*.md`: 0 errors.
- Every relative link in the eight moved files resolves to an existing
path (scripted check).
- `bash .github/workflows/test-docs-preview-mapper.sh`: the changed
`assert_maps_to` case passes; the six `resolve_ref`/`pages_for_image`
failures it reports are identical on unmodified `main` on macOS.

Linear: [DOCS-975](https://linear.app/codercom/issue/DOCS-975)

---

🤖 Built with AI assistance.
2026-09-24 19:42:18 +00:00