From 0a2cadb5db28e63e67b909f6706d609949c4d942 Mon Sep 17 00:00:00 2001 From: kkdev92 <112151103+kkdev92@users.noreply.github.com> Date: Wed, 2 Sep 2026 20:34:58 +0900 Subject: [PATCH] docs: point the README at the published documentation site The API reference, the guide and the migration guide are now served at https://vscode-ext-kit.kkdev92.dev/, built from the tag that npm resolves as `latest`, so the site and the package cannot disagree about what an export looks like. The README now says where to read them, and the entry under Known Limitations that said the reference was generated but not published is gone, because it no longer describes anything. Two claims that named an exact patch version are rewritten to name the line instead. `4.1.0 is the current release` and `4.1.0 ... holds latest on npm` were both true when written and false one release later; naming `4.1` and `4.x` says the same thing without going stale every patch. The npm badge already carries the exact version. Verified: every URL added here returns 200, and the claim that `1.134.0` is the newest `@types/vscode` still holds against the registry. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_013Tfbt5Vy1jB9C6mMAHXhLY --- CHANGELOG.md | 9 +++++++++ README.md | 26 +++++++++++++++----------- 2 files changed, 24 insertions(+), 11 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d3dcbca..55f753b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,15 @@ Pre-1.0 releases followed it in spirit; their breaking changes are marked **Brea ## [Unreleased] +### Added + +- **The documentation is published at .** + The API reference, the guide and the migration guide are rendered as one set + from the version that is `latest` on npm, so the site and the package never + disagree about what an export looks like. Nothing about the package changed; + the same set has always been buildable from the repository with + `npm run docs:api`. + ## [4.1.1] - 2026-09-02 **A patch about documentation only.** The published code is byte-for-byte what diff --git a/README.md b/README.md index d90c25c..be90d3d 100644 --- a/README.md +++ b/README.md @@ -12,8 +12,12 @@ runs it, and tears it down through exactly one path. _Built for extensions big enough that "what does this thing actually register?" has stopped being obvious._ -> **Status:** `4.1.0` — the current release. It adds introspection and tooling -> to `4.0.1` — a plan as JSON, a preflight failure as data, a command-line +**Documentation:** — the API reference, +the guide and the migration guide, rendered as one set from the version that is +`latest` on npm. + +> **Status:** `4.1` is the current line. It adds introspection and tooling to +> `4.0.1` — a plan as JSON, a preflight failure as data, a command-line > tool, an API reference, a migration guide — and changes nothing that existed; > the VS Code floor stays `^1.134.0`. 2.x was a utility library with a > different shape; it continues on `v2-maintenance` and anything pinned to @@ -258,10 +262,11 @@ Values you pass around: `ok` `err` `unwrap` `mapResult` and the `s.*` schema builders; `FrameworkError` with `userError` / `validationError` / `classifyError` / `isCancellation`; `DisposableCollection` and `createScope`. -Full signatures live in the `.d.ts` files and the JSDoc on each export. -`npm run docs:api` renders that JSDoc into an API reference under `docs/api/` -(TypeDoc); CI runs it with warnings as errors, so a broken link or a type a -public signature names but the package does not export cannot ship. +Full signatures live in the `.d.ts` files and the JSDoc on each export, and are +published at alongside the guide and the +migration guide. `npm run docs:api` renders the same set locally under +`docs/api/` (TypeDoc); CI runs it with warnings as errors, so a broken link or a +type a public signature names but the package does not export cannot ship. --- @@ -322,7 +327,6 @@ trusted for things it cannot do. - **The Test Host does not reproduce VS Code**: it renders no UI, interprets no contribution point, and does not substitute a direct `import "vscode"` - **No editor events yet**: `Editors` hands you the active editor and cross-file edits, but there is no `onDidChangeActive` / `onDidChangeSelection` / `onDidChangeDocument`; subscribing means reaching for `vscode` directly and disposing by hand, which is the one place the single-cleanup-owner rule leaks - **No log-level filtering, deliberately**: the framework writes to a `LogOutputChannel` and VS Code owns the level — per channel, persisted, in the Output panel. An extension cannot raise its own channel's level, so a `logLevel` setting of your own can only ever make the log quieter -- **No hosted API reference yet** — it is generated from the JSDoc (`npm run docs:api`) but not published --- @@ -457,10 +461,10 @@ This is a personal project maintained in spare time. It is active, but support is best-effort: I'll do my best to review issues and PRs, and releases may be a bit slow sometimes — thank you for your patience. -`4.1.0` is the current release and holds `latest` on npm, so a fresh -`npm install` gets the framework. `2.x` continues on `v2-maintenance` and still -takes bug fixes; anything pinned to `^2.x` resolves there and is unaffected. -Breaking changes are listed in the [CHANGELOG](CHANGELOG.md). +The `4.x` line holds `latest` on npm, so a fresh `npm install` gets the +framework. `2.x` continues on `v2-maintenance` and still takes bug fixes; +anything pinned to `^2.x` resolves there and is unaffected. Breaking changes are +listed in the [CHANGELOG](CHANGELOG.md). Helpful things when reporting bugs: