OpenStack 手册项目迁移

更新日期：2018-12-06 13:55

OpenStack 手册项目迁移

问题描述

文档团队正在迅速失去关键贡献者和核心评审人员。我们并非孤例，这种情况在各个方面都在发生。这使得事情变得更加困难，但并非不可能。自 2010 年成立以来，我们一直在不断攀登，努力实现最佳文档并保持我们的高标准。然而，现在我们需要退一步，认识到我们试图维护的工作量超出了我们团队的规模。目前我们有 13 名核心成员，其中没有全职贡献者或评审人员。

直到目前为止，文档团队拥有包含与多个项目相关内容的手册，包括安装指南、管理员指南、配置指南、网络指南和安全指南。由于团队不再具备拥有这些内容的能力，我们希望倒转文档团队和项目团队之间的关系，以便我们成为联络员，帮助维护，而不是要求项目团队提供联络员来帮助内容。作为这一变化的一部分，我们计划将现有内容从中央手册仓库迁移到由适当的项目团队拥有的仓库中。项目团队将拥有内容，文档团队将通过管理构建工具、帮助编写指南和风格来提供协助，但不编写大部分文本。

我们目前已经建立了基础设施，使项目团队能够管理自己仓库中的文档，并且许多团队都在这样做。作为这一变化的一部分，安装指南和管理员指南的现有内容也将迁移到项目拥有的仓库中。

提议的变更

将给定仓库的所有文档构建合并在一起，以便每个仓库都有一个单独的 doc/source 目录、一个单独的 sphinx conf.py，以及一个用于构建和发布内容（包括开发者、贡献者和用户文档）的作业。这个选项将减少我们需要运行的构建作业数量，并减少每个仓库中单独的 sphinx 配置数量。

将 openstack-manuals 中的各种指南的大部分内容移动到与被记录的事物相同的仓库中——文档应该与代码一起存在。例如，glance 的安装说明移动到 glance 仓库，使用 glance 客户端命令行工具的参考资料移动到 python-glanceclient 仓库。

为了方便从 docs.openstack.org 上的登陆页面包含链接，我们需要确保文档目录的组织结构具有最低限度的一致性。这些部分基于现有的高级分组，这些分组已经在 docs.openstack.org 上有登陆页面，这些页面需要更新。在每个顶层目录中，项目团队可以自由地组织他们的内容，只要他们认为最合适即可。这是第一阶段的建议布局

  • doc/source/
    • install/ – 与项目安装有关的任何内容
    • contributor/ – 与为项目贡献或团队管理相关的内容。适用于当前 /developer 下的部分内容，我们正在更改名称以强调并非所有贡献者都是开发者，有时开发者是用户但不是贡献者。服务项目应将自动生成的类文档放置在此树的这一部分，例如在 contributor/api 或 contributor/internals 中。
    • configuration/ – 基于 oslo.config 的 sphinx 集成（或对于未使用 oslo.config 的项目手动编写）自动生成的配置参考信息。启用 cells 或配置特定驱动程序等逐步指南应放置在 admin/ 部分中。
    • cli/ – 命令行工具参考文档，类似于 man 页面。这些可以通过 cliff 的 sphinx 集成自动生成，或者在无法自动生成时手动编写。使用这些工具的教程或其他逐步指南应放在 user/ 或 admin/ 部分中，具体取决于其受众。由于每个项目的文档应位于与代码相同的仓库中，因此此目录可能不存在于所有服务仓库中，但将存在于大多数客户端库仓库中。
    • admin/ – 来自旧管理员指南的任何内容或讨论如何运行或操作软件的任何内容
    • user/ – 最终用户内容，例如概念指南、建议、教程、使用 CLI 执行特定任务的逐步说明等。
    • reference/ – 与项目关联的任何参考信息，不包含在上述类别中。库项目应将自动生成的类文档放置在此处。

此布局是最低集合。项目可以自由地并鼓励添加超出此列表的任何其他他们需要的文档，但这些项目在此处明确列出，因为已经有链接从登陆页面指向它们的大部分内容，并且可以为其他内容创建登陆页面。

