定义交付物¶

“交付物”是可用项目的发布单元。它可能是一个单独的库，或几个服务器组件，这些组件被单独打包，但一起发布和使用。我们不基于打包等技术术语来定义，而是使用项目的社会组织来识别交付物。如果两个仓库的内容共享一个错误报告工具，以便两个仓库的内容的错误混合在一起，并对所有发布使用相同的版本号（例如，一个 launchpad 项目），那么它们都是同一个交付物的一部分。

在此仓库中，每个交付物都由发布系列目录或 _independent 目录中的一个单独文件表示。需要放入每个文件中的数据在下面详细描述。交付物的所有自动化操作都通过数据文件进行管理，该文件由核心团队在补丁被提议到 openstack/releases 时进行审查。

添加交付物¶

为了被考虑包含在给定系列的发布中，项目必须通过在系列的第二个里程碑之前将交付物文件添加到此仓库来记录。发布团队将根据具体情况考虑例外情况。

请求发布¶

项目的 PTL 或发布联络人可以通过向此仓库提交补丁，将必要的发布元数据附加到要发布的交付物描述文件来请求从 master 分支发布。发布团队将审查请求并提供有关版本号的反馈。

项目的稳定维护团队、PTL 或发布联络人可以通过向此仓库提交补丁，将必要的发布元数据附加到要发布的交付物描述文件来请求从稳定分支发布。发布团队将审查请求并提供有关版本号的反馈。如果稳定发布是由稳定维护团队请求的，则应由 PTL 或发布联络人确认，以确保开发团队了解即将发生的更改。

通过向此仓库提交补丁来准备发布请求。

• 始终将新发布添加到正在编辑的列表的末尾。版本号将重新排序以进行显示。

• 始终为新发布选择新的版本号。我们不会更新先前标记发布的的内容，因为这会混淆已经下载了这些软件包的用户。

• 在选择版本号时，请确保遵循语义化版本控制规则 semver。

  特别是，如果本次发布中包含的更改需要更高版本的依赖项，则应增加 minor 版本。

  注意

  此规则的例外情况是，当项目的版本在稳定分支中被固定在 minor 版本之间时。在这些情况下，我们经常发布全局需求同步，版本号为 patch 版本，以修复目标分支，例如 stable/juno，但不增加 minor 版本，以避免在不同的分支中使用它，例如 stable/kilo。来自 stable-maint-core 团队的成员应在批准此类更改之前进行 +1 确认。

• 不要人为地增加版本号以保持交付物之间的一致版本。我们预计兼容交付物的版本会随着时间的推移而漂移，并决定通过使用其他工具来记录哪些软件包组合在一起，以接受这一点。

  http://lists.openstack.org/pipermail/openstack-dev/2015-June/065992.html

  如果两个构建工件始终需要具有相同的版本号，那么强烈暗示它们是同一个交付物的一部分，不应单独发布。

• 对于不稳定早期版本和原型，从 0.1.0 开始。对于第一个可用于生产的发布，切换到 1.0.0。不要使用与现有相关交付物使用的版本相同的数字发布交付物的第一个版本。这会使消费者对新交付物的成熟度以及他们应该在哪里找到具有较低数字的“旧”版本（这些版本不存在）感到困惑。

• 将提交消息的第一行（摘要）设置为请求的软件包名称和版本。

• 如果您不是发布联络人或 PTL，请让项目的 PTL 确认请求，并进行 +1 确认。

• 不要使用 zuul 的“Depends-On”功能来使发布请求依赖于项目中合并另一个补丁。依赖管理在发布检查作业中无法正常工作，并且验证器要求在您的交付物文件中列出的补丁实际上合并到正确的分支中。

• 不要提交多个依赖补丁以进行多个发布。补丁系列包含多个发布意味着发布团队无法正确确定处理它们的优先级。在里程碑周，优先处理里程碑发布。来自稳定分支、独立项目和其他类型发布的发布将在稍后处理。如果您的里程碑发布请求依赖于一个被降级的请求，您可能会错过截止日期。

