Add local DocumentDB Quick Start design by guanzhousongmicrosoft · Pull Request #653 · microsoft/vscode-documentdb

guanzhousongmicrosoft · 2026-05-19T02:55:33Z

Summary

Add a UX-focused design doc for Local Quick Start: installing, starting, connecting to, and managing DocumentDB Local from the extension.
Capture learnings from the vscode-cosmosdb emulator attach-only flow.
Include ASCII user flows, lifecycle states, edge cases, and design review findings/resolutions.

Validation

npx prettier --check docs/ai-and-plans/local-quickstart/local-quickstart.md

Signed-off-by: Guanzhou Song <guanzhousong@microsoft.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Adds a UX design reference for the proposed Local Quick Start experience, documenting how the extension would install, start, connect to, and manage a local DocumentDB container from VS Code.

Changes:

Adds end-to-end UX flows, tree shapes, lifecycle states, and action matrices.
Documents conflict handling, Docker readiness, telemetry hints, edge cases, non-goals, and design review outcomes.
Captures intended coexistence with the existing manual local connection flow.

tnaum-ms · 2026-05-19T10:23:28Z

@guanzhousongmicrosoft Have you had a chance to check out the wizard and container launch flow in the Postgres extension?

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Guanzhou Song <guanzhousong@microsoft.com>

tnaum-ms · 2026-05-20T12:00:50Z

This is encouraging: microsoft/vscode#307838
It opens the path of actually using a web view for the setup and, once that API is added, convert it into a modal style web view.

tnaum-ms · 2026-05-21T11:20:58Z

I'm keen to drop all manual connections in the DocumentDB Local section, and have it dedicated to quick starts only.

Everything else can be just added as a regular connection.

Thoughts?

tnaum-ms · 2026-05-22T13:49:05Z

then we've got the progress in the terminal, and the webview closes automatically.

xgerman

two more things to consider:

users might use test containers which start a container before every test and then tear down after the test. In case of an error, they might choose to retain the container. How can we easily connect to that for investigations?
how do we manage multiple containers running potentially multiple document DB versions or otherDBs?

I am also curious how we initialize the container. Are we relying on the init scripts or will be a special VS code thing? How would we support init script development?

Are we telling users when a new conatiner image becomes available or do we update automatically?

Lastly, if there's an issue with the container are we helping to file an issue in the documentdb repo?

- Add local-quickstart-v2.md: simplified design that removes the dedicated local connection subtree, uses a webview for container creation, gates TLS exceptions in the regular connection wizard, and migrates legacy emulator connections on first launch. - Mark local-quickstart.md as iteration 1 with a forward reference.

tnaum-ms · 2026-06-09T11:58:17Z

@guanzhousongmicrosoft @xgerman -- Iteration 2 of the design doc is here: local-quickstart-v2.md

Key changes from iteration 1:

No dedicated local connection subtree. The DocumentDB Local section is replaced with DocumentDB Local - Quick Start, focused on container/Docker management only. The managed cluster is inline (expand to browse databases).
No local connections, only clusters. User-created localhost connections live alongside regular connections. Existing emulator connections are migrated to a Local Connections (Legacy) folder on first launch.
Emulator templates removed. The "MongoDB Emulator RU" / "DocumentDB Local" / "Custom" picker is dropped. Users use the regular new connection wizard.
TLS exception gated in the regular wizard. The "allow invalid certificates" step appears only for localhost, single-word hostnames, .local domains, and RFC 1918 private IPs. For other hosts, it will be accessible via a connection edit dialog (to be built).
Container creation via webview. Uses existing tRPC/webview infrastructure with card-based design (query insights tab as reference). Will become modal once the VS Code API supports it.
German's feedback incorporated. Docker-first with OCI/podman as follow-up issues, URL-safe password generation, port availability prereq check, platform/CPU validation.

The iteration 1 doc is kept as reference with a forward pointer to this revision.

…decision note - terminal-first create progress for v1.0 (staged in-webview card deferred to v1.1) - adopt @microsoft/vscode-container-client (Docker+Podman) as the runtime layer - port fallback only for the default port; read the bound port from docker inspect - distinguish create-vs-start failure; pre-check connection name AND container name - scope prereq checks v1.0/v1.1; add section 18.1 PostgreSQL source-benchmark learnings - add docs/ai-and-plans/PRs/653-local-quickstart-design/description.md decision note Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

guanzhousongmicrosoft · 2026-06-15T21:04:28Z

@xgerman — thanks for the review. The inline comments are all addressed in iteration 2 (local-quickstart-v2.md) plus the latest commit (cb21ed6); I've replied inline and resolved those threads. Your five review-level questions are now handled in the design too:

