Commit b23d73d
authored
docs: retire the generated feature stage lists (#29113)
## Problem
`docs/install/releases/feature-stages.md` advertised two generated
lists, and neither one earned its place:
- **Available early access features** rendered "Currently no
experimental features are available." The generator read
`ExperimentsSafe`, which is empty, while `ExperimentsKnown` in
`codersdk/deployment.go` defines fourteen experiments. The page told
readers no experimental features existed, which is false.
- **Available beta features** rendered a table built from `state: beta`
nodes in `docs/manifest.json`. It is only as accurate as those flags,
which are easy to forget when a feature graduates.
Both are drift surfaces that promise a completeness the docs cannot
maintain.
## Change
Retire the indexes rather than repair them:
- Delete `scripts/release/docs_update_feature_stages.sh`.
- Remove both generated sections from `feature-stages.md`, along with
their `BEGIN`/`END` markers and `DO NOT EDIT` banners.
- Drop the `docs/install/releases/feature-stages.md` Makefile target and
its two generated-files-list entries, so the page is no longer treated
as generated.
The page keeps everything that describes the stages themselves: the
stage comparison table, the early access / beta / GA guidance, and the
`--experiments` enabling instructions. Nothing else links to the removed
anchors.
## Verification
- `make gen` leaves no unstaged changes beyond the three intended edits.
- `pnpm run lint-docs` passes with 0 errors; `markdown-table-formatter`
reports no formatting to apply.
- `grep` confirms no remaining references to the deleted script, and no
inbound links to `#available-beta-features` or
`#available-early-access-features`.
## Context
Supersedes #28949, which took the opposite approach and generated the
experiments list from `ExperimentsKnown`. Following discussion with
David, the decision is not to advertise either list.
<details>
<summary>Decision log</summary>
**Why not fix the experiments list instead?** That was #28949: a new
`scripts/experimentsdocgen` generator plus a committed
`docs/experiments.json`, generating the table from `ExperimentsKnown`
with descriptions parsed out of the constants' comments. It worked, but
it made the docs responsible for tracking an internal, unstable surface.
Experiments are by definition subject to removal or rename without
notice, and several of the constant comments are developer notes rather
than user-facing prose.
**Why remove the beta table too?** The original ask covered the
experiments list. The beta table shares the same failure mode: it is a
completeness claim maintained by proxy, through `state` flags in
`docs/manifest.json`, with nothing that fails when a feature ships to GA
and the flag is not updated. Deleting the script removes both, and David
confirmed retiring both lists.
**Why remove the Makefile target rather than leave a no-op?** With no
generated regions left in the file, keeping the target would mean the
`make -B gen` unstaged-files check still guards a page nothing
generates. Removing it lets the page be edited as ordinary prose.
**What was deliberately left alone.** The `state: beta` flags in
`docs/manifest.json` stay: they drive badges elsewhere in the docs and
are not part of this change. `ExperimentsSafe` and `ExperimentsKnown` in
`codersdk` are untouched. The feature-stage definitions and the
`--experiments` instructions stay, since readers still need to know what
the stages mean and how to opt in, and that content does not go stale as
features move between stages.
</details>
I have read the AI Contribution guidelines.
---
Linear:
[DOCS-878](https://linear.app/codercom/issue/DOCS-878/remove-the-feature-stages-generator-script-and-retire-the-generated)
🤖 Generated with Coder Agents on behalf of @nickvigilante.
<details>
<summary>CI note: unrelated flakes on the first run</summary>
The initial run of `test-go-pg-17` failed in `cli` and `coderd`:
-
`TestSSH_OneShotCommandMode/{ClosesStdinOnEOF,DoesNotRequestPTY,PropagatesExitCode,RequestsPTYWithFlag}`
-
`TestWorkspaceUpdateAutostart/{DST_start,friday_to_monday,monday_to_tuesday}`
- `TestWorkspaceFilterManual/FilterQueryHasAgentTimeout`
- The `cli` package then hit `panic: test timed out after 25m0s`.
This PR changes no Go code and no CI configuration; the diff is one
deleted shell script, one Markdown page, and the Makefile wiring between
them. Re-running the failed jobs turned everything green with no code
changes.
</details>1 parent 65d01ef commit b23d73d
3 files changed
Lines changed: 0 additions & 216 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1015 | 1015 | | |
1016 | 1016 | | |
1017 | 1017 | | |
1018 | | - | |
1019 | 1018 | | |
1020 | 1019 | | |
1021 | 1020 | | |
| |||
1114 | 1113 | | |
1115 | 1114 | | |
1116 | 1115 | | |
1117 | | - | |
1118 | 1116 | | |
1119 | 1117 | | |
1120 | 1118 | | |
| |||
1351 | 1349 | | |
1352 | 1350 | | |
1353 | 1351 | | |
1354 | | - | |
1355 | | - | |
1356 | | - | |
1357 | | - | |
1358 | | - | |
1359 | | - | |
1360 | | - | |
1361 | | - | |
1362 | | - | |
1363 | | - | |
1364 | | - | |
1365 | 1352 | | |
1366 | 1353 | | |
1367 | 1354 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
60 | 60 | | |
61 | 61 | | |
62 | 62 | | |
63 | | - | |
64 | | - | |
65 | | - | |
66 | | - | |
67 | | - | |
68 | | - | |
69 | | - | |
70 | 63 | | |
71 | 64 | | |
72 | 65 | | |
| |||
98 | 91 | | |
99 | 92 | | |
100 | 93 | | |
101 | | - | |
102 | | - | |
103 | | - | |
104 | | - | |
105 | | - | |
106 | | - | |
107 | | - | |
108 | | - | |
109 | | - | |
110 | | - | |
111 | 94 | | |
112 | 95 | | |
113 | 96 | | |
| |||
This file was deleted.
0 commit comments