项目特定的安装指南¶

基本安装指南的范围¶

基本安装指南的内容将涵盖每个云所需的基础设施和集中式项目。这包括定义为 starter-kit:compute 的项目，以及其他一些项目

• 计算服务 (nova)：starter-kit:compute 的一部分。
• 镜像服务 (glance)：starter-kit:compute 的一部分。
• 身份验证服务 (keystone)：starter-kit:compute 的一部分。
• 网络服务 (neutron)：starter-kit:compute 的一部分。
• 块存储服务 (cinder)：当前安装指南的一部分，并且大多数用户都期望它。
• 仪表板 (horizon)：当前安装指南的一部分，并且大多数用户都期望它。

除非它们是现有项目所必需的，或者通常需要运行基于 OpenStack 的云，否则不会向指南中添加更多项目。

文档团队将更新和测试每个版本的基本安装指南。

安装指南将增强，以链接到额外的项目特定安装指南。为此，它将为每个官方项目提供一个单独的章节，其中每个官方项目可以对他们的项目进行简短的总结，并链接到他们自己的安装指南。该章节还将解释所有这些项目都是 OpenStack 庞大社区中的一等公民。

例如，编排 (Orchestration) 可以在 heat 仓库中存储他们的安装指南，并发布到 https://docs.openstack.org/project-install-guide/mitaka/orchestration/ 。

然后“附加项目”章节将包含一个介绍该服务并链接到它的简短部分

Orchestration service (heat)
============================

The Orchestration service ...

Installation is documented at
http://docs.openstack.org/project-install-guide/mitaka/orchestration
.

Docs.openstack.org 索引¶

项目特定的安装指南不仅会列在安装指南中，还会从 docs.openstack.org 网页中找到。具体位置需要根据指南的数量来确定。

项目特定安装指南的内容¶

这些项目特定安装指南的内容不在文档团队的控制范围内。为了与基本安装指南架构保持一致，并作为“赋能他人”的一部分，文档团队提出了一些建议

• 我们鼓励项目在现有的安装指南架构之上构建。这样，项目团队的指南就不需要记录完整的 OpenStack 设置，包括基本主机设置。与其重新发明轮子，不如让项目团队的指南指出特定项目的差异。
• 我们鼓励项目遵循文档约定，如 文档贡献者指南 中所述。
• 我们鼓励项目使用与安装指南相同的样式主题（称为 openstackdocstheme）。
• 我们鼓励项目支持与安装指南相同的发行版。他们可以记录从发行版安装 OpenStack 包，或从源代码安装。
• 项目特定的指南应该进行版本控制，因此项目团队应该发布到其服务的相应子目录。
• RST 是首选的文档格式，我们的发布工具最适合使用它。此外，RST 指南的翻译易于设置，并且在 OpenStack CI 基础设施中工作。因此，项目团队应该使用 RST 格式。
• 项目团队的安装指南应该有一个通用的命名方案：“X 服务安装指南”，其中 X 是治理仓库中的服务名称。例如，“编排服务安装指南”。

发布¶

项目团队可以将他们的内容发布到 docs.openstack.org/project-install-guide/RELEASE/SERVICE/ ``。 ``RELEASE 是像 mitaka 或 newton 这样的版本，SERVICE 是像 orchestration 这样的服务名称。对于从 master 分支发布，RELEASE 应该为 draft。

这种结构可以确保我们不会为不同的项目共享目录。

备选方案¶

• 打包的安装指南分离出来，没有单一来源的安装指南：每个发行版发布他们自己的安装指南。这些指南可以发布到 docs.openstack.org/install 或他们拥有的网络域，从他们自己的仓库中获取和审查，并由他们的团队进行审查。这些团队可以设置他们自己的发布计划。这种替代方案不能满足项目团队的需求，但可以减轻对集中式文档团队的资源压力。

• 停止在 OpenStack git 命名空间中编写基于包的安装指南。相反，让一个中央团队编写基于 starter-kit 的指南，描述多个可用的部署选项，并发布到 docs.openstack.org。当读者浏览 https://openstack.org/marketplace/distros/ 上的发行版市场时，此解决方案可能已经可用。

• 每个项目团队可以编写一个“从源代码安装”安装指南，其中包含所有基本项目基础设施的设置。

• 更改安装指南的范围，如本规范中建议的那样，添加更多或更少的项目。但是，这不能解决上述与包相关的单一来源问题。

• 现状：一个由文档团队维护的中央安装指南，对于那些不在中央指南中的项目，没有项目特定的指南。除非我们从每个项目中获得资源承诺，否则这种方法无法扩展。

• 一个中央指南由文档团队审查——就像今天一样——只有当项目团队承诺编写、测试和更新章节时，项目才会被记录。

  这无法扩展，因为审查仍然由文档团队进行。过去的经验表明，项目团队需要被提醒他们的承诺，因此最终文档团队将扮演一个大型协调和引导角色，而不是遵循本提案寻求的赋能角色。

负责人¶

• Lana Brindley (loquacities) - 文档 PTL
• 安装指南专业团队

工作项¶

• 将现在超出基本安装指南范围的项目移动到他们自己的仓库中。此外，为这些项目特定的安装指南创建初始骨架，以便项目团队可以遵循其他人的示例，从而获得一致的起点。

  这会影响：编排 (heat)、遥测 (telemetry)、对象存储 (swift)、共享文件系统 (manila)。

• 创建新的章节“项目特定的安装指南”作为骨架。

• 在 https://docs.openstack.org 上创建新的项目特定安装指南部分。

• 创建项目特定安装指南发布的示例作业 (jaegerandi)。

• 与 operator tags 团队合作，修改 ops:docs:install-guide 标签 (thingee)

• 创建一个“cookie cutter”模板，供项目在创建新的安装指南时使用。