示例规范 - 标题

包含来自 StoryBoard 的故事 URL

https://storyboard.openstack.org/#!/story/XXXXXXX

介绍段落 – 为什么要进行任何操作？一段操作员可以理解的散文。标题和此第一段应分别用作提交消息的主题和正文。

关于规范流程的一些说明

  • 并非所有蓝图都需要规范，从一个故事开始。

  • 本文档的目的是首先定义我们需要解决的问题，其次是同意解决该问题的总体方法。

  • 这并非旨在成为新功能的详尽文档。例如，无需指定确切的配置更改，也无需指定任何 DB 模型更改的详细信息。但您仍然应该定义需要进行此类更改，并明确说明这会如何影响升级。

  • 您应该在编写代码之前获得规范的批准。虽然您可以自由地编写原型和代码，然后再获得规范的批准，但规范审查过程的结果可能会导致您与最初设想的解决方案根本不同。

  • 但是，API 更改需要进行更严格的审查。一旦 API 更改合并，我们必须假设它可能已经在生产环境中，因此，我们需要永久支持该 API 更改。为了避免出错，我们希望提前获得有关 API 更改的大量详细信息。

关于使用此模板的一些说明

  • 您的规范应使用 ReSTructured 文本，如本模板所示。

  • 请将文本换行到 79 列。

  • git 仓库中的文件名应以 StoryBoard 故事编号开头。例如：2005171-allocation-partitioning.rst。

  • 请勿删除此模板中的任何部分。如果您对整个部分没有要说的话，只需写上：None

  • 有关语法帮助，请参阅 https://sphinx-doc.cn/rest.html

  • 要测试您的格式，请使用 tox -e docs 构建文档，并查看 doc/build/html/specs/<path_of_your_file> 中生成的 HTML 文件。生成的文件的扩展名将是 .html，而原始文件是 .rst。

  • 如果您想在规范中提供图表，ascii 图表通常是最佳选择。http://asciiflow.com/ 是一个有用的工具。如果 ascii 不够用，您可以选择使用 seqdiag 或 actdiag。

问题描述

问题的详细描述。此功能解决了什么问题？

用例

它解决了哪些用例？此更改对参与者有什么影响？确保您清楚地了解每个用例中的参与者：开发人员、最终用户、部署者等。

提议的变更

在这里详细介绍您提议的更改。您如何提议解决此问题？

如果这是更大工作的一部分，请明确说明这部分在哪里结束。换句话说，这项工作的范围是什么？

此时，如果您想获得关于问题和提议的变更是否适合 placement 的反馈，您可以停止在此处并将其发布以供审查，并说明：发布以获取规范范围的初步反馈。

替代方案

我们还可以用其他什么方式来做这件事？为什么我们不使用那些？这不必是全面的文献综述，但它应该表明已经考虑过为什么提议的解决方案是合适的。

数据模型影响

需要修改数据模型的变化通常会对系统产生更广泛的影响。社区通常对数据模型应该如何演进持有强烈的意见，从功能和性能的角度来看。因此，尽早捕获并达成对任何提议的数据模型更改的共识非常重要。

本节需要解决的问题包括

  • 这将需要哪些新的数据对象和/或数据库模式更改？

  • 哪些数据库迁移将伴随此更改？

  • 如何生成初始的新数据对象？例如，如果您需要考虑现有的实例，或修改其他现有数据，请描述如何进行。

API 影响

每个添加或更改的 API 方法都应具有以下内容

  • 方法的规范

    • 适合在用户文档中使用的描述方法

    • 方法类型 (POST/PUT/GET/DELETE)

    • 正常的 http 响应代码

    • 预期的错误 http 响应代码

      • 应包含对每个可能错误代码的描述，描述可能导致它的语义错误，例如提供给该方法的参数不一致，或者当资源不在适当的状态以使请求成功时。JSON 模式定义涵盖的语法问题不需要包含。

    • 资源的 URL

      • URL 不应包含下划线；而是使用连字符。

    • 可以通过 url 传递的参数

    • 如果允许，请求体数据的 JSON 模式定义

      • 字段名称应使用 snake_case 样式，而不是 camelCase 或 MixedCase 样式。

    • 如果有，响应体数据的 JSON 模式定义

      • 字段名称应使用 snake_case 样式，而不是 camelCase 或 MixedCase 样式。

  • 包括典型 API 示例的示例用例，用于调用方提供的数据和响应

  • 讨论任何策略更改，并讨论部署者在定义其策略时需要考虑的事情。

