2

背景

我来自硬件开发工程背景。我们的详细规范在文档（通常是 MS Word）的结尾或开头以表格形式包含修订历史记录。这些规范保存在一个文档管理系统中，该系统与用于存储硬件设计交付物（例如原理图和电路板布局文件）的管理系统分开。有时文档管理系统不用于规范，而是文件名包含文档修订号。考虑到有人会开始修改带有下级修订的文档，这总是感觉像是一个次优的解决方案。

问题

我已经开始研究一个使用 DVCS (Git) 的软件项目，并计划使用 Markdown 将规范/文档编写为文本文件，而不是 MS Word 文档。我喜欢在 DVCS 中包含所有内容的想法，包括规范和用户文档。但是，规范和文档似乎不应该与实际代码存储在同一个存储库中。这引出了我的问题：

  1. 规范/文档是否应该与代码存储在单独的存储库中？
  2. 每个规范/文档是否应该有一个单独的存储库？
  3. 鉴于 DVCS 提供了拥有修订历史的能力，软件工程师/编码人员通常会在他们的规范和文档中添加修订历史吗？
4

2 回答 2

2

  1. 不要以某种不广泛使用的晦涩格式存储规范。该工具不应规定文档的形式。这些文件可能需要由您小组以外的仅熟悉单词的人使用。

  2. 是的，规范/文档应该存储在与代码不同的存储库中。管理代码存储库与文档存储库有不同的要求。您可以在文档存储库中使用相同的并行组织结构（即相同的项目名称、层次结构等），这样可以很容易地找到相关文档。

  3. 每个规范/文档不应该有一个单独的存储库。组织应反映代码存储库的组织。每个项目中的每个代码文件都有单独的存储库吗？

  4. 是的，无论存储库如何，都将修订历史记录放在规范/文档中是很常见的。文档可能需要跨组织使用，组织外部的人可能无法访问源代码控制，但可能仍需要进行更改（组织中的某个人可以管理/签入）。

更常见的是，这些文档通常需要在不同的公司部门中使用（即由无权访问/不熟悉存储库的 UI 团队、销售、营销人员审查）。

于 2009-12-27T15:01:24.423 回答
0

在企业界，1. 和 2. 取决于您的存储库处理创建/访问/批准文档和代码所需的安全模型的能力。对于 3. 适用时，您应始终在文档中包含修订背后的深入推理。

于 2009-12-27T14:50:41.873 回答