• 对于使用带有 RC 的发布模型的项目，应一起提交 RC1 标签和稳定分支。

使用 new-release 命令¶

releases 仓库包含几个工具，可以更轻松地使用数据文件。例如，new-release 命令会根据命令行给出的语义化版本控制信息计算新的版本号，并确定适当分支的 HEAD 的 SHA。

使用 venv tox 环境来运行该工具，如下所示

$ tox -e venv -- new-release SERIES DELIVERABLE TYPE

SERIES 值应为发布系列，例如“pike”。

DELIVERABLE 值应为交付物名称，例如“oslo.config”或“cinder”。

TYPE 值应为以下其中之一

bugfix – 对于仅包含错误修复的发布。

feature – 对于包含新功能、新依赖项或对依赖项的最小允许版本更改的发布。

major – 对于包含向后不兼容变更的发布版本。

milestone – 对于基于日期的里程碑标签。

rc – 对于发布候选版本。

new-series 会自动为第一个发布候选版本包含一个稳定的分支。

如果 pike 系列 cinder 的最新发布版本是 11.0.0.0b3，那么运行

$ tox -e venv -- new-release pike cinder rc

会检测到这是第一个发布候选版本，并使用新的发布版本和新的稳定分支更新文件 deliverables/pike/cinder.yaml。

如果一个 deliverable 包含多个 git 仓库，除非它们的 HEAD 版本与该仓库的最新发布版本匹配，否则所有仓库都将包含在新发布版本中。在这种情况下，要重新标记，请使用 --force 选项。

使用 --stable-branch 选项也可以为新发布版本创建一个稳定分支。遵循 cycle-with-rc 发布模型的项目会在它们的第一个发布候选版本上自动获得一个新的稳定分支。

请求分支¶

项目的 PTL 或发布联络人可以通过向此仓库提交补丁，将必要的分支元数据添加到描述要发布的 deliverable 的文件中来请求新分支。发布团队将审核请求并提供关于分支点以及可能分支名称的反馈。

通过向此仓库提交补丁来准备分支请求。

• 对于使用带有 RC 的发布模型的项目，应一起提交 RC1 标签和稳定分支。

• 始终将新分支添加到正在编辑的文件末尾的列表中。

• 分支应使用以下标准前缀

  stable/ – 用于稳定系列

  feature/ – 用于临时功能分支

• stable/ 分支名称必须与有效的系列名称匹配。

• 如果您不是发布联络人或 PTL，请让项目的 PTL 确认请求，并进行 +1 确认。

• 不要使用 zuul 的“Depends-On”功能来使分支请求依赖于项目中另一个补丁的合并。依赖管理在发布检查作业中无法正常工作，并且验证器要求你在 deliverable 文件中列出的补丁实际上合并到正确的分支中。

发布批准¶

发布将在冻结周、已知存在 gate 问题的时期或发布会引入不必要的稳定性问题时被拒绝。如果在一周的后期进行的发布，除非有紧急需求（例如 gate 失败或安全问题），否则可能会延迟到下一周初。

谁负责发布？¶

发布团队负责通过良好的版本号选择来清晰地表明发布版本中更改的性质。

项目团队负责理解新发布版本对使用项目的含义，并确保发布版本不会破坏其他项目。如果发生破坏，项目团队负责采取必要的纠正措施。

Deliverable 文件¶

使用 cycle_with_intermediary 或 cycle_with_milestones 的项目的 deliverable 仓库应放置在其各自的发布版本中，位于 deliverables 目录中。使用独立发布模型的项目的 deliverable 仓库应放置在 deliverables/_independent 目录中。

对于一组 deliverable 项目，我们使用每个发布系列一个 YAML 文件来保存该 deliverable 的所有发布版本和分支的所有元数据。对于每个 deliverable，我们需要跟踪

• launchpad 项目名称（例如 oslo.config）或 storyboard 项目 ID（例如 760）

• 系列（Kilo、Liberty 等）

• 正在使用的发布模型

