Testing and Release Process

Testing and Release Process

Language: English · 简体中文

LWC tests the changed surface locally and uses the full release workflow as its cross-platform gate. A release consists of a source tag, checksum-verified binaries for six targets, a GitHub Release, and the public @i-xor/lwc package. Release notes are an operational contract, not a one-line commit summary.

This page is for maintainers. Users should follow Installation and upgrades.

Supported release targets

x86_64-apple-darwin
aarch64-apple-darwin
x86_64-unknown-linux-gnu
aarch64-unknown-linux-gnu
x86_64-pc-windows-msvc
aarch64-pc-windows-msvc

Unix targets publish .tar.gz; Windows targets publish .zip. SHA256SUMS covers every archive.

Version sources

Before tagging, keep these versions identical:

• Cargo.toml package version;
• the resolved package version in Cargo.lock;
• npm/package.json version.

The Git tag is v<version>, while both binaries and npm report lwc <version>.

Do not publish npm under a version whose GitHub assets are missing: npm postinstall resolves the matching tag and archive name.

Change scope and local verification

Start with tests covering the complete changed surface and its direct dependents. Do not rerun unrelated expensive suites after every documentation-only edit; CI remains the full release gate.

Before final tag, the release workflow requires:

cd web
npm ci
npm test
npm run typecheck
npm run build
cd ..
cargo fmt --all -- --check
cargo clippy --locked --all-targets --all-features -- -D warnings
cargo test --locked --all-targets --all-features
node --test tests/npm_package.mjs
cargo test --locked --all-targets --no-default-features
cargo package --locked

The release gate also runs the ignored graph benchmark budget. Platform jobs run release-mode tests and a real init/config/graph smoke on each target.

Use a clean source tree. Generated Viewer assets must match web/src; the workflow builds and rejects a dirty web/dist diff.

Release notes standard

Create an annotated tag with complete Markdown notes. Use this structure when applicable:

## Highlights

One short paragraph explaining the user-visible outcome.

## Added

- New capabilities and commands, with the problem they solve.

## Changed

- Behavior changes, migrations, performance, and compatibility.

## Fixed

- Correctness, recovery, security, and platform fixes.

## Upgrade notes

- Required actions, restarts, config changes, or known compatibility limits.

## Verification

- Release gates, real end-to-end coverage, supported targets, and checksums.

## Acknowledgements

- Contributors and upstream projects when relevant.

Do not include internal Agent chatter, local temp paths, unverified claims, vague “bug fixes,” or a dump of commit subjects. Call out breaking changes and data migrations prominently.

The GitHub workflow validates that the tag is annotated and notes are non-empty, persists that annotation, and publishes the same bytes through --notes-file.

Tag and GitHub Release order

1. Merge the reviewed changes to clean main.
2. Confirm version files and release notes.
3. Create and push the annotated v<version> tag.
4. Wait for release acceptance and all six target builds.
5. Verify the GitHub Release title, notes, archives, SHA256SUMS, and install.sh.
6. Perform an isolated download/install and read back lwc --version.

Do not replace or move an existing release tag. Correct a bad release with a new patch version.

Binary integrity chain

Each target job:

1. tests and builds the release binary;
2. performs a target-native smoke;
3. packages binary, English/Chinese READMEs, and Apache license;
4. emits an archive-specific SHA-256 file.

The checksum job combines those files into sorted SHA256SUMS. Consumers should verify the archive hash before extraction.

npm publication order

GitHub assets must exist first. The release workflow then installs the local npm package against those published assets as a smoke.

Actual registry publication is an authenticated local maintainer action by design:

cd npm
npm publish --access public

Before publication, confirm npm authentication and package ownership. After publication, install into a fresh isolated prefix and verify:

npm install --global @i-xor/lwc@<version> --prefix <temporary-prefix>
<temporary-prefix>/bin/lwc --version

The npm installer supports Node.js 22 or newer, maps platform/architecture to one release archive, downloads archive and checksums with 30-second per-attempt timeouts and two retries, verifies SHA-256, extracts, and checks binary version before replacement.

Never publish npm first: its postinstall would point at assets that do not yet exist.

crates.io publication

Crate publication is a separate authenticated maintainer action. Run cargo package --locked, inspect the package contents, and publish only when the crates.io version is part of the intended release.

Registry success is not a substitute for GitHub binary verification; the two channels serve different installation paths.

Upgrade behavior

On first open, a newer compatible binary migrates an older Store through the supported migration path. Long migrations may return Work and a safety checkpoint.

After an upgrade:

lwc --version
lwc --scope project lint
lwc --scope project config show
lwc --scope project graph status
lwc --scope project graph verify
lwc --scope project cg status
lwc agent refresh --target auto --location global

Do not initialize missing graphs merely because an upgrade exposes them. Graph enablement remains explicit project consent.

Older failed drafts and inverse patches must remain checksum-compatible. A migration or recovery change requires fixture coverage from the previous published format.

Post-release readback

Verify all public surfaces independently:

• Git tag type and target commit;
• GitHub Release notes and assets;
• Actions conclusion for quality and all target jobs;
• SHA256SUMS against one downloaded archive;
• npm registry version, metadata, and isolated install;
• crates.io version if published;
• bundled using-lwc Skill and AgentTarget integration from the installed binary;
• release documentation links.

Only then announce availability. A pushed tag or successful upload request is not publication proof.

Failed release

• Before registry publication: fix source, bump patch, create a new tag.
• GitHub assets incomplete: do not publish npm; diagnose the failed target job.
• npm postinstall fails with valid assets: distinguish network retry exhaustion from checksum, extraction, or version mismatch.
• A released binary has a correctness or security defect: document impact, prepare a patch, and use the Security policy when embargo is required.
• Never delete user drafts or production Wiki state as part of release cleanup.

Next: CLI and configuration reference