跳转到： 导航, 搜索

Oslo/创建新库

开始之前

这是一个漫长的过程。之所以漫长，是因为它必须如此，而不是因为我们希望如此。如果您遵循它，一切都会很好。

重要的是您按照给定的顺序执行所有步骤。不要跳过任何步骤。不要尝试并行执行操作。不要随意跳转。

项目创建者指南

项目创建者指南 包含创建仓库的许多细节。它由基础设施团队维护，并且应该与当前流程保持最新。

在继续之前阅读该指南。以下某些步骤将参考该指南中的部分，您需要同时使用这两份文档才能完成此过程。

规范

Oslo 团队使用规范流程来审查大型更改的计划，例如毕业，该流程与其他 OpenStack 团队的功能审查流程通用。为了准备毕业或采用库，您需要提交一个规范。

蓝图

首先，在 launchpad 上的 oslo-incubator 仓库中创建一个蓝图。将蓝图命名为 graduate-oslo-foo，将 foo 替换为库的名称。

规范

在 openstack/oslo-specs 仓库中，复制 specs/graduation-template.rst 以使用发布代码名称目录下的您的蓝图名称创建一个新的规范。例如，specs/kilo/graduate-oslo-reports.rst。编辑新文件，填写详细信息，然后像任何其他代码审查一样提交它进行审查。

规范模板包含稍后本文中提出的问题，您需要在此时提供答案。这是对前面提到的“不要提前阅读或跳过”规则的唯一例外。收集所有需要填写规范的信息。

选择名称

