分布式管理指南

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

分布式管理员指南¶

随着管理 OpenStack 项目的运维人员数量不断增长，为了确保 OpenStack 管理员指南的质量保持在较高水平，我们需要考虑到增长和资源共享。为此，我们认为最好将源文档文件的维护分散到各个项目团队的仓库中。

本规范建议允许项目团队像管理 api-ref 和安装指南一样管理他们的管理员指南内容。

问题描述¶

目前，已经有超过六十个批准的 OpenStack 项目。期望文档团队维护所有这些项目的管理员指南是不现实的。我们需要优化文档团队资源的使用。

目前，管理员指南与代码和正在提出的补丁位于不同的 git 仓库中。这导致了“眼不见为净”的情况，即对管理员指南的更新往往是事后才考虑，甚至根本不会更新。

提议的变更¶

本规范建议像安装指南一样管理管理员指南，将管理员指南内容存储在项目仓库中，并由项目团队直接管理。文档团队可以继续对管理员指南的内容提供编辑角色，通过向项目仓库中的指南内容发布补丁来实现。这将有助于保持指南持续一致的质量和风格。

现有的管理员指南内容将被迁移到指定的项目仓库中。项目团队可以决定哪个仓库适合存放内容，例如 neutron 可以选择 openstack/neutron-lib。在这些仓库中，管理员指南内容将存储在已知且一致的位置：admin-guide/source。当前的管理员指南已经按照服务/项目进行布局，因此本提案对指南的外观和感觉应该影响最小。

项目特定管理员指南的所有权归相应的项目团队所有，而非文档团队。这意味着内容位于项目团队拥有的现有或新仓库中，评审将由项目团队进行，错误报告将进入项目的错误队列。

文档团队通过指导、设置所需的基础设施、编写指南、提供模板（“cookie cutter”）以及提供一个可供项目特定指南作为参考的工作基础管理员指南，来帮助项目团队编写项目特定指南。

文档团队将选择一个发布系列中的优先级项目列表，对这些选定项目的管理员指南内容进行全面审查和清理。这类似于 i18n 团队对本地化项目进行优先级排序的方式。

为了发布项目的管理员指南，项目将实现一个 tox 目标来构建指南，类似于为安装指南创建的 tox 目标（参见参考文献）。一个名为 ‘admin-guide-jobs’ 的 gate job 模板将被添加到项目中，包括服务名称。这将导致在更新合并时发布管理指南。

这种发布机制应该与安装指南类似。

管理员指南应该结构化

[openstack-docs/admin-guide/index.rst]
 ====================
 Administrator Guides
 ====================

 Compute service (nova)
 ======================

 The Compute service ...

 Installation is documented at
 http://docs.openstack.org/project-admin-guide/pike/compute

 Loadbalancer service (octavia)
 ======================

 The Loadbalancer service ...

 Installation is documented at
 http://docs.openstack.org/project-admin-guide/pike/loadbalancer
 .

 [nova/admin-guide/source/index.rst]
 =======
 Compute
 =======
 * System architecture
 * Images and instances
 ...

管理员指南与安装指南的一个区别是，所有管理员指南都列在一个页面上。这使得用户更容易找到任何官方 OpenStack 项目的管理员指南。

通过此更改，管理员指南现在将按发布版本进行版本控制，以允许特定版本的指南内容。这将以与安装指南版本控制相同的方式处理。从 master 分支构建的管理员指南将发布到“draft”目录，而稳定分支将发布到相应的发布目录。

The master branch of octavia would publish to:
http://docs.openstack.org/project-admin-guide/draft/loadbalancer

The stable/pike branch of octavia would publish to:
http://docs.openstack.org/project-admin-guide/pike/loadbalancer

备选方案¶

什么都不做，并尝试维护一个集中的文档仓库。
为每个项目创建一个具有共享核心状态的文档仓库。
遵循建议的更改，但允许文档团队拥有核心状态。

实现¶

负责人¶

Alexandra Settle (asettle) Joseph Robinson (jrobinson) Michael Johnson (johnsom) Ildiko Vancsa (ildikov) Brian Moss (Docs tools) 整个文档团队

工作项¶

设置一个 wiki 页面来跟踪过渡。
为管理员指南设置 cookiecutter。
鼓励项目团队将现有内容迁移到项目团队仓库。
更新主索引文件以反映新的结构。
编写一个基础管理员指南。
设置 gate jobs，以便在合并补丁时发布管理员指南。
更新文档贡献者指南，以包含设置项目管理员指南所需的步骤。
通知项目团队此发布项目特定管理员指南的方法何时可用。

依赖项¶

测试¶

参考资料¶