企业官网建设流程全解析

• 桌面应用
• 版本控制
• 开发工具

导读

GitHub Desktop（desktop/desktop）是一个以"每两周向生产环境推送一次更新"为节奏的开源桌面客户端项目。本文基于仓库中的 docs/process/release-planning.md 官方流程文档，系统讲解该项目如何用 Marketing Releases 与 Milestones 双轨组织版本、如何为功能与缺陷修复类 Pull Request 分配里程碑排期，并结合 feature-flag.ts 特性开关实现、draft-release 发布草稿脚本与 changelog.json 真实变更记录，还原一条从"打开 Issue"到"发布 Release"的完整工作流。读完本文，你将理解一套可复用的开源项目发布治理方法，并掌握 GitHub Desktop 特有的 beta/test 通道与版本号演进规则。

双轨发布体系：Marketing Releases 与 Milestones

GitHub Desktop 团队将"发布"拆分为两个互补的维度来组织：

Marketing Release 解决"这个版本要讲什么故事、带哪些大功能"的问题；Milestone 则解决"这批具体的 PR 和 Issue 什么时候合并、什么时候见用户"的问题。二者的关系在 changelog.json 中可以得到印证：同一期功能会以3.6.6、3.6.6-beta1、3.6.6-beta2等一组关联版本号呈现，正式版与预发布版共享相同的补丁号基线。

在发布节奏上，文档明确：团队目标是大约每两周向生产环境推送一次更新，以保证改进持续不断地流向用户。这意味着所有排期决策（里程碑分配、合并时机）都围绕这个两周窗口展开，任何 PR 若错过当期里程碑，通常会被顺延到下一期。

PR 排期总原则：用户可见变更必须关联 Milestone

对于任何影响用户可见行为的 Pull Request，都应当关联一个 Milestone，用来指明其预期合并时间。这条总原则把"代码何时合入"与"功能何时发布"绑定在一起，避免合并后长期积压在主干上无法随版本交付。

从源码结构看，版本与发布通道的对应关系由__RELEASE_CHANNEL__（production/beta/test）这一编译期常量驱动，feature-flag.ts 中的enableBetaFeatures()即依赖__RELEASE_CHANNEL__ === 'beta'来判断是否开放 beta 特性。这解释了为什么排期文档要求"功能类 PR 尽早挂里程碑、缺陷类 PR 延迟挂里程碑"——因为不同通道的用户看到的特性面是受控的。

功能类 PR（Features）：尽早挂里程碑，用特性开关控放量

对于与 Marketing Release 绑定的功能类 Pull Request，文档要求尽可能早地定义 Milestone，以明确预期的发布版本并便于跟踪。其背后逻辑是：大功能需要跨越多期 beta 验证，越早进入里程碑，越有机会在正式发布前走完测试与反馈循环。

功能类 PR 还必须借助Feature Flags（特性开关）来控制功能对用户可见的时机。仓库中的 docs/technical/feature-flagging.md 是这一机制的完整说明：Preview Feature（范围明确、团队已达成共识但细节待定）与Beta Feature（已排入下个版本、可用性完整但需要更多测试）两级分层，beta 特性是 preview 特性的超集。

对应的实现位于 feature-flag.ts：

function enableDevelopmentFeatures(): boolean { if (Disable) return false if (__DEV__) return true if (process.env.GITHUB_DESKTOP_PREVIEW_FEATURES === '1') return true return false } function enableBetaFeatures(): boolean { return enableDevelopmentFeatures() || __RELEASE_CHANNEL__ === 'beta' }

核心机制是运行时检查GITHUB_DESKTOP_PREVIEW_FEATURES环境变量（非开发环境下将其设为1即可开启预览特性），以及判断当前发布通道是否为 beta。每个特性对应一个独立的开关函数，例如enablePullRequestQuickView()仅由开发特性控制、enableWSLDetection()由 beta 特性控制，从而让"已合入但未对所有用户开放"成为常态——这正是排期文档中"我们可以在功能稳定后清理新/旧分支"的设计初衷。

实际使用中，用户可以通过以下方式参与提前测试：

1. 设置环境变量GITHUB_DESKTOP_PREVIEW_FEATURES=1；
2. 重启 GitHub Desktop 以让预览特性生效；
3. 需要退出时，删除该环境变量并重启即可。

此外，使用beta 通道的构建（对应 changelog 中的-betaN版本号）可以直接验证即将发布的功能并提交反馈，这些版本会在 changelog.json 中与正式版并行记录。例如3.6.6-beta1先记录了一批 Copilot 与 Electron 升级相关的变更，随后3.6.6正式版才收录面向所有用户的条目——这就是特性开关与 beta 通道协同的实证。

缺陷修复类 PR（Bugfixes）：审批通过后才分配里程碑

与功能类 PR 相反，缺陷修复或计划外工作的 Pull Request 可以尽早打开，但在评审与批准完成之前，不应分配任何 Milestone。理由如下：

• 维护者需要在 PR 生命周期中尽可能晚地讨论合并时机；
• 评审所需的时间与精力有时会超出当前里程碑的窗口；
• 过早挂里程碑会造成"承诺了却无法兑现"的排期失真。

