docs: restructure READMEs so the happy path leads and advanced usage is findable#80
Open
dnegstad wants to merge 2 commits into
Open
docs: restructure READMEs so the happy path leads and advanced usage is findable#80dnegstad wants to merge 2 commits into
dnegstad wants to merge 2 commits into
Conversation
…is findable Main README: - Reorder sections so usage leads: Getting Started -> How It Works -> Configuration reference -> workflows -> Troubleshooting -> reference -> Development -> Provenance. Release provenance and Repository Layout were sitting at positions 3 and 4, ahead of any configuration docs. - Add a Contents list; the file has 25+ top-level and nested sections with no navigation outside GitHub's outline sidebar. - Add "Verify it worked" with the three store/trust checks and a curl call, so the happy path ends in confirmation rather than an assumption. - Add a Troubleshooting section: output channel names for both extensions, plus the common failure modes (nothing happened, browser still warns, curl fails, Kestrel picks the wrong cert, container push rejected). - Add a Commands reference. All three commands were previously mentioned only inside settings-table cells, and the host-side browser trust command not at all. - Add a Linux browser trust section. NSS/certutil was documented only in the host extension README, though without it forwarded ports still warn in the browser on Linux hosts. - Add the per-entry field table for userCertificates. The host settings table pointed at a "per-entry schema" that did not exist, leaving trustInContainer used in an example but never defined. - Disambiguate generateDotNetCert: the feature option and the host setting share a name and had near-identical descriptions in adjacent tables. The feature row now describes pulling the host cert into the container. - Document setup-cert.sh: both invocation forms, the bundle JSON shape, the openssl/jq prerequisites, and the fact that the feature does not copy the script into the container. - Add an environment variable reference covering SSL_CERT_DIR, the DEVCONTAINER_DEV_CERTS_* vars, and the DOTNET_GENERATE_ASPNET_CERTIFICATE suppression, and move the suppression rationale out of How It Works. - Fix a broken sentence in the opening paragraph; normalize "Dev Container" capitalization in prose; link Prerequisites to Supported Platforms. Extension READMEs: - Host: add a Commands table; promote browser trust from a fourth-level subsection to a top-level section next to Quick Start; add a Troubleshooting pointer with the output channel name. - Remote: drop a duplicated install-prompt sentence; add "Verify it worked" and a Troubleshooting pointer. - Both: trim the repeated 7-row feature options table to the options that affect that extension, linking to the main reference for the rest, and replace the duplicated dotnet suppression prose with a summary plus link. - Both: link back to the repository, which neither marketplace page did. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KjJpJFDYwZTq7oYF7zLAkH
The script isn't installed into the container by the feature and isn't reachable in a usable form today, so documenting it as a non-VS Code path promised support that doesn't currently exist. Removes the section, its Contents entry, and the Repository Layout line. Limitations now states plainly that VS Code is the only supported editor. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KjJpJFDYwZTq7oYF7zLAkH
There was a problem hiding this comment.
Pull request overview
Restructures documentation around setup, configuration, verification, and troubleshooting.
Changes:
- Reorders the main README and adds navigation and references.
- Expands verification, Linux browser trust, and troubleshooting guidance.
- Aligns extension READMEs with the central documentation.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
README.md |
Reorganizes and expands project documentation. |
src/vscode-ui-extension/README.md |
Updates host extension usage and reference material. |
src/vscode-workspace-extension/README.md |
Updates remote extension verification and troubleshooting. |
Comments suppressed due to low confidence (3)
README.md:212
- This value is not always formed with a colon. When pruning removes every system CA directory,
install.shdeliberately emits the trust directory alone to avoid a trailing empty path element (install.sh:280-289,333-339). Document the conditional join so users do not infer that a trailing colon is expected.
| `SSL_CERT_DIR` | `$HOME/.aspnet/dev-certs/trust:` + the resolved `sslCertDirs` | Always |
README.md:401
echo $SSL_CERT_DIRprints an expanded absolute home path (for example,/home/vscode/.aspnet/...), never a path beginning with the literal~. As written, a correctly installed feature fails this troubleshooting criterion.
4. **Did the feature actually install?** Check `echo $SSL_CERT_DIR` in a container terminal — it should start with `~/.aspnet/dev-certs/trust`. If it's empty, the feature didn't run; rebuild the container.
README.md:506
- This repository-layout entry references a nonexistent
test/hydrate.mjs. The actual hydration script used by the package command istest/sample-project/hydrate-sample-project.mjs, so the current path sends contributors to the wrong location.
hydrate.mjs Assembles a runnable test project from the template + feature
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| - **Auto-generated dev cert matches .NET's format only.** The `generateDotNetCert` flow produces a cert identical to `dotnet dev-certs https` (specific OID marker, subject, SAN entries). To sync differently-shaped certs (corporate CAs, custom wildcard certs, etc.), add them via the `devcontainerDevCerts.userCertificates` VS Code setting — they're copied as-is. | ||
| - **VS Code only.** The companion extension pattern relies on VS Code's cross-host command routing. Other editors (JetBrains, Vim, etc.) are not supported, though the devcontainer feature includes a `setup-cert.sh` fallback script (with a `--bundle-json` form for multi-cert bundles) for manual use. | ||
| - **VS Code only.** The companion extension pattern relies on VS Code's cross-host command routing, so VS Code is currently the only supported editor. Other editors (JetBrains, Vim, etc.) can't use this flow today. |
|
|
||
| ### Environment variables | ||
|
|
||
| The feature writes these into the container at build time (via `/etc/profile.d` and the container environment), so they apply to VS Code terminals, tasks, debug sessions, and `docker exec` alike: |
|
|
||
| This extension logs to the **Dev Container Dev Certs (Remote)** output channel (**View → Output**, then pick it from the dropdown) — what was received from the host, where each file was written, and which thumbprints were considered. The host companion logs separately to **Dev Container Dev Certs** in your local VS Code window; a failure to *obtain* certificates is usually explained there. | ||
|
|
||
| If nothing happened at all, check that the host extension is installed, that `autoInject` is on (or run **Dev Certs: Inject Certificate into Remote**), and that `echo $SSL_CERT_DIR` in a container terminal starts with `~/.aspnet/dev-certs/trust`. See the [troubleshooting guide](https://github.com/dnegstad/devcontainer-dev-certs#troubleshooting) for the full list. |
Comment on lines
+493
to
+497
| vscode-workspace-extension/ VS Code remote extension (extensionKind: workspace) | ||
| src/ | ||
| certInstaller.ts Writes cert files to correct paths | ||
| util/rehash.ts Pure TypeScript c_rehash (OpenSSL subject hash computation) | ||
| util/paths.ts .NET store and OpenSSL trust directory paths |
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
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.
Main README:
Configuration reference -> workflows -> Troubleshooting -> reference ->
Development -> Provenance. Release provenance and Repository Layout were
sitting at positions 3 and 4, ahead of any configuration docs.
no navigation outside GitHub's outline sidebar.
so the happy path ends in confirmation rather than an assumption.
plus the common failure modes (nothing happened, browser still warns,
curl fails, Kestrel picks the wrong cert, container push rejected).
only inside settings-table cells, and the host-side browser trust command
not at all.
host extension README, though without it forwarded ports still warn in the
browser on Linux hosts.
pointed at a "per-entry schema" that did not exist, leaving trustInContainer
used in an example but never defined.
share a name and had near-identical descriptions in adjacent tables. The
feature row now describes pulling the host cert into the container.
openssl/jq prerequisites, and the fact that the feature does not copy the
script into the container.
DEVCONTAINER_DEV_CERTS_* vars, and the DOTNET_GENERATE_ASPNET_CERTIFICATE
suppression, and move the suppression rationale out of How It Works.
capitalization in prose; link Prerequisites to Supported Platforms.
Extension READMEs:
subsection to a top-level section next to Quick Start; add a Troubleshooting
pointer with the output channel name.
and a Troubleshooting pointer.
affect that extension, linking to the main reference for the rest, and
replace the duplicated dotnet suppression prose with a summary plus link.
Co-Authored-By: Claude Opus 5 noreply@anthropic.com
Claude-Session: https://claude.ai/code/session_01KjJpJFDYwZTq7oYF7zLAkH