在后续阶段，我们将把 API 参考和发布说明构建合并到同一个作业中，以及项目的其余文档。然而，这两个构建都有自定义的考虑因素，并且移动文档团队将不再维护的内容更为重要。

  • doc/source/
    • api/ – REST API 参考和指南内容（如果存在）
    • releasenotes/ – reno 指令（实际的发布说明输入将保留在 /releasenotes/notes 中，就像现在一样）

注意

对 api/ 和 releasenotes/ 目录的布局的进一步讨论将推迟到我们完成初始迁移工作之后。

将设置一个新的文档构建作业，以获取从 tox -e venv -- python setup.py build_sphinx（与现有的一致测试接口）生成的输出，并将其发布到 https://docs.openstack.org 下的新位置。结果将进入

  • docs.openstack.org/$project-name/latest – 从 master 构建
  • docs.openstack.org/$project-name/$series – 从 stable/$series 构建
  • docs.openstack.org/$project-name/latest/$lang – 从 master 构建翻译版本
  • docs.openstack.org/$project-name/$series/$lang – 从 stable/$series 构建翻译版本

由于我们计划重用每个项目中的现有 doc/source 目录，因此在从 openstack-manuals 导入内容时，需要重新排列一些现有内容。

最终，这将改变我们发布结果的方式，并且需要设置从所有现有位置到新位置的重定向，并将所有现有文档移动到新的结构下。我们将保留高级类别（例如安装指南、配置参考和贡献者文档）的登陆页面。这些页面将继续由文档团队维护，并将深入链接到项目团队的文档。

例如，我们将保留像 https://docs.openstack.org/project-install-guide/ocata/ 这样的页面，但它们将提供指向像 https://docs.openstack.org/nova/ocata/install 这样的 URL 的链接列表，这将是 nova 的单个文档构建的一部分。