除了 项目创建者指南 中描述的规则之外，Oslo 库目前使用三种命名方案

  1. oslo.something - 用于 OpenStack 项目的生产运行时依赖项。将 oslo. 命名空间用于任何其他类型的包会导致冲突，因为 Python 和 Pip 处理命名空间包的方式存在一些限制。
  2. oslosomething - 用于 OpenStack 项目的非生产或非运行时依赖项。如果您计划使用这样的名称，请先与 Oslo 团队讨论 - 我们不确定是否喜欢这种命名方案，并且可能会建议替代方案。
  3. something - 用于可能在 OpenStack 之外普遍有用的库。注意：您应该验证您提出的名称是否未在 Python 包索引 (https://pypi.python.org/pypi) 上使用。

从孵化器毕业

Oslo 库的新来源有三个

  1. 正在毕业的孵化代码。
  2. 一个全新的库。
  3. 我们正在采用的现有库。

本文的大部分内容涵盖孵化代码。全新的和现有的库可以跳过到下面的“将仓库导入 CI 系统”。

毕业是一个多步骤的过程。它不复杂，但有很多容易遗漏的细节。请小心谨慎。

使用孵化代码的目标是从孵化器中提取它，并保留其所有历史记录，并将结果作为新库发布。这意味着必须在 gerrit 之外创建一个新的仓库，然后导入它，以避免必须重新审查所有现有的提交集。该过程的大部分是自动化的，但不可避免地会有些手动步骤 - 特别是确保测试正常工作。

在按照 项目创建者指南 中的说明之前执行本节中的步骤，然后在将项目添加到 gerrit 时使用您创建的仓库作为“上游”值。

更新孵化器中的状态

更新 oslo-incubator/MAINTAINERS

将模块的状态设置为“毕业”。

验证所有正确的名称和联系方式是否存在。

如果 openstack/common 下的子包中只有一些模块正在毕业，请向这些文件中添加注释，明确指出在毕业期间不应修改它们。

移除对 oslo 日志代码的依赖

对于将要毕业的文件，提交对 oslo-incubator 的更改，将其切换为使用标准 Python 日志，而不是可能使用的任何 Oslo 日志（来自孵化器或 oslo.log）。日志代码现在能够将上下文信息添加到所有第三方库日志消息，因此让毕业的 Oslo 库的行为与任何其他第三方库相同是有意义的。

我们希望在创建新仓库之前完成此操作，以便我们可以审查更改，但不必引入将立即删除的日志依赖项。这对于继续使用孵化器版本文件的任何人来说也不会有问题。

提取干净的历史记录副本

首先，签出 oslo-incubator 的一个副本以用于运行该工具

 cd /tmp
 mkdir graduation
 cd graduation
 git clone git://git.openstack.org/openstack/oslo-incubator

现在克隆第二个要编辑的仓库

 git clone git://git.openstack.org/openstack/oslo-incubator oslo.i18n

毕业脚本通过编辑当前仓库的 git 历史记录来工作，删除不接触您想要保留的文件中的提交。然后，它重新排列结果文件并设置 oslo 包命名空间。为了执行这些操作，它需要知道正在创建的新库的名称以及您希望保留的文件的名称。

 cd oslo.i18n
 ../oslo-incubator/tools/graduate.sh i18n openstack/common/gettextutils.py tests/unit/test_gettext.py

该脚本相当密集地进行 I/O 操作，并且需要一段时间才能运行。它将所有输出记录到 /tmp/oslo-graduate.XXXX/output.log，并且其他临时文件保存在同一目录中。

手动修复

不可能完全自动化重新组织库代码并确保其正常工作的过程，因此接下来需要执行几个手动任务。

  1. 添加缺少的依赖项
  2. 修复当前仓库中由于文件重命名而导致的损坏的导入
  3. 确保测试运行 - 不仅仅是确保 tox 通过，还要确保它实际上正在运行测试（移动文件会导致有时会静默地中断）
  4. 使用现在使用孵化器版本的项目测试新库

此时，进行尽可能少的更改，只是为了使测试作业通过。对 API 的较大更改应通过正常审查流程进行。

允许的更改包括

  • 损坏的导入
  • PEP8/测试失败
  • 同步孵化器中的依赖项

不要

  • 启用新的测试或 PEP8 检查
  • 添加孵化代码中以前未使用的新的库依赖项

同步孵化器中的所需工具

Oslo 的所有库都通用的某些工具位于 oslo-incubator 中。在将其导入之前，需要将这些工具同步到新仓库中。

  1. 克隆 oslo-incubator 仓库的副本
  2. 将适当的模块和脚本添加到 /path/to/newproject/openstack-common.conf
  3. 在 oslo-incubator 中，运行：./update.sh /path/to/newproject
  4. 在 /path/to/newproject 中，添加新文件并提交任何更改

发布您的结果

当您拥有干净的库版本时，将其发布到公共 git 仓库（例如，在 github 上）。该项目历史记录的副本将在后续步骤中使用。

获得 Oslo 团队的批准

在将库导入 OpenStack CI 系统之前，将消息发布到 openstack-dev 邮件列表，要求 Oslo 团队审查公共仓库。

将仓库添加到 CI 系统

按照 项目创建者指南 中的步骤导入您的新仓库，在将项目添加到 gerrit 时使用您创建的仓库作为“上游”值。

Launchpad 设置

项目创建者指南描述了 设置新 Launchpad 项目的步骤。

大多数 Oslo 项目使用 Oslo Drivers 团队作为“维护者”和“驱动程序”。拥有大量非 Oslo 核心团队成员的库可以设置自己的维护者/驱动程序团队，但应将 oslo-drivers 作为子团队（请参阅 oslo.vmware 和 oslo.policy 以获取示例）。

将项目添加到 Oslo 库列表

编辑 Oslo wiki 页面，将新项目添加到我们维护的库列表中。包括简短的描述。

验证 Gerrit 和测试作业是否正常工作

下一步是验证您是否可以提交仓库的更改请求，测试是否成功运行，您是否有权批准更改，以及发布过程是否有效。

准备初始发布

使您的库有用

在进一步操作之前，使库执行一些有用的操作。

如果您正在导入具有功能的现有库，则可以继续。

如果您正在创建一个全新的库，请添加一些代码和测试以提供一些对另一个项目有用的最小功能。

提供基本文档

更新 README.rst 文件，以包含描述新库的一段话。

更新其余文档，提供有关公共 API、采用技巧等信息。

标记发布

为了验证发布机制是否有效，将签名的标签推送到“gerrit”远程仓库。使用尽可能小的版本号。如果这是第一个发布版本，请使用“0.1.0”。如果库存在其他发布版本，请使用 Oslo/VersioningPolicy 选择适当的下一个版本号。

运行

 git tag -s -m "descriptive message" $version
 git push gerrit $version

等待一段时间，让 pypi 作业运行并发布版本。

如果您需要检查日志，可以使用“git-os-job”插件 (https://pypi.python.org/pypi/git-os-job)

 git os-job $version

移除孵化代码

在成功发布新毕业的库的第一个版本后，应从孵化器中移除模块。在此阶段，关键的错误修复将合并到孵化器版本代码的先前稳定分支中。新功能和次要错误应在已发布库中修复，并且应努力让下游项目使用该库。

避免重写孵化器 update.py 中的引用

oslo-incubator/update.py 脚本重写对“oslo”的引用，以使用接收代码副本的项目的名称。现在代码不再从孵化器中消耗，任何保留在孵化器中的引用都需要引用已发布库。通过将它添加到 _copy_file() 函数中已知的库列表中来修改 update.py，以防止重写引用。查找“for oslo_module in ...”大约在第 158 行。

允许其他 OpenStack 项目使用您的库

OpenStack 项目共享一个通用的全局需求列表，以便所有组件可以安装在同一系统上。为了允许其他项目使用您的库，您需要更新该需求列表。

更新全局需求列表

签出 openstack/requirements git 仓库并修改 global-requirements.txt 以

  1. 添加新库
  2. 添加库的所有直接依赖项（如果尚未列出）

记录迁移过程

如果新库是从已经通过孵化器使用的代码毕业的，请创建一个简短的描述，说明采用库所需的更改类型。例如，如果 API 已更改或需要常见的模式来创建集成模块，请描述它并提供一个示例。这应该是一个 Oslo 下的 wiki 页面，名称类似于 Oslo/MigratingTo-project-name（将此保留在 wiki 中将使项目联络员更容易添加提示和注释）。

在 Oslo#Libraries 下链接到文档。

更新 devstack 以启用门控测试

devstack 门控作业从源代码安装所有 OpenStack 项目，以便测试适当的 git 修订版（head 或合并队列中的修订版）。为了将新库包含在这些测试中，需要在 devstack 门控包装脚本中包含它。对于外部开发人员来说，为了使该功能正常工作，需要在 Oslo 部分的 devstack 中添加该项目。

签出 openstack-dev/devstack。

编辑 lib/oslo 以添加一个变量，定义源代码应该去哪里

 NEWPROJECT_DIR=$DEST/newproject

编辑 lib/oslo 中的“install_oslo()”函数，以添加签出仓库的命令。需要按顺序安装库，以便首先安装较低级别的包（这避免了从包中安装库，然后从源代码重新安装库）

 function install_oslo() {
   ...
   git_clone $NEWPROJECT_REPO $NEWPROJECT_DIR $NEWPROJECT_BRANCH
   setup_develop $NEWPROJECT_DIR
   ...
 }

编辑 stackrc 以添加配置新库所需的其他变量

 # new-project
 NEWPROJECT_REPO=${NEWPROJECT_REPO:-${GIT_BASE}/openstack/new-project.git}
 NEWPROJECT_BRANCH=${NEWPROJECT_BRANCH:-master}

等待这些更改被接受后继续。

添加开发者文档链接

更新 https://docs.openstack.org/developer/openstack-projects.html 页面，添加指向您文档的链接。方法是检出 openstack/openstack-manuals 仓库并编辑 www/developer/openstack-projects.html。

更新消耗项目

现在该库已完全集成到 OpenStack 测试基础设施的其余部分，项目可以安全地更新以使用它。向 openstack-dev 邮件列表发送电子邮件，通知社区该库可用并可供使用。

与每个项目的开发团队协调，确定他们在开发周期中可以与您合作更新并审查必要更改的时间。 联络人 可以协助完成此操作。

使用发布周期的 etherpad 跟踪采用进度。例如，https://etherpad.openstack.org/p/juno-oslo-adoption-status

其他项目的 PTL 可能会要求蓝图或错误报告来跟踪其项目中的迁移工作。使用他们习惯的流程。

尝试将其他项目中更改的主题设置为引用您的毕业蓝图，无论是在命令行上还是在 git 提交消息中引用蓝图。这使得跟踪所有仓库中的蓝图工作更加容易。

检查清单

您可以将此任务列表粘贴到蓝图的“工作项”部分，以便更轻松地跟踪步骤。

Create Launchpad project: TODO
Create Launchpad bug tracker: TODO
Create Launchpad blueprint tracker: TODO
Change owner of Launchpad project: TODO
Give openstackci Owner permissions on PyPI: TODO
Create Initial Repository: TODO
Update MAINTAINERS in incubator with status and name: TODO
Remove Oslo logging calls in incubator: TODO
Fix the output of graduate.sh: TODO
Sync tools from incubator: TODO
Publish git repo: TODO
Oslo team review new repository: TODO
openstack/governance reference/programs.yaml: TODO
openstack-infra/project-config - gerrit/projects.yaml: TODO
openstack-infra/project-config - gerrit/acls/openstack/project-name.config: TODO
openstack-infra/project-config - jenkins/jobs/projects.yaml: TODO
openstack-infra/project-config - zuul/layout.yaml: TODO
openstack-infra/project-config - gerritbot/channels.yaml: TODO
Update Gerrit Groups and ACLs: TODO
openstack-infra/devstack-gate - devstack-vm-gate-wrap.sh: TODO
openstack/requirements projects.txt: TODO
Update list of libraries on Oslo wiki page: TODO
Make the library do something: TODO
Update the README.rst: TODO
Tag a release: TODO
Remove graduated code from oslo-incubator: TODO
Update oslo-incubator/update.py to not rewrite references to the library: TODO
openstack/requirements - global-requirements.txt: TODO
Document Migration Process: TODO
openstack-dev/devstack - lib/oslo: TODO
openstack-dev/devstack - stackrc: TODO
Update project list on docs.openstack.org: TODO
从 "https://wiki.openstack.org/w/index.php?title=Oslo/CreatingANewLibrary&oldid=71643" 检索