[ English | Indonesia | русский ]

代码规范

提交代码的一般指南

  • 编写良好的提交消息。我们遵循 OpenStack 的“Git Commit Good Practice”指南。如果您对如何编写良好的提交消息有任何疑问，请查阅上游 OpenStack 文档。

  • 项目更改应通过 Gerrit 工具提交以供审查，并遵循 此处记录的工作流程。

  • 通过 GitHub 提交的拉取请求将被忽略并关闭，不作考虑。

  • 补丁应专注于解决一个问题。如果审查过于复杂或总体较大，初始提交将收到“-2”的评价，并且贡献者将被要求将补丁拆分为多个审查。对于复杂的特性添加，该特性的设计和实现应以可以分多个补丁提交的方式进行，并使用依赖关系。使用依赖关系的变化应始终旨在在依赖链中实现一个可用的构建。有关 高级 Gerrit 用法也有文档。

  • 所有补丁集应遵守此处列出的 Ansible 风格指南，并在可能的情况下遵守 Ansible playbook。

  • 所有更改应在提交消息中明确列出，并附带相关的 bug id/blueprint 以及任何其他适用信息。

  • 重构工作绝不应包含额外的“附加”特性。可能与重构内容相关的特性应作为 issue 提出，并在之前的或后续的补丁中提交。

  • 新特性、破坏性更改和其他重要的补丁必须包含使用 reno 工具生成的发布说明。有关更多信息，请参阅 文档和发布说明指南。

  • 包括代码、文档和发布说明的所有补丁都应使用适当的测试套件在本地构建和测试，然后再提交以供审查。有关更多信息，请参阅 开发和测试。

文档和发布说明指南

文档是确保 OpenStack-Ansible 的部署者能够充分了解

  • 如何有效地使用项目的工具来部署 OpenStack。

  • 如何实施正确的配置以满足其特定用例的需求。

  • 项目随时间的变化，这些变化可能会影响现有的部署。

为了满足这些需求，开发人员必须提交 代码注释、文档（另请参阅 文档位置部分）和 发布说明，以及任何代码提交。

所有形式的文档应符合 OpenStack 文档贡献者指南中提供的指南，特别是以下部分

  • 写作风格

  • RST 格式约定

代码注释

应使用变量的代码注释来解释变量的目的。这对于 role defaults 文件尤其重要，因为该文件会逐字包含在 role 的文档中。如果变量是可选的，则应将变量及其用途的说明添加到 defaults 文件中。

bash/python 脚本的代码注释应提供代码目的的指导。这对于在补丁合并之前为审查者提供上下文以及在后续修改中提醒贡献者目的和原因非常重要。

文档位置

OpenStack-Ansible 有多种形式的文档，具有不同的目的。

部署指南旨在帮助部署者首次部署 OpenStack-Ansible。

用户指南旨在提供关于如何使用 OpenStack-Ansible 执行特定操作的用户故事。

操作指南提供有关如何管理和操作 OpenStack-Ansible 的帮助。

深入的技术信息位于 OpenStack-Ansible 参考 中。

role 文档（例如，keystone role 文档）旨在解释 role 可用的所有选项以及如何实施更高级的需求。为了减少重复，role 文档直接包含 role 的默认变量文件，其中包含解释变量目的的注释。role 的详细文档应更侧重于解释如何实施高级用例，而不是解释变量。

role 文档必须包含对强制基础设施的描述（例如：需要数据库和消息队列）、变量（例如：数据库名称和凭据）和组名称（例如：role 期望存在一个名为 foo_all 的组，并且期望主机是该组的成员），以便 role 执行成功。

在 OpenStack-Ansible 的文档中，应尽量避免尝试解释 OpenStack 概念。这些解释应属于 OpenStack 手册或服务文档，并且 OpenStack-Ansible 文档应在可用时链接到这些文档，而不是重复其内容。

发行说明

发布说明使用 reno 工具生成。发布说明必须遵循以下指南编写

  • 每个列表项必须在不了解补丁或提交补丁的存储库的上下文的情况下才能理解。原因是所有发布说明都将合并并以长列表的形式呈现，不引用源补丁或存储库的上下文。

  • 每个注释应简明扼要。尽量避免多段注释。对于特性，注释通常应引用文档以获取更多详细信息。对于错误修复，注释可以引用注册的错误以获取更多详细信息。

在大多数情况下，只有以下部分应用于与补丁提交的新发布说明

  • features：这应简要告知部署者一项新特性，并描述如何通过引用要设置的变量或引用文档来使用它。

  • issues：这应告知部署者已知问题。这可能用于修复问题并希望告知部署者可以使用先前的版本的工作方法，直到包含修复该问题的补丁的版本为止。问题注释应明确提及受该问题影响的 OpenStack-Ansible 版本。

  • upgrade：这应告知部署者升级到以前的主要或次要版本时可能影响他们的更改。通常，这些注释将描述默认变量值的更改或已删除的变量。

  • deprecations：如果变量已被弃用（理想情况下使用弃用过滤器），则应通过此部分中的注释进行说明。请注意，如果变量已被完全删除，则它未被弃用，并且删除应在 upgrade 部分中注明。

提交规范