批准该 PR 的评审者在批准的同时，可以分配一个 Milestone 来提议合并时间，并可选地在评论中补充选择理由。团队在决定里程碑时主要权衡三个因素：

这三要素实质上是在"尽快止血"与"充分验证"之间做取舍：高优先级且低风险的热修复可以立即合并；涉及面广的修复则宁可多等一个 beta 周期。

PR 合并还需经过24 小时审批窗口：合并前，其他维护者可以在窗口期内讨论提议的里程碑（或仅以 👍 表示认可）。窗口过期后，只要里程碑与当前发布对应，维护者即可执行合并。这与 docs/process/pull-requests.md 中描述的"24-Hour Cooling-Off Period"机制完全一致——它保证了跨时区的团队成员都有机会对排期提出意见。

合并时还有一个容易被忽略的配套动作：PR 描述中关联的 Issue（合并时会自动关闭）也必须分配到同一 Milestone，确保问题追踪与版本交付记录保持一致。

社区贡献（Community Contributions）：走与 Bugfix 相同的路径

社区贡献者提交的 PR 与功能/缺陷修复遵循同一套规则：在评审并批准之前不得分配 Milestone。这意味着社区 PR 与内部 PR 在排期上被一视同仁，都要先经过desktop/code-reviewers团队的评审（详见 docs/process/pull-requests.md），再进入 24 小时冷却期，最后依据当期里程碑决定合并时机。

这种"后置分配"策略对社区项目尤为重要：社区 PR 的完成度、返工轮次高度不确定，晚分配里程碑可以避免把社区工作的交付时间过早写进承诺。

从排期到落地：draft-release 脚本如何支撑发布

排期文档描述的是"人"的流程，而仓库中的 script/draft-release/run.ts 则是将排期结果落到版本号与 changelog 的自动化工具，由yarn draft-release <channel>触发（channel 可选production、beta、test，见 package.json 中draft-release脚本定义）。它的执行步骤与排期文档一一呼应：

1. 创建发布分支：基于当前分支创建形如releases/<版本号>的分支；
2. 更新应用版本号：通过npm version写入 app/package.json；
3. 生成 changelog 草稿：根据通道类型收集变更条目并写入 changelog.json；
4. 打印后续步骤：提示按 docs/process/writing-release-notes.md 修订发布说明、运行yarn draft-release:format格式化校验、提交并推送发布分支。

其中版本号的演进规则定义在 script/draft-release/version.ts，与文档中的版本体系直接对应：

• production 通道：基于最新正式版做patch递增（如1.4.0 → 1.4.1），且禁止从 beta/test 预发布版本推导正式版；
• beta 通道：若当前已是 beta 预发布版则递增 beta 序号（如1.4.1-beta1 → 1.4.1-beta2），否则先生成下一个 patch 版本再追加-beta1；
• test 通道：采用独立的-testN预发布序号递增规则，且不会猜测发布说明。

这套规则解释了为什么 changelog.json 中会同时出现3.6.6-beta1、3.6.6-beta2与3.6.6这样成组的版本记录，也印证了排期文档中"Milestone 示例为 1.4.1、1.4.2、1.5.0"这类细粒度编号的由来——它们本质上是 SemVer 语义下的 patch 与 prerelease 组合。

相邻流程：让发布说明与排期无缝衔接

一个版本能否顺利发布，还依赖两套相邻的文档化流程：

• docs/process/writing-release-notes.md：定义了 changelog 条目的写作规范。每条发布说明采用[Tag] 描述 - #issue编号的结构，Tag 按[New]、[Added]、[Fixed]、[Improved]、[Removed]五种分类排序；描述必须面向用户影响而非技术实现（例如写[Fixed] Keep PR badge on top of progress bar - #8622，而不是描述 z-index 的修改），并尽量使用现在时。yarn draft-release生成的草稿只是起点，最终文本需人工按此规范修订。
• docs/process/pull-requests.md：规定了 PR 从打开、评审到合并的完整流程，其中的 24 小时冷却期与排期文档中的 24 小时审批窗口互为印证。

小结：一套闭环的版本治理实践

回顾整个机制，GitHub Desktop 的发布排期可以概括为一条闭环链路：

1. 规划：用 Marketing Release 定义功能叙事，用 Milestone 承载具体交付；
2. 排期：功能类 PR 尽早挂里程碑并依靠特性开关受控放量，缺陷类 PR 审批通过后再依据优先级、影响面与时机三要素分配里程碑；
3. 审批：经过 24 小时冷却期，跨时区维护者共同确认合并时机；
4. 发布：yarn draft-release按通道规则推导版本号、生成 changelog 草稿，再经人工修订后发布；
5. 验证：beta 通道用户先行验证，正式版两周一个节奏持续交付。

这套流程的核心思想，是用"里程碑后置分配 + 特性开关"两个机制，把"代码合并"与"用户可见"彻底解耦，从而在保持两周一次稳定交付的同时，为每个变更争取到充分的评审与验证时间。对于任何希望建立可持续发布节奏的开源项目，这都是一份极具参考价值的工程实践样本。

• 桌面应用
• 版本控制
• 开发工具