Documentation/DocImpact

在提交消息中使用 DocImpact 标记

在任何 OpenStack 项目中，您可以在提交消息中添加 DocImpact 标记，以自动在 Launchpad 中记录指定项目的 bug。该 bug 在补丁合并之前不会设置为“已确认”。整个提交消息都包含在 bug 中。

这种方法提供了补丁对文档可能产生的影响的通知和跟踪。如果您的提交可能对文档产生影响——无论是添加/更改/删除命令行选项、弃用或新增功能、注意事项，还是您在补丁中编写了文档，或者您只是不确定，只需在您的提交消息中添加一行“DocImpact”即可。

这将在 openstack/project-config 仓库中的 gerrit/projects.yaml 文件中指示的项目中创建一个 Launchpad bug。这并不能保证会编写文档，但提供了对变更的可视性和跟踪。您也可以将其用作提醒，以便稍后为该功能编写文档，或者提醒自己找到一位作者为您编写文档。考虑到有超过 2000 名代码贡献者和少数几位文档编写者，总是有需要完成的文档工作。

如果您是文档贡献者，当 DocImpact 通知发送到列表时，我们将采取以下步骤。

1. 在 openstack-manuals 或 openstack-api-site 中创建一个新的文档 bug。在 bug 中

在标题中，根据补丁将要合并到的发布版本，放入“grizzly”或“havana”。
将 review.openstack.org 链接复制并粘贴到 bug 描述中。
在 bug 描述中描述如果代码补丁合并后受影响的文档。
在代码补丁合并之前，将文档 bug 状态设置为“New”。

2. 继续检查补丁，并在合并后将状态更改为“Confirmed”。

3. 使用“文档 Bug 分类指南”部分中的信息，在合并后设置优先级。

为 DocImpact 编写良好的提交消息

由于整个提交消息都包含在记录的 bug 中，因此请尝试在提交消息中包含尽可能多的信息，关于哪些文档受众受到变更或增强的影响，变更是什么，为什么它很重要，等等。

谁会使用该功能？
为什么使用该功能？
该功能的具体用法是什么？如果是 API 变更，请提供示例请求和响应。
该功能是否还附带权限/策略？如果是，要求是什么？

如果它是配置选项的更改，我们的自动化将捕获它，但我们仍然希望有一个 bug 来跟踪。如果它是 CLI 更改，我们也有自动化可以捕获帮助文本，但额外的用法信息很有用。阅读一个示例演练或查看一个现有的记录了 DocImpact 的 bug，该 bug 需要进一步分类以获取更多信息。

第三方 DocImpact 设置

默认情况下，DocImpact 标记使用仓库名称作为 Launchpad 中的项目来创建 bug。要更改此行为，可以使用 projects.yaml 中的 docimpact-group 选项。例如，如果您这样设置项目：

- project: stackforge/project-name
  description: Latest and greatest cloud stuff.
  upstream: git://github.com/awesumsauce/project-name.git
  docimpact-group: Project

文档 bug 将在 http://launchpad.net/Project 中创建