通过提出草案规范，您可以帮助 OpenStack-Ansible 社区跟踪正在开发或大型更改的内容，并可能与其他人建立联系，他们可能感兴趣并能够帮助您完成该过程。

我们的规范存储库遵循 OpenStack 和 OpenStack-Ansible 提交代码的常用指南。

但是，为了帮助您编写规范，我们有一个 规范模板，可以将其复制到最新的发布名称文件夹中。重命名并根据您的需要进行编辑。

Ansible 风格指南

YAML 格式

在创建用于在 Ansible 中使用的任务和其他 role 时，请使用 YAML 字典格式创建它们。

示例 YAML 字典格式

- name: The name of the tasks
   module_name:
     thing1: "some-stuff"
     thing2: "some-other-stuff"
   tags:
     - some-tag
     - some-other-tag

示例 NOT 要做的

- name: The name of the tasks
  module_name: thing1="some-stuff" thing2="some-other-stuff"
  tags: some-tag

- name: The name of the tasks
  module_name: >
    thing1="some-stuff"
    thing2="some-other-stuff"
  tags: some-tag

“>”和“|”运算符的使用应仅限于 Ansible 条件和命令模块，例如 Ansible shell 或 command。

标签和标签约定

注意

如果您想了解如何有效地使用 Ansible 标签，请查看 操作指南。

标签是根据每个项目的相关性分配的。高级包含（例如在 tasks/main.yml 中）需要高级标签。例如，*-config 或 *-install。包含的任务可以有更详细的标签。

使用以下约定

  • 包含单词 install 的标签处理软件安装任务。使用 --tags <role>-install 运行 playbook 仅会在目标上部署必要的软件，并且不会根据您的需要对其进行配置或运行任何服务。

  • 包含单词 config 的标签准备软件的配置（根据您的需要调整），以及运行 role 中配置的所有必要组件。使用 --tags <role>-config 运行 playbook 仅在目标已经运行了 <role>-install 标签后才可能。

变量文件约定

role 中的变量文件分为 3 个位置

  1. defaults/main.yml 文件

  2. vars/main.yml 文件

  3. vars/<平台特定>.yml 文件

优先级较低的变量应位于 defaults/main.yml 中。这允许通过组变量或主机变量覆盖它们。一个很好的例子是默认数据库连接详细信息、默认队列连接详细信息或调试模式。

换句话说，defaults/main.yml 包含旨在由部署者或持续集成系统覆盖的变量。这些变量应尽可能限制，以避免增加测试矩阵。

vars/main.yml 始终包含。它包含不应由部署者更改的通用变量。这包括例如 role 内部变量的静态信息（例如）。

vars/<平台特定>.yml 是存储特定于发行版的内容的地方。例如，此文件将包含软件包名称、存储库 URL 和密钥、文件路径、服务名称/init 脚本。

密钥

任何密钥（例如：密码）都不应在任务、role 变量或 role defaults 中提供默认值。如果未提供所需的密钥，则任务执行应失败。对于默认安全的实现，确保环境不会因生产中使用默认密钥而受到影响非常重要。必须强制部署者正确提供自己的密钥变量值。

任务文件约定

大多数 OpenStack 服务将遵循一系列常见的阶段来安装、配置或更新服务部署。在查看现有 role 的 tasks/main.yml 时，这一点很明显。

如果正在开发新的 role，请遵循现有 role 设定的约定。

测试约定

编写测试的约定在 测试 页面中描述。

其他 OpenStack-Ansible 约定

为了促进所有 OpenStack-Ansible role 中实施的开发和测试，需要实施一组基本文件夹和文件。一组基本配置和测试促进脚本必须至少包含以下内容

  • tox.ini：role 的 lint 测试、文档构建、发布说明构建和功能构建执行过程都定义在此文件中。

  • test-requirements.txt：执行测试时必须安装的 Python 要求。

  • bindep.txt：必须安装在执行 Python 要求和 tox 执行的宿主机上的二进制要求。这必须从 openstack-ansible-tests 存储库复制，并且我们的提案机器人应发生任何更改时自动覆盖它。

  • setup.cfg 和 setup.py：用于构建工件的存储库信息。

  • README.rst, LICENSE, CONTRIBUTING.rst: 一组标准文件，其内容不言自明。

  • .gitignore: 一个标准的 git 仓库配置文件，应该在所有仓库中保持相对统一。 此文件必须从 openstack-ansible-tests 仓库复制，并且我们的提案机器人会在发生任何更改时自动覆盖它。

  • .gitreview: 一个为项目配置的标准文件，用于告知 git-review 插件在哪里可以找到仓库的上游 Gerrit 远程仓库。

  • docs/ 和 releasenotes/ 文件夹需要存在并正确配置。

请参考 os_cinder、os_keystone 或 os_neutron 等 role，以获取最新的文件。

容器技术无关性

role 的实现应该以一种与容器或物理主机上的实现无关的方式进行。 测试基础设施可能会使用容器来隔离服务，但如果一个 role 被用于针对主机的 playbook，它必须无论该主机是容器、虚拟机还是物理服务器都能正常工作。 对 role 测试使用容器不是必需的，但它可能对模拟测试基础设施中的多节点构建有所帮助。

最低支持的发行版

请参阅我们的 支持的发行版 页面。