Docs: a step-by-step migration guide from 2.x

[kkdev92]

Summary

The README has said for a while that there is "no step-by-step migration guide from 2.x". This adds one: docs/migration-from-2x.md.

2.x is a utility library called from the extension's own activate; 4.x is a framework that owns activation and hands the extension modules. The old-to-new table for every removed helper already exists in the 3.0.0-alpha.1 changelog and is linked rather than repeated. What was missing is the order to do the work in, and the guide is that:

1. Inventory the existing activate — one line per registration, module-level let, timer, configuration read and awaited initialisation.
2. Classify each line into the declaration it becomes (a table, one row per kind).
3. Move everything into one module first, as raw registrations, and switch activate/deactivate to the framework's. From that commit on the host owns activation, rollback and cleanup, and every later step is a small commit that turns one raw registration into a declaration while the extension keeps working.
4. Async initialisation and loops → hosted services (start, background with context.delay).
5. Direct subscriptions → owned scopes; configuration reads → defineSettings; mementos → defineStorage (the 2.x envelope is kept, so no data migration).
6. Isolate what is left in raw.register in its own module file, so the modules a unit test loads never import vscode.
7. Run the production plan in the Test Host.
8. Check the manifest against the plan.
9. Add an Extension Host lane.

It closes with what can be deleted afterwards.

Samples

Two new files under docs/samples/, compiled with the consumer's compiler options and checked byte-for-byte against the page by tests/readme-samples.test.ts, which now covers the new page as well as the README and the guide:

• migration-before.ts — a typical starting activate: an awaited index build, a command reading a setting at call time, a watcher with three callbacks, a setInterval disposed by hand, and a hover provider.
• migration-after.ts — the same extension declared: a service, a settings declaration, a command contract, one watcher batch handler, a background hosted service, and the framework's activate/deactivate. It imports nothing from vscode; the hover provider is deliberately absent and the guide says where it goes.

Also

• README: the "Coming from 2.x" section links the guide, and the known-limitations entry no longer claims the guide does not exist.
• CHANGELOG: an entry under Unreleased, and a fix to the 3.0.0 section's link to 3.0.0-alpha.1, which pointed at the wrong date.

Verification

npm run quality (1076 tests, including the 21 sample checks) and npm run verify:package (18 samples type-check against the packed .d.ts) pass.

🤖 Generated with Claude Code