docs: retire the generated feature stage lists - #29113
Conversation
The early access section rendered "Currently no experimental features are available" because the generator read ExperimentsSafe, which is empty, while ExperimentsKnown defines fourteen experiments. The beta table depended on manifest state flags staying current. Both lists drift silently, so remove them along with the script and Makefile target that produced them. The stage definitions, the stage-specific guidance, and the --experiments enabling instructions are unchanged. Closes DOCS-878. Supersedes #28949.
Docs previewCheck off each page once it's been reviewed. If a page changes in a later push, its checkbox clears automatically so it gets a fresh look. Pages not yet wired into the docs navigation aren't listed here. |
|
/coder-agents-review |
|
Chat: Review in progress (11/11 reviewers complete) | View chat deep-review v0.9.0 | Round 1 | Last posted: Round 1, 1 findings (1 Note), COMMENT. Review Finding inventoryFinding inventory - PR #29113Findings
Round logRound 1Panel (Netero + Bisky, Hisoka, Mafu-san, Mafuuu, Pariston, Leorio, Gon, Pen Botter, Razor, Meruem). Netero: no findings. Panel: no defects. Pure deletion, +0/-216. One convergent Note (CRF-1) on discoverability tradeoff, intended and approved. About deep-reviewCRF = Coder Review Finding (P0-P4, Nit, Note)
|
There was a problem hiding this comment.
Clean deletion. This retires two generated feature-stage lists, their generator script (scripts/release/docs_update_feature_stages.sh), and the Makefile target, at +0/-216. Severity count: 0 blocking, 1 Note.
The panel (Netero plus ten reviewers) found no defects. The removal is symmetric and complete, and every reviewer independently confirmed the mechanical claims rather than trusting the PR body:
- No surviving reference to
docs_update_feature_stagesanywhere in the tree, including.github/andscripts/. - The removed anchors
#available-early-access-featuresand#available-beta-featureshave zero inbound links; the ten live inbound links point at#early-access-features, which still resolves to the retained## Early access featuresheading. feature-stages.mdis gone fromGEN_FILES, fromgen/mark-fresh, and its target rule is deleted, so the page is no longer guarded by themake -B genunstaged-files check. No orphanedBEGIN/END/DO NOT EDITmarkers remain, and the prose flows cleanly across both excised sections.
The scope expansion (removing the beta table on top of the experiments list) is disclosed and approved, not smuggled: the decision log names the shared failure mode and cites David's confirmation, superseding #28949. As Hisoka put it: "I went looking for a thread to pull. There isn't one."
One process note: the "make gen leaves no unstaged changes" claim was not independently reproduced here (docs generation needs network-fetched deps). It is structurally consistent with the reference removal, but unverified in this review.
docs/install/releases/feature-stages.md:39-61
Note [CRF-1] Retiring the beta table removes the only in-docs enumeration of which features are currently in beta or early access. (Pariston, Pen Botter, Mafuuu)
The retained --experiments enabling instructions in this <details> block tell readers to run coder server --experiments=feature1,feature2, but after this change nothing in the docs lists real experiment names, and the two beta rows that vanished (MCP Server, JetBrains Toolbox) are no longer enumerated on a single page. This is the intended consequence of the decision, not a regression: the early-access list was already empty (ExperimentsSafe is empty), and the beta rows keep their state: beta badges in docs/manifest.json. Discoverability now flows through per-feature badges and the changelog rather than this page. Worth stating plainly so the tradeoff is a conscious one; not worth blocking.
🤖
🤖 This review was automatically generated with Coder Agents.
Problem
docs/install/releases/feature-stages.mdadvertised two generated lists, and neither one earned its place:ExperimentsSafe, which is empty, whileExperimentsKnownincodersdk/deployment.godefines fourteen experiments. The page told readers no experimental features existed, which is false.state: betanodes indocs/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:
scripts/release/docs_update_feature_stages.sh.feature-stages.md, along with theirBEGIN/ENDmarkers andDO NOT EDITbanners.docs/install/releases/feature-stages.mdMakefile 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
--experimentsenabling instructions. Nothing else links to the removed anchors.Verification
make genleaves no unstaged changes beyond the three intended edits.pnpm run lint-docspasses with 0 errors;markdown-table-formatterreports no formatting to apply.grepconfirms no remaining references to the deleted script, and no inbound links to#available-beta-featuresor#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.Decision log
Why not fix the experiments list instead? That was #28949: a new
scripts/experimentsdocgengenerator plus a committeddocs/experiments.json, generating the table fromExperimentsKnownwith 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
stateflags indocs/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 genunstaged-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: betaflags indocs/manifest.jsonstay: they drive badges elsewhere in the docs and are not part of this change.ExperimentsSafeandExperimentsKnownincodersdkare untouched. The feature-stage definitions and the--experimentsinstructions 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.I have read the AI Contribution guidelines.
Linear: DOCS-878
🤖 Generated with Coder Agents on behalf of @nickvigilante.
CI note: unrelated flakes on the first run
The initial run of
test-go-pg-17failed incliandcoderd:TestSSH_OneShotCommandMode/{ClosesStdinOnEOF,DoesNotRequestPTY,PropagatesExitCode,RequestsPTYWithFlag}TestWorkspaceUpdateAutostart/{DST_start,friday_to_monday,monday_to_tuesday}TestWorkspaceFilterManual/FilterQueryHasAgentTimeoutclipackage then hitpanic: 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.