文档错误

文档团队通过错误跟踪部分工作。本节包含文档错误的详细概述。

文档团队使用以下项目来跟踪由文档项目或其子团队管理的仓库的文档错误

项目特定仓库的文档错误在 Launchpad 上相应项目的错误跟踪区域中跟踪。

OpenStack 项目也可能使用 StoryBoard 来跟踪涉及文档的跨项目任务。有关更多信息，请参阅 处理文档故事。

最后，OpenStack 开发人员可以使用 DocImpact 标志来帮助识别 openstack-manuals 仓库中需要文档更新的错误。

提交错误

错误因以下因素而异

  • 提交方式

    • 手动

    • 自动（通过 DocImpact 标志）

  • 所需的更改

    • 修复拼写错误或格式

    • 更新现有内容

    • 添加新内容

重要提示

不要提交有关故障排除问题的错误。如果您在使用环境时遇到问题，并且正在遵循安装教程，请通过 IRC、Stack Overflow 或 OpenStack 邮件列表寻求相关团队和运维专家的帮助。

有关相关 IRC 频道的更多信息，请参阅 OpenStack IRC wiki。

有关 OpenStack 邮件列表的更多信息，请参阅 Mailing lists wiki。

只有在发现文档本身不正确时，才应提交错误。

处理文档错误

在错误设置为“已确认”之前，不要处理文档错误。理想情况下，除了提交者之外的其他人会确认该错误。一旦补丁中的更改完成，它们就会像其他 OpenStack 代码一样被审查和批准。

要获取文档错误或将错误标记为与文档相关，请访问 来自所有 OpenStack 项目的文档错误聚合列表。

处理文档故事

OpenStack 项目可能使用 StoryBoard 来跟踪跨项目任务。当这些任务涉及文档时，应在 StoryBoard 中将这些任务标记为文档相关，从而允许您查看 来自所有 OpenStack 项目的文档故事聚合列表。

对 openstack-manuals 进行错误分类

以下部分详细介绍了错误分类联络员的角色以及 openstack-manuals 仓库的错误分类流程和指南。

项目特定的仓库遵循其各自团队的错误分类流程和指南。

错误分类联络员

文档团队指定错误分类联络员，以确保对 openstack-manuals 仓库报告的所有错误都能及时进行分类。

如果您有兴趣担任错误分类联络员，您需要遵循几个步骤才能做好准备。

注意

完整阅读此页面。始终牢记本文档，因为它描述了联络员的职责以及如何分类错误。特别是，它描述了如何设置错误重要性以及如何选择错误标签。

  1. 在开始处理文档错误之前，您必须加入 Launchpad 上的 openstack-doc-bugs 团队。有关更多信息，请参阅 新手。

  2. 如果您尚未这样做，请注册 Launchpad 上的 openstack-manuals 邮件。

    1. 导航到 Launchpad openstack-manuals 错误列表。

    2. 单击右侧的 订阅错误邮件。

    3. 在显示的弹出窗口中，将接收者保留为 您自己，并为您的订阅指定一个有用的名称，例如 文档错误。您可以选择任何选项或接收多少邮件，但请记住，接收所有更改的邮件 - 虽然信息丰富 - 至少会每天产生数十封电子邮件。

  3. 在文档团队会议过程中，当请求担任错误代理的志愿者时，请报名参加。

    或者，使用 #openstack-doc IRC 频道或 openstack-discuss@lists.openstack.org 邮件列表联系文档核心团队成员。

  4. 通过在 Bug Triage Team 页面上的错误分类时间表上添加您的姓名来注册为志愿者。

  5. 在您作为联络员的计划时间内，如果您的时区可行，请计划参加文档团队会议。这样，如果您有任何 CRITICAL 或 HIGH 错误，就可以与团队一起解决它们。

错误分类流程

