跳转到： 导航, 搜索

Documentation/IncubateIntegrate

孵化项目和文档

您正在申请孵化，恭喜！我知道您已经研究了孵化和集成状态的最低要求 https://github.com/openstack/governance/blob/master/reference/incubation-integration-requirements.rst。您可能想知道在每个阶段的“文档”要求是什么。让我们通过示例来了解一下。

TC（技术委员会）只期望在孵化申请期间看到贡献者文档。我们认为您希望招募更多的 Python 开发者来帮助您实现目标。OpenStack 项目首先会在 wiki 上进行一些项目文档记录，例如在申请过程中。

您刚刚被孵化，现在怎么办？

在您孵化期间，我们希望在您的仓库中看到 doc/source 目录下的文档，并使用 Sphinx 构建。在您的项目开始孵化时，您可以开始使用 oslosphinx 主题，这是 OpenStack 项目常用的主题。您必须通过确保您的 sphinx conf.py 文件中将 incubating 设置为 True 来表明您正在孵化。

   'html_theme_options = {'incubating': True}'

在孵化期间，您可以发布到 docs.openstack.org/developer。在孵化之前，我们建议发布到 ReadTheDocs.org 或您自己的域名，并且除非您获得品牌指南中概述的许可，否则请避免使用 OpenStack 徽标或商标 https://openstack.org/brand/。

在您孵化并招募开发者贡献者时，请务必寻找编写者资源。您的开发者可能可以管理贡献者开发者文档，但请考虑如何编写您的 REST API 参考文档、安装文档、配置文档、操作员和管理员文档以及 CLI 和仪表板交互的最终用户文档。您需要证明您能够通过文档和 ask.openstack.org 上的答案来支持您的用户（操作员、管理员和最终用户），才能毕业到集成状态。

在您集成期间，我建议您的 doc/source 目录成为文档的存放位置。您需要关注的是以这种方式编写，以便您的页面可以用于官方 OpenStack 文档中的这些交付物，该文档位于 https://wiki.openstack.org/wiki/Documentation/ContentSpecs。

请始终注意，OpenStack 文档程序优先考虑核心项目，而不是集成项目，但我们提供框架和审查，并尽力提供指导。我们无法提供共享资源，例如分配给每个项目的技术作者。相反，我们期望项目指定一个文档联络人，可以通过 openstack-docs 邮件列表和 #openstack-doc IRC 频道与文档组进行交互。文档团队每周举行会议，很高兴让文档联络人参加在其时区内的会议。会议日程和议程可以在这里找到：https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting。

这里有一个 Barbican 项目的工作示例，目前处于孵化阶段

  • REST API 文档位于 openstack/barbican 仓库中，开发者指南包含 JSON 示例和 WADL 引用。WADL 最终可以用于 developer.openstack.org/api-ref.html 上的 API 参考。
  • 他们已经开始编写安装指南，但内容为空，使用 DocBook 格式——在这个阶段不必使用 DocBook，您可以将其放在 Sphinx 文档中。
  • 他们已经开始编写发布说明，但内容为空，同样也可以放在 Sphinx 文档中。
  • 由于该项目的主题与安全和身份相关，请考虑安全指南，以及如何将其融入其中。
  • 对于配置信息，请使用 Oslo common 来帮助自动化配置参考。它当前构建 docbook 表格。
  • 对于 CLI 信息，在孵化之后，我们可以自动导入 --help 信息，因此请确保它有帮助。

您正在申请毕业到集成状态，想知道需要哪些文档？如何编写它们？（什么是被动语态？）它们何时会发布到 docs.openstack.org？让我们继续。

集成项目和文档

一个项目可以在一个发布周期内尽快集成，例如 icehouse 到 juno。这意味着大约有六个月的时间来确保该项目正在支持部署者和最终用户，并提供文档以及邮件列表帖子和 ask.openstack.org 的回复。如前所述，由于文档程序不为集成项目提供额外的资源，每个团队都需要找到他们可以用来编写文档的资源。

集成项目何时真正达到集成状态？像一个部署者一样思考：他们只有在集成版本实际可用时才能获得它。因此，发布文档（仅安装和配置）仅在发布的确切日期发布，该日期在此处维护：https://wiki.openstack.org/wiki/Releases。所有其他文档都会持续发布，也就是说，一旦 doc-core 人员推送批准，它就会立即发布到 docs.openstack.org 网站。但是，发布尚未发布的内容是不准确的，因此我们通常会让补丁在审查队列中等待，直到被认为已发布。发布说明通常会收集在每个版本的 wiki 页面上，集成项目应确保为此做好计划。这是一个例子：https://wiki.openstack.org/wiki/ReleaseNotes/Icehouse

让我们通过一个正在完成集成文档的项目示例。ceilometer 项目编写的 Telemetry 模块执行以下操作

  • 提供它们为每个项目收集的所有度量的参考
  • 描述如何安装
  • 描述配置选项，包括那些影响跨项目集成的选项
  • 提供发布说明
  • 在云管理员指南中添加一个章节，添加遥测管理主题

那么 Sahara 呢？它在 Juno 中集成。他们正在为文档目标做些什么？

  • 我们将其 CLI 参考补丁合并到 openstack-manuals 中。（即使他们直到 Juno 版本才正式集成，并且这是一个持续集成的交付物）。
  • 他们在他们的开发者文档站点上编写他们的安装、配置和升级指南，网址为 https://docs.openstack.org/developer/sahara/。我想他们提出一个补丁，例如数据库章节，作为可选章节，将不会很困难。
  • 他们还有一个 UI 配置指南，以确保 OpenStack 仪表板（horizon）可以显示 sahara Hadoop 集群。很好！)
  • 像 trove 数据库项目一样，您需要注册一个镜像，因此他们可能希望更新虚拟机镜像指南，就像 trove 团队一样。
  • 他们有一个功能齐全的开发者指南，其中包含编程教程，供贡献者使用。

总而言之，孵化和集成的文档指导简短，但实际的文档工作是广泛的。发布时间应与发布本身一致。文档团队喜欢与项目联络人合作，并提供一些工具支持，并大量依赖 Oslo。文档永无止境，但我们使用与 OpenStack 项目相同的流程，包括 Gerrit 中的错误跟踪、补丁和审查，以及尽可能多的自动化。

从 "https://wiki.openstack.org/w/index.php?title=Documentation/IncubateIntegrate&oldid=63119" 检索