docs: generate the experiments list and document how to enable experiments - #28949
Closed
nickvigilante wants to merge 6 commits into
Closed
docs: generate the experiments list and document how to enable experiments#28949nickvigilante wants to merge 6 commits into
nickvigilante wants to merge 6 commits into
Conversation
…ments The feature-stages page said no experimental features exist because its generator read ExperimentsSafe, which is empty, while ExperimentsKnown defines fourteen. Add scripts/experimentsdocgen, which writes docs/experiments.json from ExperimentsKnown (id, display name, the constant's comment as description, and whether --experiments=* enables it), and have the release script render the feature-stages table from that file so the two cannot disagree. Both are make gen targets, so CI's unstaged-files check fails a PR that changes experiments without regenerating. The enabling instructions now distinguish the opt-in set from flags that must be named. Assisted-by: AI
Contributor
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. |
Contributor
Documentation CheckThis PR is itself a documentation change: it updates Updates Needed
No further documentation changes needed. Automated review via Coder Agents |
…ple experiment The generated experiments table published two constant comments that read as developer notes. Reword the auto-fill-parameters comment (mirrored into the generated apidoc files, which embed enum comments) and have the generator skip ExperimentExample, a placeholder kept for tests. Assisted-by: AI
Contributor
Author
|
Addressed the Documentation Check feedback:
|
…ch display name Assisted-by: AI
…dcard column Assisted-by: AI
…-row column Assisted-by: AI
…s named flags Assisted-by: AI
Contributor
Author
|
Closing this per discussion with @david-fraley. We're just going to remove the generator altogether. |
Contributor
Author
|
Superseded by #29113, which removes the generator and both generated lists instead of fixing the experiments table. Tracked in DOCS-878. 🤖 Generated with Coder Agents on behalf of @nickvigilante. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
docs/install/releases/feature-stages.mdsays "Currently no experimental features are available." Its generator readsExperimentsSafe, which is empty, whileExperimentsKnownincodersdk/deployment.godefines fourteen experiments. Readers cannot learn which experiments exist for the version they run or how to enable one, and the docs site has no machine-readable list to validate experimental-content markers against.Change
scripts/experimentsdocgen(new): writesdocs/experiments.jsonfromExperimentsKnown:id,displayName(Experiment.DisplayName()),description(the constant's comment, parsed fromcodersdk/deployment.gowithgo/ast), andsafe(membership inExperimentsSafe, i.e. whether--experiments=*enables it). Sorted by id, atomic write,--dry-run.docs/experiments.json(new, generated,linguist-generated): 14 entries today.scripts/release/docs_update_feature_stages.sh: the experiments table is now rendered from that JSON withjq(columns: Feature, Flag, Description, Enabled by--experiments=*), replacing thego docscraping ofExperimentsSafe. The beta table is unchanged._gen/bin/experimentsdocgenbuild rule;docs/experiments.jsontarget; the feature-stages target depends on it; both added to the generated-files lists somake -B genplus the unstaged-files check fails a PR that changes experiments without regenerating.--experiments=*, the rows marked Yes) from experiments that must be named explicitly, and note the table is generated from the code.Verification
go test ./scripts/experimentsdocgen: description parsing (trailing and doc comments, non-Experiment constants ignored), document assembly (sort, safe flags), and a test against the realdeployment.goasserting every known experiment has a display name and a declaring constant.make docs/experiments.jsonbuilds and writes the file; running the generator and the release script a second time produces no further diff (idempotent, so the CI gen check is stable).markdownlint-cli2 --fixandmarkdown-table-formatterapplied to the page as the make target does. (Locallymake docs/install/releases/feature-stages.mdstopped atsite/node_modulesbecause of a Node engine mismatch on this machine, so the script and formatters were run directly with the same inputs.)For reviewers
auto-fill-parameters: "This should not be taken out of experiments until…";example: "This isn't used for anything."). Fixing those is a comment edit incodersdk/deployment.go, and whetherExperimentExampleshould stay inExperimentsKnownat all is a codersdk question; this PR does not change either.docs/experiments.jsonper version to validatedata-featuremarkers and to label experimental content; design in that repository'sdocs/superpowers/specs/2026-09-03-conditional-content-annotations-design.md.I have read the AI Contribution guidelines.
🤖 Built with AI assistance.