Agentaily Docs

外观

RELEASE —— 发版手册 ​

「一处改动怎么从写完走到生产、怎么盯到绿、版本怎么管」的发版手册。 「线上跑住 / 应急 / 回滚」看 OPERATIONS.md;「本地怎么开发验证」看 DEVELOPMENT.md。

⚠️ 发布是不可逆的对外动作。合并 / push main 即触发 CD 部署生产 —— 有风险 / 含破坏性迁移 / 大版本的上线,先跟老板确认上线时机(全局准则)。推进走 worktree + PR(见 CLAUDE.md 的「🌳 推进模型」):在自己的 worktree 改、窄提交、push 分支、开 PR;合并回 main 由主会话 / 老板定。

一、当前发版模型:Trunk-based 持续部署(CD) ​

本仓没有人工版本号、没有 release 分支 —— main 即发布线:

worktree 里写改动 → 自洽可构建的窄提交 → push 分支 → 开 PR(CI 门禁跑在 PR 上)
        → (主会话 / 老板拍板)合并回 main → CD 部署生产(agentaily + 官网)→ 冒烟
  • 一处合并 = 一次发布:apps/web → agentaily.pages.dev、apps/website → official-website。机制细节(workflow、就绪门)见 OPERATIONS.md 第三节。
  • 内部 @agentaily/* 包当前走 workspace:* 本地消费、未发 npm;它们随主应用 / 官网一起经 CD 上线,不单独发版(npm 发布是未来项,见第五节)。

二、发版前检查清单(Pre-flight) ​

push main 之前,逐项过:

  • [ ] 本地全绿:pnpm typecheck · pnpm test · pnpm build 都过(= CI 会跑的同一套)。
  • [ ] 每个提交自洽可构建:不 push 引用了别人还没落地的包 / 文件的半成品(CD 会红、且可能拖累同批别的改动)。
  • [ ] 窄暂存自检:git diff --cached --name-only 只有你这次明确改的文件;绝不 git add -A / commit -am(铁律②)。
  • [ ] PR 已开、CI 绿:push 分支后开 PR,等 PR 上的 ci.yml 跑绿(typecheck / test / build);合并回 main 由主会话 / 老板拍板(合并即触发 CD)。
  • [ ] 不可逆项已对齐:含 D1 破坏性迁移 / 大版本 / 影响可达性的改动 → 单独跟老板确认窗口(见 OPERATIONS.md 第六节)。

三、发版流程(Step-by-step) ​

bash
# 0. 确保本地全绿(见上 Pre-flight)
pnpm typecheck && pnpm test && pnpm build

# 1. 窄暂存 + 自洽提交(只 add 你这次明确改的路径)
git add <你的明确路径>
git diff --cached --name-only          # 自检:只有你的文件
git commit -m "feat(xxx): ……"

# 2. push 你的分支(绝不 force;被拒 → git pull --rebase 再推)
git push -u origin <你的分支>

# 3. 开 PR → CI 跑在 PR 上(ci.yml)
gh pr create --base main --head <你的分支> --title "feat(xxx): ……" --body "……"

# 4. 合并回 main(由主会话 / 老板拍板)→ 触发 deploy.yml + deploy-website.yml

提交信息走 Conventional Commits(feat / fix / docs / chore(scope): …),与现有 git 历史一致。

四、盯 CI / CD 到绿(别 fire-and-forget) ​

push 后盯完整条链到生产真的更新,别停在「push 了就完事」:

bash
gh run list --branch main --limit 5     # 看 CI + 两条 Deploy 的状态
gh run watch <run-id>                    # 跟某次 run 到终态
gh run view <run-id> --log-failed        # 失败就看日志、定位、修
  • CI 红 → 修到绿(typecheck / test / build 任一挂都要处理)。
  • Deploy 绿但没真上线? → 多半是 CLOUDFLARE_API_TOKEN 就绪门把 deploy 跳过了(见 OPERATIONS.md 第三节),不是真部署成功。
  • 部署完 → 跑 OPERATIONS.md 第四节冒烟;坏了走第五节回滚。
  • 上线 / 回滚的根因与结果沉淀进记忆 / ROADMAP.md。

五、内部 npm 包发版(未来 · 尚未接线) ​

现状:本 monorepo 暂无 changesets / release workflow;@agentaily/* 都靠 workspace:* 本地消费,没有发到 npm。本节是目标态,接线前别假设它已生效。

当某个 @agentaily/* 包需要被别的仓库依赖(脱离本 workspace)时,按组织既有规范接 Changesets 全自动发版:

  • 丢 changeset → push main → release bot 自动开 Version PR → CI 自动跑 → 绿了自动合 → 打 tag + 发 npm。
  • 全程不手动 npm publish,首发也走 PR→合并→CI 自动发。
  • 落地参照 skill changesets-auto-release / publish-npm-package(复用组织 App agentaily-release-bot),凭证见 vault。
  • 配套交付:被别的仓库消费的内部包,除发布外必须配一个「用法 skill」(全局准则),并在包公开 API 变更时同次更新。

接线后回来把本节从「未来」改成「现行」,并补上具体命令。

六、回滚 ​

发版坏了的回滚路径(CF Pages 即时回滚 / git revert 重 push / D1 数据)统一见 OPERATIONS.md 第五节 —— 先止血、再定位、绝不 force-push。

真相源 / 根文档索引(发版相关) ​

文档与发版的关系
RELEASE.md发版手册(本文)—— 改动怎么走到生产、版本策略
OPERATIONS.md运维手册 —— CD 机制、冒烟、回滚、数据 / 域名运维
DEVELOPMENT.md本地开发指南(发版前的全绿验证在此跑)
ROADMAP.md能力地图 + 当前进度(发版能力缺口在此跟踪)
CLAUDE.md项目级 Agent 指引(根文档索引 + 维护纪律)

维护纪律:任何改动新增 / 改变了发版方式、CI/CD 门禁、版本 / 发布策略、或接上了 npm 自动发版时,在同一次改动里更新本文——把「文档声称的发版流程」与「实际生效的流程」之间的漂移当 bug 修。详见 CLAUDE.md 的「根文档索引 + 维护纪律」。