大型项目中 SVN 仓库结构设计：trunk、branches、tags 的规范用法

在中小型项目里，SVN 仓库结构往往很随意——有人直接往根目录提交，有人把分支当文件夹用，标签更是随手复制一份了事。但当项目规模扩大到几十人协作、多个版本并行维护、频繁发布补丁时，这种随意性就会带来灾难性的后果：合并冲突频发、版本追溯困难、发布产物无法复现。要解决这些问题，必须从仓库结构设计入手，严格区分 trunk、branches、tags 的职责，并配套相应的操作规范。

一、标准目录布局：不只是“三个文件夹”

SVN 官方推荐的标准布局是：

/trunk
/branches
/tags

很多人以为这只是约定俗成的目录命名，实际上它对应着三种完全不同的生命周期管理策略：

• trunk：主线开发区域，存放当前正在开发的下一个版本代码。所有日常提交、功能开发、缺陷修复默认都进入 trunk。
• branches：并行开发区域，用于特性开发、版本维护、实验性重构等需要与主线隔离的工作。
• tags：只读快照区域，用于标记发布版本、里程碑节点。一旦创建，就不应再修改。

关键原则是：trunk 是流动的，branches 是并行的，tags 是冻结的。三者不能混用——比如不能直接在 tags 下修改代码，也不能把 branches 当成长期开发的主线。

二、trunk 的使用规范

trunk 是项目的“事实来源”。在大型项目中，trunk 必须始终保持可构建、可测试、可发布的状态。为此需要遵守以下规范：

1. 提交粒度要小且完整。每次提交应完成一个逻辑单元，避免“半成品”提交。如果某个功能需要多天开发，应放到 branches 中，而不是在 trunk 上“边写边提交”。
2. 提交前必须通过本地构建和单元测试。大型项目通常配置持续集成（CI）监控 trunk，任何破坏构建的提交都会阻塞整个团队。
3. 禁止在 trunk 上直接打标签。发布时必须从 trunk（或维护分支）复制到 tags，而不是在 trunk 上做标记。
4. trunk 的版本号应始终指向下一个开发版本。例如当前发布 2.3.0 后，trunk 应更新为 2.4.0-SNAPSHOT（或类似标识）。

一个常见的反模式是：团队在 trunk 上开发新功能的同时，又直接在 trunk 上修复线上紧急 bug，然后从 trunk 发布补丁。这会导致新功能代码被意外带入补丁版本。正确做法是：从发布标签创建维护分支，在维护分支上修复，再合并回 trunk。

三、branches 的分类与命名规范

大型项目中，branches 目录下往往同时存在多种类型的分支。如果不加区分地命名，很快就会变成一团乱麻。建议按用途分类并采用统一命名前缀：

• feature/：特性开发分支，如 feature/user-authentication。生命周期短，完成后合并回 trunk 并删除。
• release/：发布准备分支，如 release/2.3.0。用于发布前的回归测试、版本号更新、文档完善。发布完成后打标签并删除。
• hotfix/：紧急修复分支，如 hotfix/2.3.1。从发布标签创建，修复后同时合并回 trunk 和 release 分支（如有）。
• maintenance/ 或 support/：长期维护分支，如 maintenance/2.2.x。用于为旧版本提供长期支持，只接受缺陷修复，不接受新功能。
• experiment/：实验性分支，如 experiment/new-architecture。允许失败，不承诺合并。

命名规范的核心是可读性和可追溯性。看到分支名就能知道它的用途、目标版本和创建者意图。建议在分支创建时，在分支根目录下放置一个 BRANCH_INFO.md 文件，说明分支目的、负责人、预期合并时间。

另一个重要规范是：分支创建后要尽快合并或删除。长期存在的特性分支会与 trunk 产生巨大差异，合并时冲突难以解决。建议特性分支生命周期不超过两周，超过则考虑拆分或重新评估。

四、tags 的创建与管理

tags 是发布管理的基石。在大型项目中，tags 的规范使用直接关系到版本追溯和回滚能力。

1. tags 必须从正确的源创建。发布标签应从 release 分支或 trunk 创建，hotfix 标签应从 hotfix 分支创建。禁止从工作副本直接复制。
2. tags 命名要包含完整版本号。推荐 v2.3.0、v2.3.1 或 2.3.0-release。避免使用 latest、stable 这类含义模糊的名称。
3. tags 创建后立即锁定。可以通过 SVN 的 pre-commit 钩子禁止对 tags 目录的修改。如果确实需要修正标签，应删除后重新创建，而不是直接编辑。
4. tags 应附带发布说明。可以在标签目录下放置 RELEASE_NOTES.md，记录本次发布包含的变更、已知问题、升级步骤。

一个常见的误区是“标签只是复制一份代码”。实际上，标签还应该包含构建产物、依赖清单、数据库迁移脚本等发布所需的一切。这样当需要回滚或复现历史版本时，不需要再去猜测当时的依赖版本。

五、分支合并策略与冲突预防

大型项目中，合并是最大的痛点。规范的做法是：

• 从 trunk 合并到分支要频繁。特性分支应定期（至少每天）将 trunk 的最新变更合并进来，避免差异累积。
• 从分支合并回 trunk 要完整。合并时使用 svn merge --reintegrate（SVN 1.8+ 使用 --reintegrate 或自动 reintegrate），确保分支的所有变更都进入 trunk。
• 合并前先更新工作副本。svn update 到最新版本，解决冲突后再提交。
• 记录合并信息。在提交日志中注明合并的来源分支和范围，例如 Merged from branches/feature/user-auth (r1234:r1289)。

为了预防冲突，还可以在仓库层面设置钩子，禁止对特定目录的随意提交，强制提交日志格式，甚至集成代码审查工具（如 Review Board）后再允许合并。

六、权限与钩子：让规范落地

再好的规范，如果没有工具强制，最终都会形同虚设。在大型项目中，建议配置以下 SVN 钩子：

• pre-commit：检查提交日志格式、禁止修改 tags、禁止在 trunk 上提交未通过 CI 的代码。
• post-commit：触发 CI 构建、发送通知邮件、更新任务跟踪系统。
• pre-revprop-change：禁止修改提交日志（除非有特殊权限）。

权限方面，建议按目录分配：trunk 对开发人员开放提交权限；branches 按分支负责人分配；tags 只允许发布经理写入。

结语

SVN 仓库结构设计不是一次性任务，而是需要持续维护的工程实践。trunk、branches、tags 的规范用法，本质上是将“开发—隔离—发布”三个环节在版本控制层面显式化。在大型项目中，这套规范能显著降低协作成本、提高发布可靠性、简化问题追溯。投入时间建立并执行这些规范，远比事后修复混乱的仓库结构要划算得多。

未经允许不得转载：任鹏个人博客 » 大型项目中 SVN 仓库结构设计：trunk、branches、tags 的规范用法