mirror of
https://github.com/coder/coder.git
synced 2026-10-16 14:48:56 +08:00
Nick Vigilante
b23d73d501
## 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>