Testing and Release Process zh CN

测试与发布流程

语言： English · 简体中文

LWC 在本地验证本次改动影响面，并以完整 release workflow 作为跨平台门禁。一次 Release 由 source tag、六个平台的 checksum-verified binary、GitHub Release 和公开 @i-xor/lwc package 组成。Release notes 是运维契约，不能只写一行 commit summary。

本页面向维护者；普通用户请阅读安装与升级。

支持的 Release Target

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 target 发布 .tar.gz，Windows target 发布 .zip，SHA256SUMS 覆盖所有 archive。

版本来源

Tag 前确保以下版本完全一致：

• Cargo.toml package version；
• Cargo.lock 中 resolved package version；
• npm/package.json version。

Git tag 为 v<version>，binary 与 npm 都应报告 lwc <version>。

GitHub asset 尚未存在时不要发布同版本 npm，因为 npm postinstall 会寻找完全匹配的 tag 与 archive name。

变更范围与本地验证

先运行覆盖完整改动面及直接依赖方的测试。Documentation-only edit 之后不必反复执行无关昂贵 suite；CI 仍是最终完整 release gate。

最终 tag 前，release workflow 要求：

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

Release gate 还会执行 ignored graph benchmark budget。各 platform job 用 release mode 测试，并在对应 target 真实运行 init/config/graph smoke。

Source tree 必须 clean。生成 Viewer asset 要与 web/src 一致；workflow build 后如果 web/dist 出现 diff，会直接拒绝。

Release Notes 规范

创建带完整 Markdown notes 的 annotated tag。适用时采用以下结构：

## 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.

禁止写入内部 Agent 对话、本地 temp path、未经验证 claim、含糊的 “bug fixes” 或 commit subject 堆叠。Breaking change 与 data migration 必须醒目标注。

GitHub workflow 会验证 tag 是 annotated、notes 非空，将 annotation 持久化，再通过 --notes-file 原样发布同一份内容。

Tag 与 GitHub Release 顺序

1. 把经过 review 的变更合入 clean main；
2. 确认 version file 与 release notes；
3. 创建并 push annotated v<version> tag；
4. 等待 release acceptance 与六个 target build；
5. 验证 GitHub Release title、notes、archive、SHA256SUMS 与 install.sh；
6. 隔离下载/安装，并 read back lwc --version。

不要替换或移动已有 release tag。错误 release 应通过新 patch version 修正。

Binary 完整性链

每个 target job 会：

1. 测试并构建 release binary；
2. 执行 target-native smoke；
3. 打包 binary、中英文 README 与 Apache license；
4. 生成 archive-specific SHA-256 file。

Checksum job 会把这些文件合并为稳定排序的 SHA256SUMS。Consumer 应在解压前验证 archive hash。

npm 发布顺序

必须先有 GitHub asset。随后 release workflow 会针对已发布 asset 安装本地 npm package 做 smoke。

真正 registry publication 刻意保留为本地 authenticated maintainer action：

cd npm
npm publish --access public

发布前确认 npm authentication 与 package ownership。发布后安装到全新隔离 prefix 并验证：

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

npm installer 支持 Node.js 22 或更高版本；它把 platform/architecture 映射到一份 release archive，以每次 30 秒 timeout、两次 retry 下载 archive 与 checksums，验证 SHA-256，解压，并在替换前校验 binary version。

绝不能先发布 npm，否则 postinstall 会指向尚不存在的 asset。

crates.io 发布

Crate publication 是另一项 authenticated maintainer action。运行 cargo package --locked，检查 package content，且只有 crates.io version 属于本次发布目标时才 publish。

Registry success 不能替代 GitHub binary verification，两种渠道服务于不同安装方式。

升级行为

新兼容 binary 首次打开旧 Store 时，会走受支持 migration path。耗时迁移可能返回 Work 与 safety checkpoint。

升级后运行：

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

不能因为升级暴露了缺失图能力就直接初始化。Graph enablement 始终需要明确 project consent。

旧 failed draft 与 inverse patch 必须保持 checksum compatible。Migration 或 recovery 变化需要前一个已发布格式的 fixture coverage。

发布后 Readback

分别验证所有公开 surface：

• Git tag type 与 target commit；
• GitHub Release notes 与 assets；
• Actions quality 与全部 target job conclusion；
• 用下载的一份 archive 校验 SHA256SUMS；
• npm registry version、metadata 与 isolated install；
• 如果发布了 crates.io，则验证对应 version；
• installed binary 中 bundled using-lwc Skill 与 AgentTarget integration；
• release documentation link。

全部通过后才能宣布可用。Pushed tag 或成功 upload request 都不是 publication proof。

发布失败

• Registry publication 之前：修复 source、提升 patch、创建新 tag；
• GitHub asset 不完整：不要发布 npm，先诊断 failed target job；
• Asset 有效但 npm postinstall 失败：区分 network retry exhaustion、checksum、extraction 与 version mismatch；
• Released binary 存在 correctness/security defect：说明影响、准备 patch，需要 embargo 时使用 Security policy；
• 禁止把删除 user draft 或 production Wiki state 当成 release cleanup。

下一篇：CLI 与配置参考