docs: document the checks that gate a pull request - #2382
Open
Suneha Bose (bosesuneha) wants to merge 10 commits into
Open
docs: document the checks that gate a pull request#2382Suneha Bose (bosesuneha) wants to merge 10 commits into
Suneha Bose (bosesuneha) wants to merge 10 commits into
Conversation
Suneha Bose (bosesuneha)
force-pushed
the
docs/contributor-guide
branch
from
August 12, 2026 02:07
c3020e7 to
8115db1
Compare
…ate copies
The published Development section rendered as a bare heading because
SUMMARY.md linked to ./development.md, which did not exist. mdBook's
create-missing default silently generated an empty stub instead of failing,
so this went unnoticed. Add the page and set create-missing = false.
Three pages under docs/ were stale forks of their docs/book/src/
counterparts, and docs/README.md linked only to the forks:
docs/webview-development.md missing the Custom UI Elements section
docs/package-scripts.md missing the Local VSIX Sharing section
docs/maintenance/README.md last updated 2021; missing the pinned
third-party versions section entirely
Delete them and rewrite docs/README.md as an index into book/.
The release skill instructed maintainers to mirror releasing.md into
docs/maintenance/README.md, which is why that fork stayed alive; update it
to name book/src/ as the single source of truth.
Also fixed:
- ../package.json and ../webview-ui/ links resolved outside the book
- dev-webview / build-webview are not real npm scripts (dev:webview,
build:webview)
- webpack-ui typo for webview-ui
- SUMMARY.md nav labels disagreed with the pages' own titles
- bin/ ignored; make -C docs/book build writes mdBook binaries to the repo
root because the Makefile uses $(PWD) rather than $(CURDIR)
Adds reference/ pages generated from package.json by scripts/generate-docs-reference.js, carrying a DO NOT EDIT header: commands with their menu placement, settings, and pinned versions. SUMMARY.md listed show-properties-azureportal-start-stop.md four times and inspektor-gadget.md twice, so three sidebar entries led to a page that did not match the label clicked. Collapsed to one entry each; no URLs change. features.md was a stale 2.1.0 release spotlight that linked to 2 of its 25 feature pages. Rewritten as an index. This orphans 5 classic-menu screenshots, removed in a later PR.
aks.simplifiedMenuStructure has defaulted to true since Azure#2168, grouping cluster commands under Develop & Deploy, Troubleshoot & Diagnose, and Manage Cluster. The guides still described the classic flat menu, so readers were told to look for items that are now one level down. Paths come from the generated menu reference, not from reading the UI, and are written as "Right-click your AKS cluster > Submenu > Command" so docs-check can validate them. Guides describe the default menu; the classic layout is covered once, in simplified-menu-structure.md. Also corrected: - aks-compare-cluster is on the subscription node, not the cluster node - "Managed Cluster Operations" is the classic label; the default is "Manage Cluster" - the KAITO submenu is "Deploy a LLM with KAITO", not "an LLM" - container-assist pointed at AKS: Run Container Assist (Preview), which has no menu contribution; replaced with the three real commands - inspektor-gadget claimed the command had moved to the main context menu, which described the classic layout and was backwards - "Abort Last Operation" is a webview action in ClusterPropertiesPanel.ts, not a command, so it is no longer listed as a menu operation - simplified-menu-structure.md advised keeping the default false while stating above that it was true merge-save-kubeconfig.md is left alone: those commands belong to ms-kubernetes-tools.vscode-kubernetes-tools.
Mechanical. Only the number of leading '#' changes; heading text is untouched, so every anchor still resolves. 17 pages had a broken hierarchy: 12 jumped from '#' straight to '###', and 5 had no top-level heading at all. Each file's levels were remapped to a contiguous sequence starting at 1, and where that left more than one h1 the later ones were demoted so each page has a single title. Sidebar labels come from SUMMARY.md so navigation was unaffected, but skipped levels are a problem for screen readers.
Two commands set both `category: "AKS"` and an `AKS: ` prefix in their
title, so VS Code rendered them as "AKS: AKS: Launch Kickstart Agent"
and "AKS: AKS: Configure Kickstart Cluster" in the Command Palette.
VS Code composes the palette entry as `category: title`, so the prefix
belongs in exactly one of the two. Dropped it from the titles.
No localized `package.nls.*.json` files exist and `l10n/bundle.l10n.json`
does not carry these strings, so no translations are affected. The
rendered palette text is unchanged from what the docs already describe.
`generate-docs-reference.js` already reports this class of problem
("title repeats its category"); that finding is now clear. Regenerated
`reference/commands.md` in the same commit so the generated output
cannot disagree with `package.json`.
Removed `create-gh-workflow.md`. It described the retired
`actions/starter-workflows` templates, while the live command
(`aks.draftWorkflow`) scaffolds via Draft and is documented in
`draft-integration.md`.
`README.md` re-listed all 25 feature pages by hand, a third copy after
SUMMARY.md and features.md. It had drifted: four entries pointed at the
same page under different labels, and the Container Assist sub-pages and
Copilot plugin page were missing. Replaced with pointers to the Features
index and the generated Reference.
Rebased onto main, which renamed aks.draftArgoCDDeployment to "AKS: Create Argo CD Application" in Azure#2353. Regenerated so the committed reference matches package.json; otherwise docs:reference:check would fail once Azure#2371 lands.
Each change was verified against package.json, src/, or resources/. merge-save-kubeconfig Merge into Kubeconfig and Save Kubeconfig are not this extension's commands. Neither appears in contributes.commands; both come from ms-kubernetes-tools.vscode-kubernetes-tools, which is an extensionDependency. Page now says so. draft-integration Claimed Draft Dockerfile and Draft Deployment are available from the Command Palette. Both are registered in src/extension.ts:147-148 but have no contributes.commands entry, so they are unreachable. Rewritten around the commands that do exist, including aksDraftValidate, which was undocumented, and the pinned Draft version v0.17.14, which was never stated. container-assist-github-workflow All five GitHub Action versions were stale: checkout v4 -> v7.0.0, azure/login v2 -> v3.0.0, use-kubelogin v1 -> v1.3, aks-set-context v4 -> v5.0.0, k8s-deploy v5 -> v6.0.0. Removed the "Annotate namespace" step. No template contains it, and workflowTemplate.test.ts:223 asserts it is absent. container-assist-integration Removed the namespace annotations section for the same reason. container-assist-azure-resources "9 role assignments" summed two mutually exclusive paths. The maximum is 5: one in stage 1, four in stage 2, where the user-namespace and managed-namespace paths cannot both apply. aks-diagnostics Detector list did not match the menu: "Known Issues, Availability and Performance" is "Cluster and Control Plane Availability and Performance", "Network and Connectivity issues" is "Network Connectivity Issues", and Storage was missing. run-kubectl-command, k8s-api-health-points Command labels did not match kubectl.ts: "API Resources" is "Get API Resources", "Get Node" is "Get Nodes", and the health checks are "Healthz Check", "Livez Check", "Readyz Check". Get All Events was missing from the health list. Both pages now show the kubectl command each one runs. argocd-gitops-integration Apply runs with --validate=false, which was omitted. The Copilot integration is an Azure AI Agent plugin (argoCDDeploymentPlugin), not a chat skill. telemetery.md and README.md telemetry.enableTelemetry was deprecated in VS Code 1.61; the setting is telemetry.telemetryLevel set to off.
Deletes 23 images, 100 down to 77, and 12M down to 9.6M. 14 were referenced by no page at all. Five of those were orphaned by the features.md rewrite, the other nine were already dead. 9 were still referenced but showed the classic cluster menu. The extension switched to the grouped menu by default in Azure#2168 (2026-05-30) and every one of these was last touched before that, the newest in 2025-07-28. They told readers to look for menu items that are no longer there. The text breadcrumbs added earlier in this series replace them, and unlike screenshots those are checked by docs:check. Screenshots of webview and result panels are kept. They show output that text cannot convey, which is the test worth applying: never screenshot a menu path, screenshot a result.
Release notes stopped at 2.1.0 while the extension shipped 2.4.0, so the three releases that brought Argo CD on by default, the Kickstart agent and the Container Assist changes had no reader-facing notes. Added whats-new-2.4.0.md covering 2.2.0 through 2.4.0 and removed the 2.1.0 file, per the release-pr skill convention of keeping only the current release. Written around what a reader can now do rather than which settings changed, and the DevHub removal is left out: that code was orphaned with no command entry, so no reader can have been using it. Telemetry is a privacy page and had three accuracy problems: - Webview panels emit an event per message (BasePanel.ts:162-164), which was not disclosed at all. - clusterCreationSuccess was listed under the Copilot handlers, but CreateClusterPanel.ts:300 selects the plain `command` event for the normal Create Cluster flow. - README.md and telemetery.md disclosed different data. Rewritten so the disclosure is in terms a reader can check, rather than internal event shapes and type names, with "what we do not collect" spelled out as concrete categories and the opt-out ahead of the legal links. README.md now agrees with it. Wording elsewhere described the extension from the perspective of the people building it: - "Feature flag" sections gave instructions for enabling settings that are already on by default. Reframed around turning the feature off, which is the decision a reader actually faces. - The menu page documented the default layout as opt-in and referred to "the new menu", a comparison a new reader cannot make. - "the SDK", "the scaffolder" and "Webview" replaced with what those are from the outside. - Container Assist was titled "Alpha Preview" while SUMMARY, the feature index and the command titles all say "Preview". - Three images shared the alt text "Cloud explorer extension menu". book.toml declares the mdbook-toc preprocessor but no page used the marker, so the build depended on that binary for nothing. Added <!-- toc --> to the two pages long enough to need one.
CONTRIBUTING.md was CLA and code-of-conduct boilerplate only. It did not mention how to build, how to run tests, or any of the checks that will actually fail a PR: prettier-format (Prettier Check), lint:all (the lint step in Build), the 1200-line PR Size Checker, or the husky pre-commit hook installed by the prepare script. It was also byte-identical to docs/book/src/contributing.md. Expanded the root file, which GitHub surfaces in the PR and issue UI, and reduced the book copy to the CLA, the code of conduct and links to the development pages, so the two are no longer duplicates that can drift apart. The development page had several inaccuracies: - CI builds on Node 22 and nothing in the repo said so. There is no engines.node and no .nvmrc, so nothing enforces it locally either. - install:all passes --legacy-peer-deps; a bare npm install fails on peer resolution, which is not obvious from the failure. - 9 of the 17 npm scripts were undocumented, including both CI gates. - webpack was described as packaging the extension. It does not; package does. The VSIX sharing section also told contributors to run `vsce package` rather than `npm run package`. - test-compile also copies the deploy template next to the compiled output, which matters if you compile by hand.
Suneha Bose (bosesuneha)
force-pushed
the
docs/contributor-guide
branch
from
August 12, 2026 02:25
8115db1 to
87eeff4
Compare
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 join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Stacked on #2373. Review the last commit only; the rest belongs to the PRs below it.
Split out of #2373, which is otherwise user-facing documentation. This targets contributors.
CONTRIBUTING.md
It was CLA and code-of-conduct boilerplate only — no build steps, no test steps, and no mention of the checks that actually fail a PR:
format-check.ymlnpm run prettier-formatbuild.ymllint stepnpm run lint:allrestrict-pr-size.ymlprepareIt was also byte-identical to
docs/book/src/contributing.md. Expanded the root file, which GitHub surfaces natively in the PR and issue UI, and reduced the book copy to CLA, code of conduct and links — so they are no longer duplicates waiting to drift.Development page
build.yml:48,1es-pipeline.yml:12-14). Noengines.node, no.nvmrc, so nothing enforces it locallyinstall:allrequirement undocumented--legacy-peer-deps; a barenpm installfails on peer resolutionprettier-formatandlint:all, the two CI gateswebpackdescribed as packaging the extensionpackagedoesvsce packagenpm run package(vsce package --no-dependencies), which is what CI usestest-compiledescription incompleteaks-deploy.template.yamlnext to the compiled outputAlso replaced the first-person
watch: "not currently used as part of any workflow I'm aware of".Verification
Prettier clean. No links or generated content affected.