每个指南会发生什么？

  • 安装指南
    • 大部分内容将从 openstack-manuals 移动到每个项目的树中。
    • 与特定 OpenStack 项目无关的章节，例如与安装 ntp 和 RabbitMQ 相关的部分，将保留在 openstack-manuals 中，以设置共享的常见依赖项，以便无需多次复制内容。
    • 当前指南实际上构建了 3 次，以涵盖 3 个单独的部署平台。新的构建将不支持这一点，因此安装指南的迁移将涉及将内容分解为针对每个平台的单独页面（如果需要）。补丁 https://review.openstack.org/473579 将内容分解为单独的补丁，每个操作系统一个。
  • 项目安装指南，已在树中
    • 我们建议任何已在树中的安装指南也移动到新的组织结构中。
  • 管理员指南
  • 高可用性指南
  • 操作指南
    • 此指南将最终从 openstack-manuals 移动到 wiki。在找到志愿者来管理此移动之前，将不会对其进行任何操作。
  • 安全指南
    • 此内容将保留在 openstack-manuals 中，并由安全团队管理。
    • 正在添加通知，以指示上次更新的时间以及相关的发布版本 (https://review.openstack.org/#/c/470059)。
  • 架构设计指南
  • 网络指南
    • 此内容将从 openstack-manuals 移动到 neutron 仓库的 docs/source/admin 下。
  • 配置参考
  • API 文档
    • 没有更改。
  • 最终用户指南
    • 此内容将在 horizon 仓库和 python-openstackclient 仓库之间划分。
  • 命令行参考
    • 此内容会将项目特定的客户端文档树移动到 doc/source/cli 下。例如，有关使用 glance 命令行工具的信息将移动到 python-glanceclient 仓库。
  • 虚拟机镜像参考
    • 此内容将保留在 openstack-manuals 中。

迁移过程

如果我们要在 Pike 周期结束前完成它，我们需要尽可能地并行化迁移工作。因此，我们需要项目团队找到志愿者将内容“拉”到他们的仓库中，而不是让文档团队“推送”它。

注意

对所有补丁使用主题 doc-migration。

注意

对所有服务器项目、客户端和其他库重复这些步骤。

  1. 将现有的面向贡献者的内容移动到以适应上述布局。使用 Depends-On: Ia750cb049c0f53a234ea70ce1f2bbbb7a2aa9454 提交该更改，将其与此规范关联。

  2. 如果您的项目文档尚未在 setup.cfg 中使用 warning-is-error 构建，请启用它并修复任何构建错误。将这些作为补丁提交到第一个补丁之上。

  3. 按照上述布局拉入正在迁移的内容。

    • 浏览 https://etherpad.openstack.org/p/doc-migration-tracking 中的手册列表，并采取必要的措施导入内容。
    • 为每个手册准备一个补丁（因此，导入安装指南、用户指南等）。将这些作为补丁提交到任何之前的补丁之上。
    • :term: 需要在导入和执行迁移时删除。这是因为词汇表保留在 openstack-manuals 仓库中。团队可以选择链接到他们自己项目页面上的词汇表（如果他们愿意）。

  4. 确保 doc/source 的每个子目录中都有一个 index.rst，以便文档团队管理的登陆页面可以直接链接到项目的文档的该部分。例如，除了将安装文档移动到 install/ 之外，还创建 install/index.rst，其中包含一个 toctree 指令，显示所有安装内容。

  5. 确保 doc/source 中有一个顶层 index.rst，它通过包含所有子目录到 toctree 中来合并项目的全部文档。

  6. 更新树内文档的主题以使用 openstackdocstheme 代替 oslosphinx。

  7. 在 configuration/ 目录中添加自动生成的配置参考部分。

  8. 如果正在使用 pbr 的 autodoc 功能，请更新 setup.cfg 的 pbr 部分中的 api_doc_dir 设置，以指向 reference/api（对于库）或 contributor/api（对于其他类型的项目）。

  9. 将 project-config 更新为使用新的构建任务，而不是旧的任务，通过将 ‘openstack-server-publish-jobs’ 替换为 ‘openstack-unified-publish-jobs’。

    将 Depends-On 设置为步骤 1 中创建的补丁的 Change-Id。 这可确保我们不会将旧内容发布到新位置。

  10. 在每个手册的专门章节中，在每个 TODO 项目下方添加指向评审的链接。 这样文档团队就能知道何时可以安全地开始删除内容。

备选方案

  1. 我们可以保留开发者和 API 文档的现有树，并为“用户”文档添加一个新树。 安装指南、配置指南和管理指南将移动到这里，适用于所有项目。 Neutron 的用户文档也将包含当前的 Networking 指南。 此选项将为每个仓库添加 1 个新的构建，但可以让我们更轻松地推出更改，减少站点组织和发布方式的干扰，从而在短期内减少工作量。
  2. 我们可以将内容移动到项目团队拥有的单独仓库中，而不是与代码一起放在树中。 这将允许项目团队将文档管理委托给一个单独的评审子团队，但会使同时发布代码和文档更新的过程变得复杂，从而确保文档始终是最新的。
  3. 什么都不做，看着世界毁灭。

我们考虑过使用“服务类型”而不是“项目名称”作为发布 URL，但并非所有需要文档的项目都是服务。 例如，我们将从几个 Oslo 库获得面向用户的文档。

实现

负责人

主要负责人

  • Alexandra Settle (asettle)
  • Doug Hellmann (dhellmann)
  • 项目团队
  • Queens 的文档团队 PTL
  • 文档团队

工作项

任务列表很长，为了避免在这里重复，我们给出一个摘要。 更多细节请参见步骤 3 中提到的跟踪板。

  1. 定义新的文档构建和门控任务，其工作方式与当前任务相同，在仓库中使用“tox -e venv – python setup.py build_sphinx”，但发布到 docs.o.o/$project-name/latest 的新位置 (dhellmann)
  2. 为稳定分支定义文档构建任务，运行相同的命令，但发布到 docs.o.o/$project-name/$series (dhellmann)
    • 相同的任务将适用于所有分支。
  3. 同时，在每个仓库中，执行上述迁移步骤，将新内容复制到 doc/source 目录中。 有关哪些页面进入哪些项目树的详细信息，请参阅 https://etherpad.openstack.org/p/doc-migration-tracking。
  4. 基于发布说明构建任务，定义新的翻译任务，但使用主文档构建。
  5. 为 openstack-manuals 词汇表创建一个单独的构建。

依赖项

  • 项目团队协作
  • 基础设施团队协助
  • 来自多个来源的评审
更新日期：2018-12-06 13:55
Creative Commons Attribution 3.0 License

除非另有说明，本文档根据 知识共享署名 3.0 许可协议 授权。请参阅所有 OpenStack 法律文件。

问题？

docs-specs