版本管理与发布指南

为了保持 SaaS 系统核心业务应用（Web、Server、Docs）的一致性，项目采用 Changesets 方案实现应用层的统一版本管理。

核心理念：版本锁定 (Fixed Versioning)

在本项目中，业务应用（apps/* 下的项目）共用同一个版本号。

• 关联升级：当 web 或 server 发生变动时，项目会自动同步升级 apps/ 下的所有项目。
• 排除项：packages/* 下的公共包（如 @IAM/api）不参与版本联动，以避免因版本号变动触发 CI/CD 的无意义部署。它们通过 workspace:* 保持代码同步。

---

日志记录流 (Daily Development)

当您完成了一项功能或修复了一个 Bug，请按照以下步骤记录变动：

1. 运行记录命令

在项目根目录运行：

pnpm changeset

2. 交互式选择

• 选择包：使用空格选中 web 或 server（选任意一个都会触发整体联动）。
• 选择级别：
  • patch：补丁，用于 Bug 修复、小改动。
  • minor：次版本，用于新增功能（非破坏性）。
  • major：主版本，包含重大破坏性变更（慎选，会跳到 2.0, 3.0）。
• 输入描述：在弹出的编辑器中输入改动概要。

3. 提交变动文件

执行完成后，.changeset 目录会生成一个 .md 记录文件。请将其随代码一起 Commit 并推送。

注意：不要将 .changeset 目录加入 .gitignore，它是版本历史的一部分。

---

版本发布流 (Release Process)

当积累了足够的变更准备发布新版本时：

1. 统一升级版本号

在根目录运行：

pnpm version-packages

该命令会自动：

1. 消费掉所有待处理的 changeset 记录文件。
2. 自动更新所有 package.json 中的 version 字段。
3. 自动在每个包的 CHANGELOG.md 中追加改动说明。

2. 提交版本变更

手动提交版本号修改和日志更新：

# 请严格遵守 Commitlint 规范
git add .
git commit -m "chore(release): bump version to 1.x.x and update changelogs"

3. 打标签并推送

为了方便溯源，必须在 Git 上打上对应的 Tag：

# 创建本地标签
git tag -a v1.x.x -m "Release v1.x.x"

# 推送所有内容至远程
git push origin main --tags

---

避坑指南 (Best Practices)

• 严禁手动修改版本号：永远不要去 package.json 里手动修改 version 字符串，这会导致版本树冲突，请始终依赖 pnpm version-packages。
• 关于 Major 升级：在运行 pnpm changeset 询问 “Which packages should have a major bump?” 时，若非破坏性变更，请直接按 Enter 跳过，否则版本号会从 1.x.x 直接跳到 2.0.0。
• 保持 Changelog 清晰：Changeset 的这段描述是给最终用户看的，请尽量写得清晰易懂。