审查 DocImpact¶
https://blueprints.launchpad.net/openstack-manuals/+spec/review-docimpact
`DocImpact` 脚本在 openstack-manuals bug 列表中产生了很多噪音。这部分是一个社会问题（我们需要培训贡献者更周到地使用 `DocImpact` 标记），另一部分是一个自动化问题（我们应该考虑如何使用 `DocImpact` 标记，以及实现我们所需结果的最有效自动化方式）。
问题描述¶
当前流程：贡献者创建补丁，并在提交时想“哦，对了，可能需要一些文档来描述这个”然后加上一个 `DocImpact` 标记。换句话说，这里没有经过太多思考，只是一个容易做的事情，他们感到很舒服，并且假设文档精灵会过来处理这些事情。实际上，接下来发生的是，一些文档分拣员花费一个小时查看补丁，搜索文档，然后决定它与 openstack-manuals 无关。通常，实际的文档影响（如果存在的话）是针对 dev 仓库中的文档，而不是 openstack-manuals。
简而言之，贡献者意识到他们需要文档，而 `DocImpact` 是一种让他们感觉正在做一些有成效的事情的方式。然而，实际情况是，这些 bug 对于 openstack-manuals 来说在很大程度上是不相关的，这给我们的核心团队带来了有效处理它们的压力。为了尝试了解问题的规模，以下是一些数据
在 508 个当前的 openstack-manuals bug 中，214 个是 `DocImpact` 脚本的结果。其中 51 个尚未分拣。目前，有 170 个带有 DocImpact 标签的补丁正在处理中。显而易见，如果它们全部提交，那么我们的队列中将有 170 个新的 bug。
提议的变更¶
- 调整 `
DocImpact`，使其无法在没有描述的情况下使用。目前，这是一个贡献者可以随意选择的事情，但似乎没有人使用它。这意味着，贡献者不能仅仅输入“DocImpact”然后继续他们的生活，他们必须写“DocImpact：这里有一些相关内容”。 - 一个 Jenkins 作业用于测试补丁中的描述字段。如果没有找到描述字段，Jenkins 作业将失败。
- 目前，所有项目默认在 openstack-manuals 队列中创建一个 bug。这种行为将被更改，以便所有项目默认在自己的仓库中引发 bug，只有五个 defcore 项目（Nova、Swift、Glance、Keystone 和 Cinder）会进入 openstack-manuals 队列。（Neutron 将在成为 defcore 后添加，计划于 2016 年）。
- 在 dev 邮件列表中，以及可能的其他渠道，发起一项教育活动，以尝试鼓励贡献者负责任地使用该标记。
示例¶
正确使用 `DocImpact` 的一些示例
需要更新文档的位置
DocImpact: Update in the Networking section of the Ubuntu Install Guide所需的文档类型
DocImpact: Add a description and install info for $NEW_FEATURE.对现有文档的更改
DocImpact: Current docs say X, should be Y.指向更长篇幅文档的链接（例如 OpenStack pastebin、etherpad 或博客文章）
DocImpact: For more info, see http://paste.openstack.org/show/479079/
备选方案¶
- 组织一支由文档专家组成的精干团队（可能借助自动化），遍历 `
DocImpact` bug，抄送原始补丁作者，分拣有效的 bug，将其他 bug 移动到 dev 仓库（如果需要），并标记其余的为无效。我们可以将此与 dev 邮件列表上的教育活动结合起来。 - 放弃 `
DocImpact`，并强制贡献者创建他们自己的文档 bug（和补丁）。这意味着更少的贡献者会参与文档工作，但至少我们得到的内容会经过深思熟虑，而不是匆忙地添加到他们的提交消息中。 - `
DocImpact` 根本不记录 bug，而是表明补丁包含文档。这种提交消息风格与 APIImpact 一致，API 工作组会审查带有该标签的传入补丁。目前这行不通，因为我们没有一个好的机制来搜索该标记（当前的文档仪表板不支持此功能）。 - 什么都不做。保持 `
DocImpact` 标记的原样，然后慢慢沉沦。
除非另有说明，本文档根据 知识共享署名 3.0 许可协议 授权。请参阅所有 OpenStack 法律文件。