如何使用git正确管理源代码和附带的文档？

Question

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

存储库针对不同的发布分支具有不同的分支。例如，我们有一个“主要”分支，可以提交功能，并从中创建下一个主要版本。我们还有一个“次要”分支，只有错误修正可以提交，并从中进行下一个次要发布。次要分支经常合并到主要分支，以确保所有已完成的错误修正也会在下一个主要版本中结束（这样我们就不会在例如v1.3和v2之间进行回归）。 / p>

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

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

1. 主要分支和次要分支都有一个版本的手册。对于特定于版本的功能，请明确说出“从软件的v2开始，您也可以执行XYZ”。
2. 将文档文件移动到专用的git存储库中。当将存储库的“次要”分支合并为“主要”时，这仍然会导致冲突，但至少所有使用源代码的软件开发人员都没有看到（并且被这些冲突所困扰）。
3. 使用专用的git存储库并将它们作为git submodules嵌入到原始存储库中。我不太清楚这会给我带来什么，但我听说使用像这样的子模块有点痛苦，因为我最终会更新引用提交以便一直从外部存储库中提取。

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

Answer 1

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

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

话虽这么说，我看不到用于管理文本文件中的并行演进的简单解决方案。冲突仍将存在。