Retained test containers — connect for investigation. Any locally reachable container can be attached through the regular new-connection wizard at its localhost:<port> — Quick Start doesn't need to own it. Auto-discovery of unmanaged/test containers is tracked for v1.1. (§13 rule 10, §15)
Multiple containers / versions / other DBs. v1 is single-managed-instance, but recognition is label-based so the model is forward-compatible; multiple managed instances and multiple image versions side-by-side are v1.1. (Other DB engines are out of scope — this is DocumentDB-local.) (§10.1, §15)
Container initialization & init-script development. We use the image's standard init-script convention (mount a host dir into the image's documented init directory) rather than a bespoke VS Code mechanism, so it stays portable and testable outside the extension. "Seed sample data" just drops a bundled init script into that dir; for init-script development, the Advanced panel lets you point at a local scripts folder that's mounted in. (§8.4)
New image: notify vs auto-update. Notify only — an UpdateAvailable badge in the tree; we never auto-update (no-surprises rule). "Update Image" stays a manual, user-initiated verb (v1.1). (§6.1, §11)
Help file an issue on container failure. Planned as a Report Issue action on the Error / readiness-timeout states that pre-fills a GitHub issue with sanitized diagnostics (no credentials, hostnames, or ports, per the telemetry rules). Tracked for v1.1. (§14, §15)

For context, there's a short decision/reasoning note for reviewers at docs/ai-and-plans/PRs/653-local-quickstart-design/description.md, and a PostgreSQL source-benchmark summary in local-quickstart-v2.md §18.1 (we'll reuse @microsoft/vscode-container-client, which already ships both Docker and Podman clients — directly relevant to your OCI point).

…n documentation

github-actions · 2026-06-16T16:10:32Z

✅ Code Quality Checks

Check	Status	How to fix
Localization (`l10n`)	✅ Passed
ESLint	✅ Passed
Prettier formatting	✅ Passed

This comment is updated automatically on each push.

github-actions · 2026-06-16T16:13:34Z

📦 Build Size Report

Metric	Base (`main`)	PR	Delta
VSIX (`vscode-documentdb-0.9.0-beta.vsix`)	7.60 MB	7.60 MB	✅ 0 KB (0.0%)
Webview bundle (`views.js`)	5.88 MB	5.88 MB	✅ 0 KB (0.0%)

Download artifact · updated automatically on each push.

Add local quick start design doc

aa7d9b0

Signed-off-by: Guanzhou Song <guanzhousong@microsoft.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

guanzhousongmicrosoft requested a review from a team as a code owner May 19, 2026 02:55

Copilot AI review requested due to automatic review settings May 19, 2026 02:55

guanzhousongmicrosoft mentioned this pull request May 19, 2026

Add local DocumentDB Quick Start design guanzhousongmicrosoft/vscode-documentdb#1

Closed

Copilot started reviewing on behalf of guanzhousongmicrosoft May 19, 2026 02:57 View session

Copilot AI reviewed May 19, 2026

View reviewed changes

tnaum-ms added this to the 0.10.0 milestone May 19, 2026

guanzhousongmicrosoft and others added 3 commits May 19, 2026 09:27

Expand local quick start design references

e1edad4

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Guanzhou Song <guanzhousong@microsoft.com>

Refine local quick start easy setup UX

aa8e052

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Guanzhou Song <guanzhousong@microsoft.com>

update design doc

fff4b6e

tnaum-ms changed the base branch from next to main May 21, 2026 10:37

Merge branch 'main' into guanzhou/local-quickstart-design

15b747f

tnaum-ms marked this pull request as draft May 22, 2026 15:54

xgerman reviewed May 22, 2026

View reviewed changes

tnaum-ms mentioned this pull request May 29, 2026

Feature: MongoDB Atlas Service Discovery (UX) #531

Open

tnaum-ms added 2 commits June 16, 2026 15:57

Merge branch 'main' into guanzhou/local-quickstart-design

0dea955

docs(local-quickstart): update version references from v1.1 to v1.2 i…

ce0224f

…n documentation

Uh oh!

Conversation

guanzhousongmicrosoft commented May 19, 2026

Summary

Validation

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tnaum-ms commented May 19, 2026

Uh oh!

tnaum-ms commented May 20, 2026

Uh oh!

tnaum-ms commented May 21, 2026

Uh oh!

tnaum-ms commented May 22, 2026

Uh oh!

xgerman left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tnaum-ms commented Jun 9, 2026

Uh oh!

guanzhousongmicrosoft commented Jun 15, 2026

Uh oh!

github-actions Bot commented Jun 16, 2026

✅ Code Quality Checks

Uh oh!

github-actions Bot commented Jun 16, 2026

📦 Build Size Report

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants