06_gstack发布运营：一键发布与文档同步机制

06_gstack发布运营一键发布与文档同步机制关键字gstack、一键发布、ship技能、document-release、文档同步、发布流水线、CHANGELOG、PR自动化、retro、工程回顾你上一次修改完代码到实际提交 PR中间经历了多少步git stashrebase main处理冲突运行测试等 CI写 PR 描述贴上测试截图通知 reviewer顺便更新一下 README……每一步都不难但放在一起这个流程很容易让工程师在写完代码和代码进 main之间消耗掉半小时到一小时。更隐性的成本是文档。多少工程师发完 PR 之后CHANGELOG 还是上个版本的README 里的接口说明还是旧的CONTRIBUTING.md 里的架构图还对应着三个月前的代码gstack 的发布运营层把这些碎片化的工作统一成两个指令/ship和/document-release。一、/ship完整的发布流水线/ship不是简单的git push它是一个编排了所有发布前置工作的完整流水线/ship 执行序列完全无人值守 步骤 1: 同步代码库 ----------------------------------------------- | git fetch origin | | git rebase origin/main | | 如果有冲突 -- 暂停提示工程师手动解决 | ----------------------------------------------- | v 步骤 2: 运行测试套件 ----------------------------------------------- | npm test或 bun test/pytest/cargo test | | | | 输出 | | Tests: 42 → 51 (9 新测试通过) | | Coverage: 14/14 代码路径100% | | | | 如果测试失败 -- 停止流程报告失败原因 | ----------------------------------------------- | v 步骤 3: 解决 Greptile 代码审查 ----------------------------------------------- | 读取当前 PR 的 Greptile 评论 | | 逐条处理 | | 有效问题 -- 已在之前的 /review 中修复 | | -- 回复已修复见 commit xxx | | 误报 -- 解释为什么不是问题 | | 疑问 -- 如果能确认则回复否则标注待定 | ----------------------------------------------- | v 步骤 4: 推送代码 ----------------------------------------------- | git push origin feature/xxx | ----------------------------------------------- | v 步骤 5: 创建/更新 PR ----------------------------------------------- | 自动生成 PR 描述 | | | | ## Changes | | - 实现 CSV 导出功能最多10万行 | | - 添加时间范围过滤 | | - 修复超时无提示的问题 | | | | ## Test Coverage | | - 新增 9 个测试用例 | | - 覆盖 7 个功能路径 | | - 端到端测试桌面/移动/慢网络全部通过 | | | | ## Screenshots | | [自动附上 /qa 截图] | ----------------------------------------------- | v 步骤 6: 调用 /document-release ----------------------------------------------- | 同步受影响的文档文件 | | (详见下文) | ----------------------------------------------- | v 输出 PR URL: github.com/you/app/pull/42 分支feature/export-csv 测试51/51 通过 覆盖率100% (14/14 路径)整个过程不需要工程师干预除非出现冲突或测试失败。工程师的工作变成了看一眼 PR点击 Merge。二、/document-release解决文档欠债问题文档落后于代码是几乎所有工程团队的通病。原因很简单改代码有明确的需求驱动改文档没有。/document-release的设计把文档更新变成了代码发布的强制附属步骤2.1 工作原理/document-release 的处理流程 输入当前 PR 的代码 diff21个变更文件 | v 扫描所有文档文件 README.md CHANGELOG.md CLAUDE.md CONTRIBUTING.md TODOS.md docs/api-reference.md docs/architecture.md ...共扫描 15 个文档文件 | v 交叉引用代码变更 vs 文档内容 对每个文档文件 - 文档里描述了哪些功能/接口/架构 - 这次代码变更是否影响了这些描述 - 如果影响了哪些地方需要更新 | v 识别需要更新的文件8 个 另外 7 个文件未受本次变更影响 | v 执行更新2.2 具体更新内容README.md 更新 旧支持功能用户管理 | 数据看板 新支持功能用户管理 | 数据看板 | 数据导出CSV CHANGELOG.md 更新关键语气优化 AI 原始生成的 CHANGELOG不采用 Enhanced the platform by implementing CSV data export functionality with configurable parameters including temporal filtering capabilities and volumetric constraints. /document-release 优化后的 CHANGELOG 新增数据导出功能支持 CSV 格式可按时间范围筛选 单次最多导出 10 万条记录。超出时自动截断并提示。 CLAUDE.md 更新 - 项目结构新增 src/export/ 目录说明 - 新增 export_jobs 数据表说明 - 更新相关环境变量列表 TODOS.md 更新 已完成项目标为 [x] [x] CSV 导出基础功能 [x] 时间范围过滤 [ ] Excel/JSON 多格式支持下个sprint [ ] 定时导出任务规划中 docs/api-reference.md 更新 新增 POST /api/export 接口文档 包含请求参数/响应格式/错误码说明 ...共更新 8 个文件2.3 PR 正文自动更新文档更新完成后/document-release会把文档变更摘要附加到 PR 正文## Documentation Changes Updated 8 documentation files: - **README.md**: 添加导出功能到功能列表 - **CHANGELOG.md**: 记录本次发布内容 - **CLAUDE.md**: 更新项目结构说明 - **TODOS.md**: 标记完成项保留后续计划 - **docs/api-reference.md**: 添加导出 API 文档 - [...] Full diff: [查看文档变更]Code reviewer 在审查 PR 时能同时看到代码变更和文档变更确认两者是否对齐。三、CHANGELOG 的语气问题这是一个看似细节、实际上影响团队形象的问题。大量使用 AI 辅助开发的团队CHANGELOG 普遍有一个特征读起来像翻译腔充满了Implemented comprehensive solution for…、Enhanced the functionality by…之类的空话。这种语气的问题不是不准确而是让读者感觉这个 CHANGELOG 不是人写的——因为确实不是人写的。gstack 的/document-release专门针对这个问题做了优化检测模式会被替换 Implemented X functionality Enhanced Y by Z Resolved issues related to... Comprehensive solution for... Leveraging advanced algorithms to... 替换为人类写法 新增 X 功能 修复 Y 问题 优化 Z 性能 支持 W 场景这个细节在团队规模小的时候不重要但当代码库有外部贡献者、有开源用户或者需要给非技术 stakeholder 看 CHANGELOG 的时候语气一致性就变成了信任成本的一部分。四、/retro数据驱动的工程回顾传统的 sprint 回顾是定性的大家说说这周哪里好、哪里不好、下周改什么。这种方式的问题是记忆会筛选信息。印象深刻的问题会被过度强调重要但不显眼的趋势会被忽视。/retro从代码库数据出发提供客观的工程视角/retro --period 2026-03-01:2026-03-28 工程回顾报告 1. 贡献者分析 贡献者 提交数 行数变更 Bug修复 新功能 Alice 47 8,234 12 23 Bob 31 5,102 8 18 Carol 22 3,876 15 5 注意Carol 的 bug 修复比例68%明显高于团队平均37% 可能需要关注负责的代码区域是否存在系统性问题。 2. 代码质量趋势 测试覆盖率 03月01日 62% -------- 03月07日 68% ----------- 03月14日 71% ------------ 03月21日 75% --------------- 03月28日 79% ---------------- -- 持续改善 PR 合并周期平均 03月01日 2.3天 03月14日 1.8天 03月28日 1.1天 -- 流程在提速 3. 技术债趋势 新增 TODO/FIXME 注释23 清理 TODO/FIXME 注释-8 净增15需要关注 4. 识别的模式 [关注] 数据层集中了 41% 的 bug 修复建议专项重构 [好转] CI 失败率从 18% 下降到 6% [新增] 引入了 3 个新的外部依赖需要安全审查 5. 下周建议 优先级1偿还数据层技术债建议分配 2 天 优先级2Carol 的工作方向调整讨论 优先级3安全审查新增依赖这种回顾有两个好处一是客观数字不会说谎二是具体数据层集中了 41% 的 bug比感觉代码质量有点问题更容易推动行动。五、发布运营层的最佳实践使用时序功能开发完成通过 /review 和 /qa 后 1. 调用 /ship (完全无人值守约5-8分钟) | v 2. 检查 PR 重点关注 - 测试报告是否全绿 - 文档更新是否准确 - Greptile 的 [ASK] 问题有没有处理 | v 3. 请求 reviewer 审批 | v 4. Merge PR 整个过程工程师主动花的时间 5分钟发布后每个 sprint 结束或每周一次 1. /retro --period 起始日期:结束日期 获取数据驱动的回顾报告 | v 2. 团队讨论报告里的关键发现 重点趋势性问题 点状问题 | v 3. 制定下周的技术债偿还优先级六、一个容易被忽视的价值/ship和/document-release带来的最大价值不是节省时间——尽管它确实节省了时间。最大价值是让发布这件事变得不再有心理负担。很多工程师不自觉地囤积改动——攒了几个小功能才发一次 PR因为每次发 PR 都要经历繁琐的发布流程。这种行为会让每次合并的改动量变大review 难度增加出问题的风险也随之增加。当发布的边际成本变得接近于零工程师自然会倾向于更频繁地发布小改动。更小的批次更快的反馈循环更低的回滚风险——这才是频繁发布的真正价值所在。下一篇我们进入 gstack 并行开发的核心Git Worktrees 怎么配合 Conductor 工具实现一个工程师跑 10-15 个并行 sprint以及 Garry Tan 每天早上的工作流是什么样的。系列文章本文是 gstack 深度解析系列第 06 篇共 10 篇。参考资料gstack ship Skill 源码、document-release 实现逻辑