Skip to content

feat(home): offer VS Code alongside Docker in the quick start - #150

Draft
guanzhousongmicrosoft wants to merge 1 commit into
mainfrom
dev/guanzhousong/hero-quickstart-vscode
Draft

feat(home): offer VS Code alongside Docker in the quick start#150
guanzhousongmicrosoft wants to merge 1 commit into
mainfrom
dev/guanzhousong/hero-quickstart-vscode

Conversation

@guanzhousongmicrosoft

Copy link
Copy Markdown
Contributor

What changed

The home page quick start now offers two ways to get DocumentDB running locally, as a toggle: Docker (unchanged, still the default) and VS Code.

The VS Code tab links to the extension on the marketplace and to vscode://ms-azuretools.vscode-documentdb/local, which opens the DocumentDB Local setup wizard directly.

Why

DocumentDB Local shipped in the VS Code extension's 0.10.0 release. The extension now creates and starts the container itself — someone already working in VS Code no longer runs Docker by hand and then types a port, username, password and TLS choice back into a connection wizard.

The home page only offered the Docker command, so that path was invisible to exactly the people it was built for: the ones who arrive here without the extension and leave with a terminal command.

Design notes

  • Docker stays selected by default. It works everywhere and needs nothing beyond Docker itself. The VS Code path is shorter but only pays off for people already in that editor, so it is offered rather than assumed.
  • The install link comes first, and neither link appears alone. A vscode:// URL for an extension that is not installed does nothing visible at all — no error, no navigation. Presenting it on its own would leave a first-time visitor clicking a button that silently does nothing.
  • The heading becomes "Run DocumentDB locally" since it now covers both paths.
  • The run-with-docker anchor is kept. Nothing in this repository links to it, but it is a public URL and it still lands on the right card.
  • Keyboard and screen readers: proper tablist / tab / tabpanel roles, arrow-key navigation between tabs, and roving tabindex so only the selected tab is in the tab order.

Dependency

The deep link needs the action switch added in microsoft/vscode-documentdb#898, which is currently a draft. Before that lands, vscode://ms-azuretools.vscode-documentdb/local reaches the extension but is rejected — the handler only understood connection-string links.

This should not merge before #898 ships in a released version of the extension. Happy to hold it, or to gate the VS Code tab behind a flag if you would rather land the layout first.

Validation

  • npm run lint, npm test (129 tests) and npm run build:next all clean.
  • Verified against the generated static HTML: both panels render, Docker is selected by default (aria-selected="true"), the VS Code tab is aria-selected="false" with tabindex="-1", and both the deep link and the marketplace link are present.
  • Not yet clicked end to end — that needs a build of the extension carrying #898.

Related, not fixed here

/docs/getting-started/vscode-quickstart still describes the pre-0.10.0 flow: run Docker first, then add a local connection by hand with port, username, password and a TLS prompt. That is the workflow DocumentDB Local replaced. Worth a follow-up; I left it alone to keep this change to one thing.

DocumentDB Local shipped in the VS Code extension's 0.10.0 release: the
extension now creates and starts the container itself, so someone already
working in VS Code no longer needs to run Docker by hand and then type a port,
username, password and TLS choice back into a connection wizard.

The home page only offered the Docker command, so that path was invisible to
the people it was built for -- the ones who arrive at the site without the
extension and leave with a terminal command.

Docker stays selected by default. It works everywhere and needs nothing beyond
Docker itself, while the VS Code path only pays off for people who already live
in that editor, so it is offered rather than assumed.

The install link comes before the deep link, and neither appears alone. A
vscode:// URL for an extension that is not installed does nothing visible at
all -- no error, no navigation -- so presenting it on its own would leave a
first-time visitor clicking a button that silently does nothing.

The heading moves from 'Run locally with Docker' to 'Run DocumentDB locally',
since it now covers both. The run-with-docker anchor is kept: nothing in the
repository links to it, but it is a public URL and it still lands on the right
card.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Signed-off-by: Guanzhou Song <guanzhousong@microsoft.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant