1

我正在开发一个软件项目，该项目在同一个git存储库中维护源代码以及随附的用户手册（包括教程和参考资料等）。用户手册是使用DocBook编写的。

存储库对于不同的发布分支有不同的分支。例如，我们有一个“主要”分支，可以向其提交功能并从中创建下一个主要版本。我们还有一个“次要”分支，只能提交错误修正，并从中制作下一个次要版本。次要分支经常合并到主要分支中，以确保所有已完成的错误修复也最终出现在下一个主要版本中（这样我们就不会在例如 v1.3 和 v2 之间出现回归）。

我看到的问题是，由于主要分支和次要分支之间的软件不同（主要包含新功能），因此文档也不同（主要分支中的文档可能已在某些地方重写以提及新特征）。在将“次要”合并为“主要”时，这会不时导致 DocBook 源中的冲突，因为分支之间的单行不同。ChangeLog对于其他文档文件（如文件）来说，这实际上是正确的。

我最近开始想知道如何改善这一点。我的想法包括：

  1. 只需要一个版本的主要分支和次要分支的手册。对于特定版本的功能，明确地说“从软件的 v2 开始，你也可以做 XYZ”。
  2. 将文档文件移动到专用的 git 存储库中。当将存储库的“次要”分支合并到“主要”分支时，这仍然会导致冲突，但至少所有处理源代码的软件开发人员都看不到（并因此而烦恼）冲突。
  3. 使用专用的 git 存储库并将它们作为git 子模块嵌入到原始存储库中。我不太确定这会给我带来什么，但我听说使用这样的子模块有点痛苦，因为我最终会一直更新要从外部存储库中提取的参考提交。

我想知道 - 其他人如何处理这种将源代码和文档保持在一起的情况？请注意，我在这里谈论的不是 API 文档（可以从源代码自动生成），而是简单的、手动编写的英文文本。

4

1 回答 1

4

我相信“选项 3”（子模块）仍然是最不烦人的，因为它：

  • 解耦这两组文件（您不需要最新版本的文档来编译和运行您的项目）
  • 大多数 git 命令现在都是“子模块感知的”（或者相反，可以忽略它们git status）
  • 您可以随时更新子模块（不必“一直”）
  • 您将通过父仓库保持源代码和文档之间的链接。

话虽如此，我没有看到一个简单的解决方案来管理文本文件中的并行演变。冲突仍将存在。

于 2011-01-20T12:52:56.100 回答