• 对于每个仓库

  • 名称（例如 openstack/oslo.config）

  • 要标记的提交的哈希值

  • 要使用的版本号

• 将在 releases.openstack.org/$SERIES/highlights.html 上发布的 cycle 亮点（可选，仅适用于 cycle_with_intermediary 和 cycle_with_rc 项目）

• 所有分支的起始点

我们跟踪 deliverable 所有发布版本的元数据，以便我们可以渲染一组发布历史记录文档。

文件应基于要标记的 deliverable 命名，因此来自 openstack/oslo.config 仓库的 liberty 的发布版本将在 openstack/releases 中名为 deliverables/liberty/oslo.config.yaml 的文件中。来自 stable/kilo 分支的相同 deliverable 的发布版本将由 deliverables/kilo/oslo.config.yaml 描述。

Deliverables 文件模式¶

deliverable 文件的顶层是一个映射，其键为

team

拥有 deliverable 的团队的名称，如治理仓库数据文件中所列。

launchpad

launchpad 项目的 slug 名称，适用于 URL。 （对于使用 storyboard 的项目不需要。）

storyboard

storyboard 项目的 ID，适用于 URL 和 API 调用。 （对于使用 launchpad 的项目不需要。）

release-notes

发布说明的 URL 或 URL，适用于该系列的 deliverable。

包含单个仓库的 Deliverables 应该只包含指向该仓库的说明的 URL。由多个仓库组成的 Deliverables 应该使用哈希将每个仓库名称映射到其说明 URL。

include-pypi-link

要么 true 要么 false，指示发布公告是否应包含指向 PyPI 上软件包的链接。默认值为 false。

release-model

确定交付项使用的发布模型。有关有效模型的描述，请参阅文档的参考部分。

type

根据交付项的功能对其进行分类。有关有效交付项类型的描述，请参阅文档的参考部分。

artifact-link-mode

描述如何链接到项目生成的工件。默认值为 tarball。有效值为

tarball

自动生成指向 tarballs.openstack.org 上的特定版本文件的链接。

none

不链接到任何内容，仅显示版本号。

repository-settings

特殊设置到每个仓库行为的映射，按仓库名称键控。

flags

附加到仓库的标志列表。

no-artifact-build-job

此仓库没有构建工件的作业，但仍应进行标记。

retired

此仓库不再使用，但存在于交付项的旧版本中。

pypi-name

在 pypi.python.org 上的交付项的可选名称。仅当 PyPI 上的名称与 python setup.py --name 的规范化输出不匹配时（例如，使用大写字母“DragonFlow”而不是“dragonflow”），才需要此值。

tarball-base

发布创建的 tarball 的可选名称。如果未提供值，则默认使用仓库基本名称或在 releases 下特定发布条目中设置的覆盖值。

release-type

此（可选）键设置版本号的验证级别。

python-service

默认：强制执行发布中 3 位数字的语义化版本号，并允许常见的 alpha、beta 和 dev 版本。这应该适用于大多数 OpenStack 组件发布需求。

python-pypi

类似于 python-service，但要求作业将组件发布到 Python 包索引 (PyPI)。

xstatic

允许符合 xstatic 包指南和要求的更灵活的版本控制。

fuel

Fuel 项目管理自己的软件包。

puppet

所有 puppet 模块都应使用此选项。如果未指定 release-type，并且验证作业可以确定模块是 puppet 模块，则假定 release-type 为 puppet。

nodejs

所有 nodejs 模块都应使用此选项。如果未指定 release-type，并且验证作业可以确定模块是 nodejs 模块，则假定 release-type 为 nodejs。

neutron

对于使用 PyPI 发布变体来安装 neutron 以构建软件包的项目。通常由 neutron 插件使用。

horizon

对于使用 PyPI 发布变体来安装 horizon 以构建软件包的项目。通常由 horizon 插件使用。

releases

交付项的发布列表。

stable-branch-type

此（可选）键设置与每个稳定分支关联的位置的验证。

std

默认：要求从标记的发布创建稳定分支。这是大多数项目的正确分支类型。

