webspatial/webspatial-sdk/webspatial-release

WebSpatial 版本发布（Changesets）

本仓库是 pnpm workspace，多包发布由 changesets 统一驱动。

English quick guide

• Release branch: `stable`. Publishing workflow runs on pushes to stable.
• Fixed version group: core/react/builder/platform packages are versioned together.
• Commands: pnpm changeset, pnpm ci:publish, pnpm changeset:pre-enter, pnpm changeset:pre-exit.
• After publish: CI tags v<version> and creates a sync PR from stable to main.

关键约定（务必先读）

• 发布主分支是 `stable`：Changesets 发布工作流仅在 push 到 stable 时触发（.changeset/config.json 里的 baseBranch 也是 stable）。
• 一组包固定同版本：@webspatial/core-sdk、@webspatial/react-sdk、@webspatial/builder、@webspatial/platform-visionos 属于 fixed 组，发布时会一起涨版本。
• 主分支 `main` 会被自动同步：stable 发布成功后，CI 会自动创建 “Merge stable into main” 的同步 PR（见 .github/workflows/changesets.yml）。

什么时候需要 Changeset

以下情况 必须 加 .changeset/*.md：

• 修改了任何 packages/* 中的可发布内容（对外 API、类型、行为、构建产物）。
• 修复 bug / 新增特性 / 性能优化，且会影响用户。

以下情况 可以不加（但要确认不影响发布包）：

• 仅改 demo（apps/test-server）、仅改测试（不影响发布包）、仅改 CI。
• 纯内部重构且不改变对外行为（建议仍加 patch，避免漏发）。

Changeset 如何写（建议模板）

在仓库根目录执行：

pnpm changeset

选择要发布的包与版本类型：

• patch：bugfix、小改动、兼容性增强（新增可选字段、修复边界条件）。
• minor：向后兼容的新能力（新增 API、默认行为不变但能力增强）。
• major：破坏性变更（删除/重命名 API、行为不兼容、强制迁移）。

正文建议包含：

• 变更点一句话（what）
• 影响与原因（why）
• 迁移说明（如有）

发布前自检（发版人/合入前都应做）

在仓库根目录：

pnpm install
pnpm run buildPackages
pnpm test

如果你改动涉及 React/事件/类型：

• 确认类型导出路径与 exports 没破坏（尤其是 packages/react/package.json）。
• 对事件新增字段，优先做“向后兼容”（新增可选字段），并补单测覆盖。

正式发布流程（stable 发布）

1. 确保本次要发布的改动都已在 PR 中合入，并且 changeset 已齐全。
2. 将 main 的发布内容合入 stable（团队按既定流程：merge / cherry-pick / PR）。
3. 当 stable 有新的 push：

• GitHub Actions Changesets 工作流会自动运行（.github/workflows/changesets.yml）。
• 它会先尝试创建 “chore: update versions” 的版本 PR；
• 合并后会执行 changeset publish（脚本 pnpm ci:publish），并推送 v<version> tag；
• 发布成功后会自动创建 stable → main 的同步 PR。

发布结果确认（建议）

• 在 GitHub Release / Tags 中确认出现 v<version>。
• 在 npm 上确认 @webspatial/* 对应版本已更新。
• 如使用 Preview Release，确认临时包已失效或无误。

预发布（alpha）

仓库提供了 alpha 预发布命令：

pnpm changeset:pre-enter
pnpm changeset:pre-exit

建议用法：

• 当需要给少量用户验证变更时，进入 alpha 预发布模式，生成 alpha 版本号，验证后退出。
• 注意：预发布仍应遵循 Changeset 规范，避免出现“发了 alpha 但忘记写 changeset”的情况。

预览发布（PR/分支的临时包）

仓库有 Preview release 工作流（.github/workflows/preview-release.yml），用于在 PR 上产出临时包。

• 触发方式：给 PR 打上标签 trigger: preview（或 push 到 main/stable 时满足条件）。
• 作用：把 ./packages/* 发布成临时可安装版本，便于联调验证（通过 pkg-pr-new）。

常见故障排查

1) stable push 后没有触发发布

• 确认目标分支是 stable（不是 main）。
• 确认 GitHub Actions 工作流是否被禁用。

2) 发布没有产出新版本

• 大概率是本次合入没有 changeset，或 changeset 被误删。
• 检查 .changeset/ 目录是否存在本次变更对应的 md 文件。

3) fixed 组版本不一致

• 本仓库配置为 fixed 组，理论上不应不一致。
• 若出现，检查 .changeset/config.json 的 fixed 配置是否被误改，或是否存在手动改版本号的提交。

4) 版本 PR 生成了但 publish 失败

• 先看 CI 日志里 pnpm run setup 是否成功（构建失败会导致 publish 失败）。
• 再看 npm 鉴权/权限问题（工作流使用 OIDC，相关问题需要在 CI 侧修复）。