已发布文档的保留策略¶

问题描述¶

当前已发布文档的保留策略规定，当相关的分支被标记为“结束生命周期”并关闭时，手册将被从 docs.openstack.org 上移除。过去，较旧的文档已被从站点移除，原因如下（顺序不限）

• 内容大小

  当时使用的托管服务，我们发布的内容量非常大。

• 搜索结果

  • 移除较旧的文档被认为可以减少混淆，因为没有指定版本号或系列名称的用户在搜索时不会遇到过时的信息。
  • 由于拥有更长的稳定 URL，较旧版本的文档在搜索结果中出现的频率高于较新版本的类似更新内容。

• 支持请求

  针对不再更新或修复的文档版本，已经提交了错误和支持请求。这给文档团队带来了不必要的负担。

• 构建支持

  在文档的稳定分支关闭后，不再有构建和更新已发布文档的方法。这与内容本身无关，但我们至少遇到过一种情况，即存在一个跨站脚本攻击的安全问题，指出如果未来在无法构建的分支中出现类似的动态站点问题，删除内容可能是我们唯一可以采取的行动。有关详细信息，请参阅 clouddocs-maven-plugin 仓库中的提交 de6289854e9a059d5a33075b6593e7f9cb3b4f2d（由于某种原因，该仓库未通过 gerrit 索引或通过 cgit 网页 UI 提供）。

我们正在更新此策略，原因有两个

1. 根据撰写本文时的最新用户调查，大约 60% 的用户正在运行不再受上游支持的 OpenStack 版本。这些用户缺少他们正在部署的软件版本的准确文档。
2. 作为 OpenStack 手册项目迁移 计划的一部分，更多主动维护的文档现在由 openstack-manuals git 仓库之外的项目团队管理。

提议的变更¶

拟议的更改是停止基于其年龄或其适用的软件的年龄或其恢复的仓库，从 docs.openstack.org 上删除所有内容。

我们还将恢复 Mitaka 到 Ocata 的管理员指南、CLI 参考和用户指南。管理员指南旨在在系列之间重复使用，但只有在底层操作系统没有更改时才是真的。由于过去它已经更改过，我们需要将管理员指南视为特定于系列的即使我们没有更改它。Mitaka 的 CLI 参考和用户指南使用旧版本的客户端，并且选项可能已经更改。

选择 Mitaka 系列的原因有几个。

1. 它是所有文档都使用 Sphinx 进行管理的第一个系列，Sphinx 比旧工具更容易安装，并且社区中有更多的人了解如何使用 Sphinx。
2. 它也代表了一个足够旧的版本，对大量用户有用。实用性和易于更新的结合使 Mitaka 成为开始新的保留策略的一个很好的折衷点。
3. Mitaka 版本的许多特定于项目的文档仍然存在于 docs.openstack.org 上，因此很容易链接到它。

我们将找到其他方法来缓解促使我们采用删除已结束生命周期版本的旧策略的问题。

已结束生命周期版本的文档在相关的稳定分支关闭时仍将被冻结，因此不会进行任何更新。此更改不应显著增加维护负担或用户的期望。

• 内容大小

  我们已经将 docs.openstack.org 从 CloudSites 托管服务迁移到具有大型文件系统的标准 Web 服务器。我们发布的内容量不再是一个重要问题。

• 搜索结果

  鉴于运行旧版本的用户数量，我们对搜索结果的优先级已经改变。我们希望旧版本可以通过搜索引擎获得，假设用户可以轻松确定他们找到的结果是否与他们的版本匹配，或者他们可以快速地在版本之间导航。

  我们将继续尝试搜索引擎优化技术，以使不合格的搜索，例如“安装 nova”，显示较新的结果。这项工作将有自己的规范，由承担该任务的团队创建。

  我们可以通过利用主题的 earliest_published_series 配置选项，使在特定于系列的文档之间导航变得容易。

  我们还将更新文档主题，以包含一个水印或“徽章”，清晰地指示何时内容被认为过时，尤其是当它不再维护时。这些标记需要构建在文档之外，以便可以独立更新它们，而无需修补文档或向稳定分支 EOL 过程添加步骤。在 Queens PTG 上讨论的计划基于从 openstack-manuals 仓库构建的 SVG 文件，并由 openstackdocstheme 包含在已发布页面中。需要进一步详细说明，并且这项工作将涉及一个遵循此规范的规范。

• 支持请求

  项目团队现在负责特定于项目的文档。发送到文档团队的错误和支持请求可以根据需要进行分类和重新分配给项目团队。与不再支持的文档相关的任何内容应以与不支持的代码的错误报告相同的方式处理（关闭“不会修复”）。

• 构建支持

  由于我们没有延长稳定分支及其包含的文档的支持生命周期，因此需要构建文档的唯一原因是在我们丢失 Web 服务器上的数据或出现另一个安全问题时。分支关闭后，不需要考虑对该分支的文档进行任何进一步的更新。

  虽然我们不想淡化潜在的跨站脚本或 JavaScript CVE 问题，但我们也不想过分强调这些问题发生的可能性。如果出现此类问题，我们将届时努力解决。在最坏的情况下，如果恢复稳定分支和更改构建不起作用，并且无法手动更新受影响的文件，我们可以删除不良内容。任何关于最佳行动方案的决定都将由积极处理问题的人员在当时做出。

  同样，如果我们在 Web 服务器上丢失数据并需要重建内容，管理恢复的人员可以在需要时制定计划。

实现¶

依赖项¶

无

测试¶

旧文档将按原样恢复，并且仅允许进行必要的更改以更新发布位置并确保构建正常工作。

参考资料¶

• 2017 年用户调查

• 邮件列表线程
  • 2017 年 7 月（文档列表）
  • 2017 年 7 月（开发列表）
  • 2017 年 8 月（开发列表）
• Queens PTG 讨论笔记
• 旧“存档”规范
• 旧“存档”蓝图