错误分类流程包括以下步骤

  • 检查错误是否提交到正确的组件（项目）。如果不是，请更改项目或将其标记为 Invalid。例如，如果错误影响项目特定的 dev-ref，则将其标记为 Invalid。如果错误报告在 nova 安装指南中，请确保删除 openstack-manuals，并添加 nova 项目。

  • 如果报告的错误影响 ReST API、工具、openstackdocstheme 或安全指南，请将相关项目添加到受影响的项目中，并删除 openstack-manuals。例如，如果错误影响 ReST API，请在 openstack-api-site 中提交错误，并删除 openstack-manuals。

  • 为适当的指南标记错误。例如，对于 image-guide，如果它仅影响 openstack-manuals，则删除 glance，并标记 image-guide。

  • 如果这是一个支持请求或故障排除请求，请将错误设置为 Invalid。

  • 检查是否之前已提交了类似的错误。您还可以检查已验证的错误，以查看是否已报告该错误。如果是这样，请将其标记为先前错误的重复项。

  • 通过检查是否遵循了指南或清单来验证错误是否符合良好错误报告的要求。

  • 如果问题清晰，则省略的信息是可以接受的。运用您的判断力和经验，如有疑问，请咨询其他核心成员或 PTL。

文档错误分类指南

错误分类是审查新错误、验证错误是否有效以及收集有关错误更多信息的流程。在分类之前，所有新错误的状态均为 New，重要性为 Undecided。以下是任何错误的状态和重要性列中可用选项的定义。

状态

  • New - 最近由非分类人员记录。

  • Incomplete - 在可以进行分类之前需要更多信息。

  • Opinion - 不适合该项目，但仍可以讨论。

  • Invalid - 不是文档问题。

  • Won’t Fix - 文档修复无法解决问题。

  • Confirmed - 确认这是一个文档错误。

  • Triaged - 错误中的评论指示其范围和需要完成的工作量。

  • In Progress - 有人在处理它。

  • Fix Committed - 修复已在仓库中；Gerrit 会自动设置此项。不要手动设置此项。

  • Fix Released - 修复已发布到站点。

注意

由于所有文档都直接发布到 docs.openstack.org，因此“Fix Committed”状态已弃用。如果补丁包含行“Closes-Bug: #12345”（有关详细信息，请参阅 git 提交消息），我们的 CI 基础设施会在补丁合并后自动将错误设置为“Fix Released”。

重要性

  • Critical - 如果此错误仍然存在，数据将丢失；或者它非常糟糕，以至于修复它比处理所有传入的关于它的问题更好。网站上阻止访问的项目也是关键文档错误。

  • High - 绝对需要有关此的文档或对当前文档的修复；如果没有此文档，文档将是不完整的。如果可能，首先处理这些文档。

  • Medium - 需要在六个月的发布时间范围内有关此的文档。

  • Low - 没有此文档也可以，但可以通过修复此错误来增强文档。

  • Wishlist - 实际上不是一个错误，但是一个受欢迎的更改。如果文档有错误，请将错误标记为 Low，而不是 Wishlist。

  • Undecided - 最近由非分类人员记录或需要在决定其重要性之前进行更多研究。

文档错误的标签

根据错误影响的区域，它有一个或多个标签。例如

  • low-hanging-fruit 用于易于修复的文档错误。如果您是新手，这是开始的一种方式。

  • install-guide、image-guide 等用于特定指南。

  • infra、theme 用于文档构建工具链中的文档错误。

按标签跟踪错误

如果您需要定期跟踪与特定标签相关的活动，可以通过访问 Launchpad 项目的订阅页面 来设置电子邮件订阅

  1. 选择 添加订阅。

  2. 选择接收影响项目的邮件的选项 以任何方式添加或更改。

  3. 选中 错误必须匹配此过滤器 复选框。

  4. 选择 标签 子部分。

  5. 填写您要跟踪的标签。

  6. 创建订阅。

第三方驱动程序的错误

注意

从 Pike 版本开始，此文档已移动到项目特定的仓库，此选项不再需要。

用于更新配置参考表的错误使用标签 autogenerate-config-docs。

对于特定部分更新或添加新驱动程序，请遵循规范 Proprietary driver docs in openstack-manuals 并将错误分配给 Vendor driver page 上提到的联系人。如果这是一个没有文档的新驱动程序，请将错误分配给触发错误报告的更改的提交者，将其标记为 Wishlist，并要求提交者阅读并遵循规范并处理它，因为文档团队不会记录第三方驱动程序。