位置必须是现有的版本标签，或者是发布列表下最近添加的版本号（允许同时提交标签和分支）。与版本关联的所有仓库（由交付项文件标识）将使用给定的名称从该版本分支。

std-with-versions

此模式的含义与 std 分支类型相同，此外还可以创建基于版本的分支。

这些基于版本的分支是短期稳定分支，其名称为主要和次要版本号（例如 bugfix/3.1）。这主要用于 Ironic 发布。

tagless

此模式要求稳定分支位置是仓库名称与现有提交（由哈希指定）之间的映射。此模式仅应用于不标记发布的项目，例如 devstack 和 grenade。

upstream

稳定分支名称跟踪上游发布名称，而不是 OpenStack 系列名称。

none

此模式表示交付项不应有稳定分支。这用于特定的交付项，例如 tempest。

cycle-highlights

描述您希望在此发布周期中重点介绍的一些顶级新功能或更改的纯文本项目符号列表。支持最少的 RST 标记。这些亮点将按团队编译并在 releases.openstack.org/$SERIES/highlights.html 上发布。

branches

交付项的分支列表。

每个 release 条目都是一个映射，其中包含键

version

应用于所有成员项目的发布标签。

projects

构成该发布交付项的所有项目的列表。

highlights

要在发布说明电子邮件中包含的可选消息。 (使用 | 表示多行、预格式化的消息。)

flags

附加到发布的标志列表。

forced

此发布由发布团队应用，而不是项目团队。

skipped-sig

此独立发布早于 Ocata 周期，未生成任何签名。生成网站页面时应跳过签名链接显示。

在 projects 列表中，每个条目都是一个映射，其中包含键

repo

git.openstack.org 上的仓库名称。

hash

要接收版本标签的提交的 SHA1 哈希值。

tarball-base

发布创建的 tarball 的可选名称。如果未提供值，则默认使用 repository-settings 值（如果已设置），否则使用仓库基本名称。

在 branches 列表中，每个条目都是一个映射，其中包含键

name

分支名称。

location

位置值取决于名称。

如果分支名称以 stable/ 开头，则 location 值取决于 stable-branch-type 设置。

如果分支名称以 feature/ 开头，则 location 必须是目标仓库名称和目标仓库中已存在提交的 SHA 之间的映射。

示例¶

例如，deliverables/liberty/oslo.config.yaml 的一个版本可能包含

---
launchpad: oslo.config
branches:
  - name: feature/random-feature-work
    location:
      openstack/oslo.config: 02a86d2eefeda5144ea8c39657aed24b8b0c9a39
releases:
  - version: 1.12.0
    projects:
      - repo: openstack/oslo.config
        hash: 02a86d2eefeda5144ea8c39657aed24b8b0c9a39

然后对于后续发布，它将被更新为包含

---
launchpad: oslo.config
branches:
  - name: feature/random-feature-work
    location:
      openstack/oslo.config: 02a86d2eefeda5144ea8c39657aed24b8b0c9a39
  - name: stable/newton
    location: 1.12.1
releases:
  - version: 1.12.0
    projects:
      - repo: openstack/oslo.config
        hash: 02a86d2eefeda5144ea8c39657aed24b8b0c9a39
  - version: 1.12.1
    projects:
      - repo: openstack/oslo.config
        hash: 0c9113f68285f7b55ca01f0bbb5ce6cddada5023
    highlights: |
       This release includes the change to stop importing
       from the 'oslo' namespace package.

对于具有多个仓库的 deliverables，项目列表将包含所有这些仓库。例如，Neutron deliverable 可以由 deliverables/mitaka/neutron.yaml 描述，其中包含

---
launchpad: neutron
release-notes:
  openstack/neutron: https://docs.openstack.org/releasenotes/neutron/mitaka.html
  openstack/neutron-lbaas: https://docs.openstack.org/releasenotes/neutron-lbaas/mitaka.html
  openstack/neutron-fwaas: https://docs.openstack.org/releasenotes/neutron-fwaas/mitaka.html
  openstack/neutron-vpnaas: https://docs.openstack.org/releasenotes/neutron-vpnaas/mitaka.html
