Skip to content

chore: (docs) document API version support and deprecation policy @W-12345678@ #692

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
rax-it wants to merge 2 commits into
base: main
Choose a base branch
from
Open

chore: (docs) document API version support and deprecation policy @W-12345678@ #692

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1f466fc
docs: document API version support and deprecation policy
rax-it Oct 9, 2026
2ce5bba
docs: note how to mark an API version deprecated
rax-it Oct 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 2 additions & 3 deletions .cursorrules
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -134,9 +134,8 @@ This plugin provides three main commands:

### API Version Management

- Supports multiple Salesforce API versions (62.0-65.0)
- Has version mappings in `apiVersionMetadata` in package.json
- Different tags target different org versions
- Supported versions are the keys of `apiVersionMetadata` in package.json, each backed by an `@lwc/sfdx-local-dev-dist-<version>` alias
- Support/deprecation policy and decision log: see "API version support" in CONTRIBUTING.md

## File Structure Understanding

Expand Down
40 changes: 40 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,3 +58,43 @@ R2b Release
| 296-patch | spring32 | 84 | 23 |
| 298-patch | summer32 | 85 | 24 |
| 300-patch | winter33 | 86 | 25 |

## API version support

Each supported API version ships its own `@lwc/sfdx-local-dev-dist-<version>` bundle (aliased in `package.json`, listed in `apiVersionMetadata`). Bundles can't be shared across versions because each one includes that release's LWC compiler. Every bundle adds significant install size, so plan version removals as well as additions.

@wjhsf wjhsf Oct 9, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Each supported API version ships its own `@lwc/sfdx-local-dev-dist-<version>` bundle (aliased in `package.json`, listed in `apiVersionMetadata`). Bundles can't be shared across versions because each one includes that release's LWC compiler. Every bundle adds significant install size, so plan version removals as well as additions.
Because Salesforce releases are deployed in a staggered manner, this plugin supports multiple API versions at a time. Because users can manually specify an API version to use, this plugin deprecates each API version once rollout of the following version has completed, and removes each deprecated version after one release.
Supported versions are listed in `apiVersionMetadata` in `package.json`.

The motivation is more important than the technical details here. (And the technical details may change when we make changes to add deprecation warnings.)


### How users select a version

The bundle is picked from the org connection's API version, not the org's release:

- `lightning dev app|component|site --api-version <version>`, otherwise
- the `org-api-version` config value, otherwise
- the Dev Hub's API version.

So an R2b rollout shifts the default but never drops a version's usage to zero. Users and projects can pin an older version, and orgs don't all upgrade at the same moment. Expect usage to taper off after rollout.

Comment on lines +66 to +75

@wjhsf wjhsf Oct 9, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
### How users select a version
The bundle is picked from the org connection's API version, not the org's release:
- `lightning dev app|component|site --api-version <version>`, otherwise
- the `org-api-version` config value, otherwise
- the Dev Hub's API version.
So an R2b rollout shifts the default but never drops a version's usage to zero. Users and projects can pin an older version, and orgs don't all upgrade at the same moment. Expect usage to taper off after rollout.

Usage is described in the README, and this isn't particularly relevant to contributing.

### Removing a version

Removing a version is a breaking change, so it follows the [Salesforce CLI deprecation policy](https://developer.salesforce.com/docs/platform/salesforce-cli-reference/guide/cli_reference_deprecation.html): 4 months' notice, which is roughly one release.

1. Deprecate the version at release N R2b. The plugin doesn't have a deprecation mechanism yet. The intended approach:
- Add a `deprecated` field to the version's `apiVersionMetadata` entry.
- When a command selects that version, print a warning with `this.warn()`.
- Don't use `Lifecycle.emitWarning()`: `SfCommand` only prints those when the command exits, and `lightning dev` commands are long-running.
- Also announce the deprecation in the release notes.
2. Check usage telemetry before removing it (see below).
3. Remove it at release N+1 R2b.

The new version is added at the start of the N+1 rollout, but the old one can't be removed until R2b. So the plugin briefly ships one extra bundle.
Comment on lines +76 to +88

@wjhsf wjhsf Oct 9, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's already a section above for R2b, move this into there.


### Usage telemetry

Command executions by API version are in the CLI's Azure Application Insights. To get access, follow [DX Telemetry - Azure Application Insights Access](https://docs.google.com/document/d/1mHWon34OUj67CnKUdGGB7nrpTtDBx_9OcUhl79tVF-A/edit?tab=t.0).

The telemetry doesn't show whether a version was picked by default or set explicitly. Judge removal on the trend over a set window after release, not a single snapshot.

Comment on lines +90 to +95

@wjhsf wjhsf Oct 9, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
### Usage telemetry
Command executions by API version are in the CLI's Azure Application Insights. To get access, follow [DX Telemetry - Azure Application Insights Access](https://docs.google.com/document/d/1mHWon34OUj67CnKUdGGB7nrpTtDBx_9OcUhl79tVF-A/edit?tab=t.0).
The telemetry doesn't show whether a version was picked by default or set explicitly. Judge removal on the trend over a set window after release, not a single snapshot.
  1. We shouldn't link to internal docs from a public repo.
  2. Because we've decided on the deprecation policy, we don't need to care about telemetry for contributing.

### Decision log

| Date | Decision | Source |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 2026-10-09 | Keep API 66.0 through the 264 rollout. Deprecate it at 264 R2b and remove it at 266 R2b. 180-day usage: 66.0: 8,514 executions / 1,503 orgs; 67.0: 17,273 / 1,974; 68.0: 2,688 / 362. | [#platform-cli](https://salesforce-internal.slack.com/archives/C01LKDT1P6J/p1791556792551479), [original request](https://salesforce-internal.slack.com/archives/C05P1MZ2DN2/p1790887576398399) |
Comment on lines +97 to +100

@wjhsf wjhsf Oct 9, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
| Date | Decision | Source |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 2026-10-09 | Keep API 66.0 through the 264 rollout. Deprecate it at 264 R2b and remove it at 266 R2b. 180-day usage: 66.0: 8,514 executions / 1,503 orgs; 67.0: 17,273 / 1,974; 68.0: 2,688 / 362. | [#platform-cli](https://salesforce-internal.slack.com/archives/C01LKDT1P6J/p1791556792551479), [original request](https://salesforce-internal.slack.com/archives/C05P1MZ2DN2/p1790887576398399) |
  1. Internal
  2. Not particularly relevant to contributing

Loading