mirror of
https://github.com/coder/coder.git
synced 2026-11-23 04:09:07 +08:00
main
2
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
|
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> |
||
|
|
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. |