openstack-manuals 中的专有驱动程序文档¶
https://blueprints.launchpad.net/openstack-manuals/+spec/move-driver-docs
配置参考和云管理员指南包含各种驱动程序的文档。此规范明确了对此类文档的期望和处理方式。
驱动程序文档的共同目标包括
- 一致的文档，每个驱动程序的可比性。
- 每个驱动程序的版本无关文档，这意味着 OpenStack 版本可以更改，但驱动程序文档可以保持不变。
- 可维护的文档，每个驱动程序不会随着时间的推移发生太大变化并保持准确。
- 可审查的文档，每个驱动程序。
我们认为这种新方法的一些好处是
- 在合适的网站上更改详细驱动程序文档的灵活性更高。
- 使为贡献驱动程序编写者更容易维护详细的驱动程序文档，因为他们可以选择适合其当前工作流程的源和发布链。
- 减少了核心 OpenStack 文档团队的维护工作。
Compute、Storage、Networking 和 Databases 的驱动程序文档将按照描述的方式进行更改，目标是拥有准确的文档。这可以在 OpenStack 手册中提供简短的版本无关信息，并链接到供应商页面以获取完整详细信息或完整版本。
问题描述¶
许多 OpenStack 项目包含驱动程序以支持特定的硬件或软件。
示例包括
- Cinder：块存储驱动程序
- Neutron：网络插件
- Nova：虚拟机管理程序
- Trove：不同的数据库
这些驱动程序中的许多是硬件或软件特定的，只能由第三方驱动程序供应商记录。一些供应商拥有优秀的内置文档并定期更新，而另一些则没有或只有过时的文档。许多供应商已经在他们的网页上提供了关于驱动程序的文档，此规范建议将文档移动到供应商的网页并简单地链接到它们。
该规范还记录了作为 OpenStack 手册的一部分的完整文档的要求。
这将减少文档团队和供应商驱动程序的工作量，并提供明确的要求。
提议的变更¶
文档团队将完全记录如下指定的参考驱动程序，并为其他驱动程序添加简短的部分。如果供应商希望记录他们的驱动程序，他们被邀请 - 但不是强制 - 将他们的文档包含在配置参考中，如果他们承诺维护文档。但是，其他文档（包括云管理员指南和网络指南）将不包含第三方驱动程序的内容。在这些书籍中，如果存在第三方驱动程序，请添加以下声明：“有关其他驱动程序，请参阅配置参考指南的第 X 章”。
OpenStack 文档社区将完全记录的驱动程序的指南
- 完整的解决方案必须是开源的并使用标准硬件
- 驱动程序必须是各自 OpenStack 仓库的一部分
- 该驱动程序被认为是参考驱动程序之一
对于其他驱动程序的文档，适用以下指南
- 配置参考将为每个驱动程序包含一个小节，有关详细信息，请参见下文
- 仅涵盖包含在官方 OpenStack 项目驱动程序仓库中的驱动程序（例如，在主项目仓库或官方第三方仓库中）。
如果供应商希望添加超过最小文档，他们需要承诺以下指南
- 指定负责内容的编辑人员。
- 审查并在必要时更新他们的驱动程序，用于每个发布周期。
有了这项政策，文档团队将在配置参考中记录至少以下驱动程序
- 对于 cinder：卷驱动程序：记录 LVM 和 NFS；备份驱动程序：记录 swift
- 对于 glance：记录本地存储、cinder 和 swift 作为后端
- 对于 neutron：记录 ML2 插件以及机制驱动程序 OpenVSwitch 和 LinuxBridge
- 对于 nova：记录 KVM（大部分），发送 Xen 开源求助
- 对于 sahara：apache hadoop
- 对于 trove：记录所有支持的开源数据库引擎，如 MySQL。
外部驱动程序的默认章节格式¶
对于每个外部驱动程序，我们希望以版本无关的方式简要记录驱动程序，并包含当前的配置选项。
每个章节应遵循此格式
一段简短的段落解释驱动程序。
一个链接，其中包含指向供应商网站的详细说明（如果有的话）
一个默认段落，例如
Set the following in your cinder.conf, and use the following options to configure it. volume_driver = cinder.volume.drivers.smbfs.SmbfsDriver
最后是自动生成的配置选项
驱动程序供应商可以发送这些补丁或创建错误。
供应商的完整文档¶
如果供应商希望在配置参考中提供完整的文档，他们必须添加到 wiki 页面 一个联系编辑，他将负责供应商驱动程序文档。文档团队将向联系人分配错误，将联系人包含在供应商驱动程序的审查中，并期望及时响应。
如果供应商驱动程序文档变得过时，并且联系人没有对请求做出反应，则文档团队会将完整的文档更改为最小版本。
文档团队将审查供应商驱动程序，并确保各种驱动程序文档遵循一致的标准。
备选方案¶
- 保持现状：将所有驱动程序添加到配置参考。
- 删除驱动程序，完全不链接到它们 - 或仅链接到单个 wiki 页面。
- 对所有驱动程序仅拥有最小文档。这是最初的想法，但被拒绝，因为一些供应商没有自己的文档。
实现¶
这项工作将分三个步骤完成
- 在配置参考中，将所有当前只是“骨架”的驱动程序部分提升到上述标准。
- 与第三方驱动程序合作，将配置参考中现有的文档转换为新标准。
- 从其他文档（如云管理员指南）中清除第三方驱动程序内容。
负责人¶
整个文档团队的口头交流 - 通知供应商
工作项¶
- 通知第三方驱动程序联系人有关更改（请注意，我们必须提前让他们了解此规范，以便获得他们的意见）
- 要求供应商驱动程序指定一个联系人并给出截止日期。
- 为目前没有内容的驱动程序添加最小内容。
- 增强内容（根据驱动程序供应商的建议）
- 从其他文档中清除第三方驱动程序内容。
依赖项¶
无。
测试¶
除非另有说明，本文档根据 知识共享署名 3.0 许可协议 授权。请参阅所有 OpenStack 法律文件。