release-and-changeset-best-practices

用途

统一 pnpm change intent、提交、版本联动和 repoctl 发布前检查，避免漏掉用户可见改动和脚手架联动。

何时使用

用户问“这个改动要不要加 change intent / changeset”。
用户要补 .changeset/*.md。
用户准备发布。
用户改了 weapp-vite / wevu / @weapp-vite/react / mpcore / templates/* / skills/* / dist/docs / AGENTS.md / website。
用户改了 AI 使用路径，如 screenshot / compare / MCP / logs / skills 安装。
用户要求按仓库流程修 GitHub issue，包括 worktree、最小复现、PR、中文变更说明与 CI 收尾。

不适用场景

本 skill 聚焦仓库交付流程，包括 repoctl release 判定、pnpm change-intent 治理和 issue 修复闭环。

文档同步：使用 docs-and-website-sync。
构建或运行时设计：使用对应 best-practices skill。

核心流程

先判断改动是否用户可见；源码 bug fix、功能新增、行为变化、模板行为变化默认要通过 pnpm change 补 change intent。
下列改动不要轻易归类为“纯内部维护”：
- skills/*
- dist/docs
- 脚手架生成 AGENTS.md
- AI skills 安装行为
- prepare / mcp init|print|doctor / forwardConsole
- wv screenshot / wv compare / wv ide logs
- web runtime / lib mode
- React runtime、React 模板、mpcore provider parity 与多平台构建合约
若 release 涉及 weapp-vite、wevu 或 templates/*，默认联动补 create-weapp-vite bump。
.changeset/*.md 是 pnpm change-intent 存储格式，不代表使用 Changesets CLI；summary 用中文，描述用户感知结果，不写成内部重构流水账。
若任务来自 GitHub issue：
- 先在仓库可写目录创建 git worktree
- 优先在 e2e-apps/github-issues 或最小入口稳定复现
- 先补根因相关 unit / e2e，再做 PR 收尾
交付遵循 Conventional Commits；默认 commit-only，issue 修复走 PR 流程。
- 平台敏感改动先定位最早 OS 分歧，检查 command launch、path normalization、line endings 和 filesystem assumptions。
- touched DevTools parity 场景同时核对 mpcore unit/integration、browser e2e 和必要的 type tests。
发布前优先跑仓库脚本：
- pnpm change status
- node --import tsx scripts/check-create-weapp-vite-changeset.ts
- node --import tsx scripts/check-catalog-changeset.ts
- stable：repo release stable prepare / repo release stable publish
- prerelease：repo release pre enter <alpha|beta|rc|next> / repo release pre publish / repo release pre exit
- 恢复单包发布：repo release ci --mode publish-unpublished --package <name> --version <version>

Skills 改动判定

skill 正文、触发元数据、脚手架 AGENTS 或网站 AI 路由变化属于用户可见的 AI 工作流变化，不应按纯注释维护处理。
只要改动影响 create-weapp-vite 生成的默认指引，默认同时检查 create-weapp-vite bump 和模板输出回归。
change-intent summary 说明用户获得的 AI 工作流、验证路径或命令路由变化，不罗列内部文案重排。

约束

不要漏掉源码 bug fix 的 pnpm change intent。
不要忘记 create-weapp-vite 联动。
不要写英文或空泛的 summary。
不要把用户可见的 AI / docs / template 合约误判成纯内部改动。
不要在复现不稳定时直接修源码并开 PR。
不要把仅某个 OS、DevTools 登录、端口或 automator 连接失败当作产品行为回归。

输出

应用本 skill 时，输出必须包含：

是否需要 pnpm change intent 及理由。
是否需要 create-weapp-vite 联动。
推荐提交类型。
推荐检查命令。
若来自 issue，补充复现路径与 PR 交付状态。

完成标记

change-intent 需求已判断清楚。
需要时已补中文 change intent。
需要时已补 create-weapp-vite bump。
提交方式和交付方式符合仓库规则。
issue 修复时已完成 worktree、复现、回归与 PR 闭环。

参考资料

references/release-checklist.md
references/issue-fix-checklist.md