git 获取 github

我们在OpenStack中广泛使用git作为文档，以便我们可以“像对待代码一样对待文档” —而且我在很多地方都看到了这种趋势，尤其是在社区中。

请查看2014年在波特兰举办的Docs活动中的这些演讲：

在OpenStack中，我们有模仿我们的代码协作的文档工作流。 我们发布供人查看的补丁程序，审查彼此的补丁程序（类似于GitHub上的请求请求），并且为每个文档补丁程序构建和测试自动化。 这个想法是，使用GitHub pull request工作流程中存在的协作来处理文档和代码。 我们全都负责在130个git存储库中使用Python编写的约25个OpenStack项目的相关且准确的文档，因此让我们进行协作。 我确实从开始使用这些类型的工作流的作家那里收到一些问题，所以我想将我们发现的一些最佳实践结合在一起，并找到更多的最佳实践。

您如何处理许多对文档的请求请求？

OpenStack是一个 ，因此该文档需要扩展以适应许多贡献者和贡献者。 我们拥有的系统每天可以合并多达50个文档补丁，尽管通常大约是15个。由于OpenStack使用 ，因此我的一些技巧是针对该基于Web的团队软件代码查看工具而非GitHub的。 但是，这些是应该普遍适用的准则。 我也强烈建议“ ”，该报告提供了调查结果，并提出了有关集成商如何使用请求请求作为其他阅读的主题。

我们使用以下工具和流程处理许多补丁请求（在OpenStack中，从技术上讲，它们不是请求请求）：

如果我缺少您最喜欢的助手，请在下面评论！

门测试：机器人助手

我们拥有“门测试”，可以自动执行许多初步质量检查，以检查社区做出的任何贡献。 我们的登机口测试检查以下内容：

1. “此补丁中的文档是否生成？”
2. “所有修补文件中的语法正确吗？”
3. “所有链接都有效吗？”
4. “补丁程序会删除其他可交付成果使用的任何文件吗？”

必须通过这四个测试才能完全合并，因此它们是我们真正的看门人。 为了提高效率，这些测试仅在与补丁相关的情况下运行。 因此，如果补丁中没有删除任何文件，则不会运行删除测试。 这样可以节省人员将补丁带到本地并手动运行测试的时间。 还有其他测试报告，但实际上并没有阻止补丁通过，例如“翻译是否仍适用于此补丁？” 文档的持续集成（CI）改变了游戏规则。 我认为我不足以强调这一点，但是这篇文章的重点是扩展文档审查。 如果您想了解有关OpenStack CI系统的更多信息，请访问 。

技术准确性：人工检查

测试补丁的技术准确性是耗时的部分，并且很难预测在文档审阅中将花费的时间。 人工仔细检查对文档做出的任何贡献的技术准确性至关重要，我们在此依靠我们的审阅者。 设置可让您测试用户操作的环境是审阅者的一部分，并且可以节省您的时间。 DevStack是用于运行已配置开发环境的脚本的集合，已调整为本地设置。 TryStack是使用捐赠的硬件和资源运行的免费公共云。 例如，如果我有一个基于OpenStack稳定分支的有效DevStack环境，则可以针对已知版本的OpenStack运行客户端命令。 我可以对自己运行的DevStack环境具有管理员访问权限。 我还有一个TryStack帐户，该帐户可通过CLI或API命令为我提供免费的云资源。 我还有一个Rackspace Cloud帐户，可让我测试API调用。

提交消息中的错误链接

我们有一个快捷系统，供贡献者在提交消息中放入“ Closes-bug：nnnnnn”之类的短语，其中nnnnnn来自启动板系统（我们的错误跟踪器）。 doc错误与贡献本身之间的这种联系对于查看修补程序是否解决了已记录的bug的问题很方便。 我通常会通过以下方式来查看补丁程序：首先单击该错误，通读注释，然后查看该补丁程序是否修复了已损坏的内容。 您还希望确保您的过程确保贡献者知道是否将错误视为错误。 在我们的系统中，必须将其设置为“已确认”。 在GitHub中，您需要在问题上使用标签，还需要从拉取请求中链接到问题。

提交消息标准

在OpenStack中，我们一天可以合并多达70个补丁（仅适用于文档），因此使扫描变得更加容易，以查找您可以利用基础知识进行审查的补丁。 似乎很挑剔，但了解一天可以看50则有助于理解挑剔的理由。 以下是我们标准的摘要：

• 在第一行中提供更改的简短描述。
• 在第一行之后插入一个空白行。
• 在以下各行中提供有关更改的详细说明，并在需要的地方断开段落。
• 第一行应限制为50个字符，并且不应以句号结尾（超过72个字符的提交消息将被门拒绝）。
• 随后的行应以72个字符换行。

约定

所有审阅者都知道我们使用了一组 ，并且在审阅补丁时可以指向这些 。 这套标准有助于我们检查服务的命名是否一致，出于法律目的的大写形式以及诸如“无堆叠头”之类的结构约定。 我们将这些内容发布在OpenStack Wiki上，所有更改之前，所有更改都将在openstack-docs邮件列表中进行讨论。 当Wiki页面没有解决问题时，我们将在任何样式或约定问题中使用IBM样式指南作为最终仲裁者。

所有公开评论的信息中心

使用Gerrit，我们可以对相关补丁进行特定搜索以进行审查。 例如，我已经创建了一个 （链接需要登录）。 您还可以拥有一个仪表板，仅用于影响API的补丁程序。 真正具有搜索功能，您可以定制仪表板以查看所需内容并根据需要确定优先级。

提醒您进行评论的日历项目

我们的日历上有很多会议，因此最好预留时间进行审核。 有时人们想在工作结束时进行检查，或者首先要做的是完成大量工作。 真正由您决定在工作日内对审核进行优先排序。 我将日历项目用作提醒，并加紧了评论时间。

审核的预计周转时间是多少？

确实，这取决于补丁程序或请求请求的大小，加上知道足以审查该补丁程序的审阅者数量。 我们使用数据分析来衡量OpenStack评论的周转时间。 在过去的五个月左右的时间里，我们已经完成了对评论的这类调整。

• 总评价： 2102 （每天70.1）
• 审稿总数： 113 （每名审稿人每天0.6）
• 核心团队评论总数： 1570 （每天52.3）
• 核心团队人数： 21 （每天每核心2.5）

坦白地说，我们有一位超人的审阅者（Andreas Jaeger），我们活跃的核心团队规模是15而不是21。在OpenStack中，核心审阅者是可以发布到网站的人。 任何人都可以查看文档补丁。 我想每天至少接受2到10条评论。 在一个不错的点评周中，我可以获得大约60条评论。 因此，我对我们的文档贡献者的期望约为3-5天，以便获得评论者可以解决的评论。

摘要

编写者可能会犹豫与他人合作以交付成果，而开发人员可能会觉得他们对文档没有什么贡献。 我断言没有人能一无所知，因此就像在代码上一起协作一样，通过一起编写来分配工作量。 希望这些技巧能帮助您将docs工作流程与git和GitHub工作流程进行匹配，从而加快协作写作的速度，尤其是在开放源代码中。

翻译自:

git 获取 github