Watcher/贡献
目录
开始之前
你需要执行一个 OpenStack CLA。在你可以向我们的 Watcher Repo 提交评审之前,这是必需的。有关如何准备贡献的信息,请参阅 How To Contribute wiki 页面。
注册 OpenStack 开发邮件列表
前往 OpenStack Dev 邮件列表,在“订阅 OpenStack-dev”下填写字段,然后点击订阅。
了解 Gerrit
请务必阅读 开发者指南,了解如何提交你的提交以供评审,以便将其合并到 Watcher 代码库中。
如果你没有 Gerrit 用户名或记不住它,请在此处验证并配置它:https://review.openstack.org/#/settings/
在下面的 https://wiki.openstack.org/wiki/Watcher/Contributing#Setting_up_your_git_review_settings 和 https://wiki.openstack.org/wiki/Watcher/Contributing#Set_up_your_local_branch 部分的“git review -s”命令中,请记住它...
你还需要上传一个专门用于 Gerrit 的 SSH 公钥:https://review.openstack.org/#/settings/ssh-keys
设置你的 git review 设置
不熟悉 git?尝试这个 15 分钟的高级交互式 Git 演示 GitHub Demo
需要复习一下 git?从源头下载 git 参考:GitHub Git Cheat Sheet
然后
git config --global user.name "Firstname Lastname" git config --global user.email "your_email@youremail.com"
如果你的 Launchpad 和 Gerrit 用户名相同
git config --global gitreview.username "your_launchpad_username"
如果你的 Launchpad 和 Gerrit 用户名不相同
git config --global gitreview.username "your_gerrit_username"
检查你的 git 配置
git config --list
安装 git-review
在 Ubuntu、MacOSx 或大多数其他类 Unix 系统上,它就像这样简单
pip install git-review
其他安装选项详见 开发者指南。现在你可以检出 Watcher 代码并开始使用它了
Blueprints
蓝图应该用于提出设计并获得批准。
你应该将你的蓝图链接到 Watcher-specs 仓库 中的规范文件,并在蓝图中“设计”字段中使用规范批准来跟踪规范批准。
你应该遵循这个过程
- 通过访问 launchpad.net/watcher 页面并点击“注册蓝图”来在 Launchpad 中注册你的蓝图
- 将设计规范上传到 watcher-specs 的“specs/<release>”文件夹中
- 它应该基于 specs/<release>-template.rst,有关更多详细信息,请参阅模板中的说明
- 它应该提交到当前版本的批准文件夹中,例如 specs/mitaka/approved
- 文件名应与 Launchpad URL 匹配,例如 URL 为 https://blueprints.launchpad.net/watcher-specs/+spec/awesome-thing 应该命名为 awesome-thing.rst
- 通过 Gerrit 提交您的补丁以进行审查,以通常的方式:开发工作流程
- 在每个版本的结束时,未完成的规范将被删除
- 你需要重新提交下一个版本
- Watcher 驱动程序会将蓝图状态设置为
- "New" - 提交了描述但尚未评审
- "Discussion" - 描述已评审,需要改进
- "Drafting" - 描述已评审,规范正在 Gerrit 中评审
- "Approved" - 规范已讨论并合并,可以开始实施
- Watcher 驱动程序还会根据分配者的建议设置目标里程碑
- 分配者会保持里程碑和实施状态的更新,以反映进度
- 当工作完成时,分配者会将实施状态设置为“Implemented”
注意:自动化脚本将确保未批准(未优先排序)蓝图上未设置里程碑目标。
你的第一次提交
设置你的本地分支
git clone git://git.openstack.org/openstack/watcher cd watcher git checkout -b [branch name (see below...)] git review -s
你的分支名称 '必须' 与蓝图或 bug 相关。这将在 Gerrit 的“topic”字段中反映出来。
请使用以下约定来命名你的分支
- 对于蓝图,使用 "bp/<short-bp-name>"
- 对于 bug,使用 "bug/<bug-id>"
如果你在运行“git review -s”命令时收到以下错误
We don't know where your gerrit is. Please manually create a remote named "gerrit" and try again.
执行以下操作(将 <your gerrit username> 替换为你的特定 Gerrit 用户名...)
git remote add gerrit ssh://<your gerrit username>@review.openstack.org:29418/openstack/watcher.git git review -s
如果你在运行“git review -s”命令时收到以下错误
Agent admitted failure to sign using the key
请参阅此支持页面:https://help.github.com/articles/error-agent-admitted-failure-to-sign/
编写一些优秀的的代码
此时你可以编写你的代码并将其推送到 Gerrit 以供评审。
git add <list of files you added/changed>
如果你在上一节中提交了一个 bug,请确保在提交消息中添加 bug 链接。
每个提交行都应符合 OpenStack 消息结构指南,请参见 https://wiki.openstack.org/wiki/GitCommitMessages#Summary_of_Git_commit_message_structure
亮点包括
- 行尾不应有空格
- 行的顺序很重要
- 提交消息的第一行应 <=50 个字符
- 下一行是空白
- 下一部分是对提交的详细描述(行必须 <= 72 个字符)
- 下一行是空白
- 接下来的行包含 bug 号码或蓝图名称,以及其他信息
- Closes-Bug/Partial-Bug/Related-Bug: 井号 (#) 后跟 bug 号码(例如 Closes-Bug: #111111)
- Blueprint: 蓝图名称(例如,“Implements: blueprint libvirt-xml-cpu-model”)
- 提交了 git review 后,将追加一个带有 Gerrit 生成的标识符的“Change-Id:”行
一个提交消息示例
Adjust Gerrit workflow Link <blank_line> The Gerrit workflow link in the previous version is no longer valid. This patch updates documentation to the current link. <blank_line> Closes-Bug: #<launchpad_bug_number> Change-Id: <generated_by_gerrit>
这只是一个例子。你可以在 https://wiki.openstack.org/wiki/GitCommitMessages 找到有关提交消息的更多详细信息
一旦你整理了以上信息,执行以下命令输入它
git commit -a
然后,提交评审
git review -v
此时,你的代码将由 OpenStack 自动测试框架以及项目中的同行进行评审。
要对尚未完成的更改获得早期反馈,你可以提交它并将其标记为“Work in Progress”(WIP)。为此,你应该转到 Gerrit,并对你自己的更改进行代码评审,同时将“Workflow”投票设置为“-1”,这将把更改标记为 WIP。
如果你想响应反馈来修改评审系统中的补丁集,首先返回到你的开发区域
cd ~/watcher [or wherever that is for your setup...]
下载更改。请务必使用评审编号,而不是 bug 编号
git review -d <review number>
然后,进行更改,并使用上述提交指南更新提交消息
git commit --amend
然后
git review -v
在评审批准后,你的代码将被自动合并。
需要一个开始编写代码的地方吗?
你还可以通过查看当前 Watcher 单元测试的覆盖率并改进代码覆盖率来为代码质量做出贡献。
你可以使用以下命令检查当前检出的代码的覆盖率
$ tox -e cover
这将生成一个 cover 目录,提供 HTML 输出,显示代码覆盖率以及未覆盖的特定代码行。
如何解决合并冲突
如果另一个补丁更改了与你的补丁相同的代码行,并且它在你的补丁之前被合并,你的补丁可能会在 Gerrit URL https://review.openstack.org/NNNNN 中显示为红色 patch in merge conflict 状态。如果发生这种情况,以下是如何解决它。你需要来自 Gerrit URL 的补丁编号来使你的 rebase 成为先前评审的修订版。
git clone https://github.com/openstack/watcher cd watcher git review -d NNNNN git rebase master
现在编辑所有包含合并冲突的文件以解决它们,使代码看起来既包含最近合并的代码,又包含你自己的代码。然后 git add 你编辑的每个文件。
git add path/to/file/you/edited git rebase --continue git review -v
这将使用原始提交消息重新提交你的补丁,并将带有合并修复的新补丁集作为 rebase 代码。
错误
识别 Bug
发现了一个 Bug?在此处报告:https://launchpad.net/watcher
- 点击 Report a Bug 按钮。
- 在字段中输入摘要,然后点击下一步。这是一个例子:Gerrit Workflow 链接已失效
- 查看你提供的选项。如果你发现你的 bug,点击该 bug 并查看其状态;如果还有更多工作要做,请继续下面的代码部分。如果你没有发现你的 bug,请继续下一步。
- 点击 No, I need to report a new bug 按钮。
- 在“Further information”字段中输入 bug 的详细描述,然后点击 Submit bug report。
注意:如果你修复的是一些琐碎的事情,实际上不是软件中的功能缺陷,你可以这样做,而无需提交 bug 工单,如果你不想在版本之间跟踪这项工作。如果你这样做,只需在提交消息中提及这是一个不需要 bug 工单的琐碎更改。功能缺陷应在 bug 工单中跟踪。新功能应在蓝图中跟踪。琐碎的功能可以使用标记为“Wishlist”重要性的 bug 工单进行跟踪。
选择 Bug
如果你想开始处理一个 bug,请等待 watcher 驱动程序将其状态设置为“Triaged”。请不要将状态为“New”的 bug 分配给自己,如果你刚刚提交了 bug 并且准备提交修复程序,请告诉我们的 IRC 频道 #openstack-watcher 中的核心贡献者将其设置为“Triaged”。
容易解决的问题
一些 bug 已被 bug 管理员识别为适合首次贡献者。这些 bug 应该需要小的补丁,并且不需要对 Watcher 有深入的了解即可进行处理。在 bug 系统中 使用带有 low-hanging-fruit 标签 找到它们。
审查
OpenStack CI 系统使用核心评审者的概念。这些人一直为项目评审代码,并在相当长的时间内帮助提高代码质量和一致性。项目贡献者会认为这位评审者对团队有积极影响,并且他们维护了 OpenStack 开发社区的价值观和传统。
政策
现有的核心评审者可以在 ML 线程中提名新的核心评审者。当前评审者之间的同意将导致 PTL 宣布新的核心评审者。缺乏一致同意应仔细考虑,并由 PTL 根据活跃团队成员的意见做出最终决定。如果核心评审组中的同行认为核心评审者未能达到核心评审者的期望,则可以提名他们恢复到普通评审者状态。
补丁需要核心评审者标记评审为“Approved”才能合并。
审查指南
合并代码审批
- 为了获得批准,至少需要一位核心评审者提供
+2,并且 gate 测试(Jenkins)已成功通过。
继续他人的贡献
- 如果一个贡献者提交的补丁被另一个贡献者接手并完成,则应使用 特殊的处理方式 来解决该补丁。
给评审者的建议
-1投票是一个让我们的代码在合并之前变得更好的机会。请尽最大努力提出有帮助、可操作的 -1 投票。- 避免盲目地
+1代码的诱惑,请在充分审查后形成自己的意见,再进行投票。 - 当对补丁投票
-1时,意味着您希望提交者根据您的反馈进行修改,然后再由核心评审人员考虑合并此代码。 - 如果您提出了问题,除非您预计该问题的答案很可能会导致您在没有进一步修改的情况下对补丁投反对票,否则应投票
0。 - 如果您使用
-1投票提问,并且贡献者回答了问题,请回复确认您的问题。要么更改您的投票,要么继续提供为什么应该保持-1评论的额外理由。 -2投票是单个核心评审人员的否决。它是“粘性”的。这意味着即使您修改了补丁,该投票也会保留。为了允许您的补丁合并,必须先由同一评审人员清除-2投票。当您贡献的内容与当前项目愿景不符,或者实现方式无法接受时,会使用此投票。例如,核心评审人员希望单独重新评估的安全问题,然后再允许继续贡献。它也可以用作停止补丁进一步门控测试的一种方式,如果包含可能破坏门控的内容。即使在2*+2,+A合并批准之后,但在补丁达到 MERGED 状态之前,它仍然有效。- 为了避免
-2投票,请在编写代码之前与开发团队讨论您的计划,并在工作时发布 WIP(workflow-1)补丁,并在提交合并审查之前征求意见。