请注意，模式应尽可能严格地定义。应将所需的参数标记为必需，并且在极少数情况下才应允许未在模式中定义的附加参数（例如，additionalProperties 应为 False）。

强烈鼓励重用现有的预定义参数类型，例如密码和用户定义名称的正则表达式。

安全影响

描述任何对系统潜在的安全影响。需要考虑的一些项目包括

  • 此更改是否涉及敏感数据，例如令牌、密钥或用户数据？

  • 此更改是否以可能影响安全性的方式更改了 API，例如访问敏感信息的新方式或登录的新方式？

  • 此更改是否涉及密码学或哈希？

  • 此更改是否需要使用 sudo 或任何特权？

  • 此更改是否涉及使用或解析用户提供的数据？这可能是直接在 API 级别，或间接，例如对缓存层的更改。

  • 此更改是否会启用资源耗尽攻击，例如允许单个 API 交互消耗大量的服务器资源？这方面的一些例子包括为每个连接启动子进程，或 XML 中的实体扩展攻击。

有关更详细的指导，请参阅 OpenStack 安全指南作为参考 (https://wiki.openstack.org/wiki/Security/Guidelines)。这些指南正在不断完善中，旨在帮助您识别安全最佳实践。有关更多信息，请随时通过 openstack-security@lists.openstack.org 联系 OpenStack 安全组。

其他最终用户影响

除了 API 之外，用户还有其他与此功能交互的方式吗？

  • 此更改是否对 osc-placement 有影响？那里的用户界面是什么样的？

性能影响

描述任何对系统潜在的性能影响，例如新代码将被调用多少次，以及现有代码的调用模式是否有重大变化。

需要考虑的一些示例包括

  • 对实用函数或常用装饰器的微小更改可能对性能产生巨大影响。

  • 导致数据库查询的调用在代码的关键部分调用时，可能对性能产生深刻的影响。

  • 更改是否包含任何锁定，如果是，对持有锁有什么考虑？

其他部署者影响

讨论会影响您部署和配置 OpenStack 的事情，这些事情尚未提及，例如

  • 正在添加哪些配置选项？它们是否应该比提议的更通用？默认值是否适用于实际部署？

  • 此更改是合并后立即生效，还是需要显式启用？

  • 如果此更改是新的二进制文件，将如何部署它？

  • 请说明那些进行持续部署或从以前版本升级的人需要注意的任何事情。还描述了弃用配置值或功能的计划。

开发人员影响

讨论会影响在 OpenStack 上工作的其他开发人员的事情。

升级影响

描述任何对系统潜在的升级影响。

实现

负责人(s)

谁在编写代码？或者这是一个蓝图，您正在将其抛出以查看谁来接手？

如果有多人参与实施，请指定主要作者和联系人。

主要负责人

<IRC 昵称或 None>

其他贡献者

<IRC 昵称或 None>

工作项目

工作项目或任务 – 将该功能分解为实施它需要完成的事情。这些部分可能由不同的人完成，但我们主要试图了解实施的时间表。

依赖项

  • 包括对其他规范或故事的特定引用，这些规范或故事是此规范所依赖或相关的。

  • 如果这需要在另一个项目中需要新功能，但尚未被使用，请记录这一事实。

  • 此功能是否需要任何新的库依赖项或未包含在 OpenStack 中的代码？或者它是否依赖于库的特定版本？

测试

请讨论需要测试的重要场景，以及我们应该确保正确工作的特定边缘情况。

文档影响

哪些受众最受此更改的影响，docs.openstack.org 上的哪些文档标题应该因此更改而更新？不要重复上面讨论的细节，而是在这里引用它们，以了解多个受众的文档。

参考

请在此处添加任何有用的参考资料。您不需要有任何参考资料。此外，当您的参考资料不可用时，此规范仍然应该有意义。您可能包括的内容示例是

  • 指向邮件列表或 IRC 讨论的链接

  • 指向峰会会话笔记的链接

  • 指向相关研究的链接（如果适用）

  • 您认为值得参考的任何其他内容

历史

可选部分，旨在每次更新规范时描述新的设计、API 或任何数据库模式更新。有助于让读者了解规范随时间的变化。

修订

发布名称

描述

<替换为当前发布版本>

引入