releases:
 - version: 8.0.0
   projects:
     - repo: openstack/neutron
       hash: 3213eb124e40b130e174ac3a91067e2b196788dd
     - repo: openstack/neutron-fwaas
       hash: ab5622891e2b1a7631f97471f55ffb9b5235e5ee
     - repo: openstack/neutron-lbaas
       hash: 19b18f05037dae4bbbada848aae6421da18ab490
     - repo: openstack/neutron-vpnaas
       hash: a1b12601a64a2359b2224fd4406c5db008484700

为了允许对没有构建工件的仓库进行标记，请设置 no-artifact-build-job 标志。

---
launchpad: astara
repository-settings:
  openstack/astara-appliance:
    flags:
      - no-artifact-build-job
releases:
  - version: 9.0.0.0b1
    projects:
      - repo: openstack/astara-appliance
        hash: c21a64ea7b3b0fbdab8592afecdd31d9b8e64a6a

辅助工具¶

为了帮助构建这些文件，该仓库包含各种基于命令行工具。要安装这些工具，只需在此仓库目录中运行 pip install . 即可。

• new-release 接受参数来描述一个新发布，并更新 deliverable 文件，自动计算版本号

• edit-deliverable 接受参数来更新单个 deliverable 文件的内容

• list-changes 列出给定发布文件中的更改。

• interactive-release 以向导式问题集的形式，生成给定项目或一组项目的新的或更新的发布。

• missing-releases 扫描 deliverable 文件，并验证所有应该手动标记的发布是否已标记

• init-series 基于上一个发布，初始化一个新的 deliverable 目录，并带有 stub 文件。

• get-contacts 加载治理和联络数据，以打印给定团队的联系方式

tox -e aclmanager -- --series newton acls ~/branches/openstack-infra/project-config

tox -e aclmanager -- groups pre_release ttx

./tools/add_reviewers.sh ussuri-rc

tox -e check_approval -- 695375

./tools/process_auto_releases.sh ussuri $(list-deliverables --unreleased --series ussuri)

tox -e venv -- list-deliverables --unreleased --series ussuri > deliverables.log
vi deliverables.log  # edit contents as needed
./tools/process_auto_releases.sh ussuri $(cat deliverables.log)

tools/add_release_note_links.sh ussuri

$ tools/search_emails.py

$ tools/search_emails.py --starting-date 2020-04-01 --ending-date 2020-4-1

$ tools/search_emails.py --authors "Herve Beraud" "Sean McGinnis"

$ tools/search_emails.py --starting-date 2020-04-01 --ending-date 2020-4-1 --authors "Herve Beraud" "Sean McGinnis"

$ tools/search_emails.py --topic ".?\[release\] Release countdown.*" --starting-date 2020-5-1

$ tools/search_emails.py --topic ".?openstack/watcher.*" --mailing-list http://lists.openstack.org/pipermail/
release-job-failures/ --starting-date 2016-6-1

tools/list_eol_stale_branches.sh

GERRIT_USER=<gerrit_user_name> tools/list_eol_stale_branches.sh

tools/list_eom_stale_branches.sh <series>

tools/abandon_patches_on_branch.sh yoga $(list-deliverables --series yoga)

tools/list_unbranched_projects.sh

tox -e membership_freeze_test -- stein ~/branches/governance/reference/projects.yaml

tox -e membership_freeze_test -- stein ~/branches/governance/reference/projects.yaml --url --distgit https://github.com/

tox -e venv -- propose-final-releases newton ocata

tox -e venv -- propose-library-branches
tox -e venv -- propose-library-branches pike

./tools/list_unreleased_changes.sh master openstack/oslo.config

./tools/list_unreleased_changes_for_team.sh stein oslo

./list_stable_unreleased_changes.sh stable/liberty

./list_unreleased_changes.sh stable/liberty $(list-deliverables --repos --series liberty)

tox -e venv -- list-eom-series