注意

本文档适用于 Ceph 开发版本。

基本工作流程

以下图表说明了基本的 Ceph 开发工作流程：

本页假设您是一位新贡献者，有一个错误修复或增强的想法，但不知道如何进行。观看 c37448: Getting StartedGetting Started with Ceph Development视频（1 小时 15 分钟），以获得此工作流程的实际总结。

更新跟踪器

查找问题跟踪器(Redmine) 您打算修复的错误的编号。如果不存在跟踪器问题，请创建一个。只有在以下情况下您不需要创建 Redmine 跟踪器问题：次要文档更改的情况。简单的文档清理不需要相应的跟踪器问题。主要的文档更改需要跟踪器问题。主要的文档更改包括添加新的文档章节或文件，以及对文档的结构或内容进行重大更改。

简单的文档清理不需要相应的跟踪器问题。主要的文档更改需要跟踪器问题。主要的文档更改包括添加新的文档章节或文件，以及对文档的结构或内容进行重大更改。

一个 (Redmine) 跟踪器票证向其他 Ceph 开发者解释了问题（错误），以便他们在错误接近解决时保持知情。在描述中提供有用、清晰的主题，并包括详细信息。在编写票证标题时，问自己“如果两年后我需要搜索这个票证，我可能会搜索哪些关键词？”然后包括这些关键词在标题中。

如果您的跟踪器权限被提升，通过设置Assignee字段将错误分配给自己。如果您的跟踪器权限没有被提升，只需添加一条评论，简短地说明“我正在处理这个问题”。

Ceph 工作流程概述

Ceph 工作流程涉及三个仓库。它们是：

  1. 上游仓库 (ceph/ceph)

  2. 您的 upstream 仓库分支 (your_github_id/ceph)

  3. 您的本地仓库工作副本（在您的工作站上）

更改 Ceph 仓库的步骤如下：

  1. 配置您的本地环境

    1. 创建一个分支“upstream Ceph” 仓库。

    2. 将分支克隆到您的本地文件系统。 to your local filesystem.

  2. 修复错误

    1. 同步本地主与 upstream 主.

    2. 在您的本地工作副本中创建一个错误修复分支。在您的本地工作副本中创建一个错误修复分支。

    3. 在您的本地文件系统中的本地工作副本上做出更改.

    4. 将本地工作副本中的更改推送到您的分支.

  3. 创建一个拉取请求以将更改推送到上游。

    1. 创建一个拉取请求，要求将您的更改添加到“upstream Ceph” 仓库。

准备您的本地 Ceph 仓库工作副本

本节“准备您的本地 Ceph 仓库工作副本”中的步骤仅在您首次设置本地环境时需要遵循。如果您是第一次与 Ceph 项目合作，那么这些命令是必要的，并且是您应该运行的第一批命令。

创建 Ceph 仓库的分支

请参阅GitHub 文档有关详细信息，请参阅有关分支的说明。简而言之，如果您的 GitHub 用户名是https://github.com/mygithubaccount/ceph.

克隆您的分支

创建您的分支后，通过运行以下命令克隆它：

git clone https://github.com/mygithubaccount/ceph

您必须在克隆之前分支 Ceph 仓库。如果您未能分支，则无法打开GitHub 拉取请求.

有关使用 GitHub 的更多信息，请参阅GitHub 帮助.

配置您的本地环境

本节中的命令配置您的本地 git 环境以生成Signed-off-by:标签。这些命令还设置了您的本地环境，以便它可以与上游仓库保持同步。

本节中的命令仅在您的本地工作副本的初始设置期间是必要的。这意味着这些命令仅在您第一次与 Ceph 仓库合作时是必要的。然而，它们是不可避免的，如果您未能运行它们，则您将无法在 Ceph 仓库上工作。

  1. 使用您的姓名和电子邮件地址配置本地 git 环境。

    Note

    这些命令仅在您克隆分支时所在的ceph/目录中才有效。

    git config user.name "FIRST_NAME LAST_NAME"
git config user.email "MY_NAME@example.com"

  2. 将上游仓库作为“远程”添加并获取它：

    git remote add ceph https://github.com/ceph/ceph.git
git fetch ceph

    这些命令获取所有分支和提交，从ceph/ceph.git到本地 git 仓库作为remotes/ceph/$BRANCH_NAME和可以引用为ceph/$BRANCH_NAME在本地 git 命令中。

修复错误

同步本地主与 upstream 主

在您的本地工作副本中，有一个main分支的副本在remotes/origin/main中。这被称为“本地主”。这个主分支的副本 (https://github.com/your_github_id/ceph.git) 在您克隆它时“冻结在时间”中，但您从中分支的上游仓库 (https://github.com/ceph/ceph.git，通常缩写为ceph/ceph.git)

由于上游主不断从其他贡献者那里接收更新，随着时间的推移，您的分支将越来越远离您克隆时上游仓库的状态。

保持您的分支的main分支与上游主同步，以减少您的分支的主分支和上游主分支之间的漂移。

保持您的分支与上游仓库同步的命令如下：

git fetch ceph
git checkout main
git reset --hard ceph/main
git push -u origin main

经常遵循此程序以保持您的本地main与上游main.

如果命令git status返回一行“未跟踪文件”，请参阅更新子模块的步骤.

创建一个错误修复分支

为您的错误修复创建一个分支：

git checkout main
git checkout -b fix_1
git push -u origin fix_1

第一个命令 (git checkout main) 确保错误修复分支“fix_1”是从上游仓库主分支的最新状态创建的。

第二个命令 (git checkout -b fix_1) 在您的本地工作副本中创建一个名为“fix_1”的“错误修复分支”。您为了修复错误而做出的更改将提交到这个分支。

第三个命令 (git push -u origin fix_1) 将错误修复分支从您的本地工作仓库推送到上游仓库的分支。

在本地工作副本中修复错误

  1. 更新跟踪器

    在Ceph 问题跟踪器，更改跟踪器问题的状态为“进行中”。这向其他 Ceph 贡献者传达了您已经开始处理修复，这有助于避免工作重复。如果您没有更改该字段的权限，只需评论您正在处理该问题。

  2. 修复错误本身

    本指南不能告诉您如何修复您选择修复的错误。本指南假设您已经确定了一个需要改进的区域，并且您知道如何进行改进。

    您的修复可能很简单，并且只需要最小的测试。但除非您只更新文档，否则这种情况不太可能。更有可能的是，修复您的错误的进程将需要多轮测试。测试过程可能是迭代的，并将涉及尝试、错误、技能和耐心。

    有关可用于验证错误修复的工具的详细讨论，请参阅测试部分.

将修复推送到您的分支

您已经完成了错误修复的工作。您已经测试了错误修复，并且您相信它有效。

  1. 将更改提交到您的本地工作副本。

    使用fix_1分支：--signoff选项（这里表示为s标志的一部分）将更改提交到您的本地工作副本的-as flag):

    git commit -as

  2. 将更改推送到您的分支：

    将更改从您的本地工作副本的fix_1分支推送到您的上游仓库分支的fix_1分支：

    git push origin fix_1

    Note

    在命令git push origin fix_1, origin是上游 Ceph 仓库分支的名称，可以将其视为git@github.com:username/ceph.git，其中username是您的 GitHub 用户名。

    可能origin不是您的分支的名称。通过运行git remote -v来发现您的分支的名称，如下所示：

    $ git remote -v
ceph   https://github.com/ceph/ceph.git (fetch)
ceph   https://github.com/ceph/ceph.git (push)
origin git@github.com:username/ceph.git (fetch)
origin git@github.com:username/ceph.git (push)

    行：

    origin git@github.com:username/ceph.git (fetch)

    和行：

    origin git@github.com:username/ceph.git (push)

    提供了信息，即origin是您的 Ceph 仓库分支的名称。

打开一个 GitHub 拉取请求

将错误修复推送到您的分支后，打开一个 GitHub 拉取请求 (PR)。这使得您的错误修复对 Ceph 贡献者社区可见。他们会审查它。他们可能会对您的错误修复进行额外的测试，并且他们可能会要求更改错误修复。

准备好接收建议和建设性批评，以评论的形式出现在 PR 中。

如果您不知道如何创建和管理拉取请求，请阅读GitHub 拉取请求教程.

要了解构成“良好”拉取请求的内容，请参阅Git 提交良好实践文章在OpenStack 项目维基.

请参阅 Ceph 自己的提交补丁文档。

您的拉取请求 (PR) 打开后，更新问题跟踪器通过添加一条评论，指示其他贡献者您的 PR。评论可以像这样简单：

*PR*: https://github.com/ceph/ceph/pull/$NUMBER_OF_YOUR_PULL_REQUEST

理解自动 PR 验证

当您创建或更新您的 PR 时，Ceph 项目的持续集成 (CI)基础设施自动测试它。以下是一些在您的 PR 上执行的自动测试：

  1. 一个测试，检查提交是否正确签名（见提交补丁）：

  2. 一个测试，检查文档是否构建

  3. 一个测试，检查子模块是否未修改

  4. 一个测试，检查 API 是否有序

  5. a make check测试

可能会运行其他测试，具体取决于您的 PR 修改的文件。

The make check测试构建 PR 并运行它通过一系列测试。这些测试在由 Ceph 持续集成 (CI) 团队运营的服务器上运行。当测试完成运行时，结果会显示在 GitHub 上的拉取请求本身中。

在打开 PR 之前测试您的修改。参考测试部分 for details.

PR make check test 的注意事项

GitHubmake check测试由 Jenkins 实例驱动。

Jenkins 在开始任何测试之前将您的 PR 分支合并到最新版本的基线分支。这意味着您不必重新基础 PR 以获取任何修复。

您可以通过向 PR 添加评论随时触发 PR 测试 - 评论应包含字符串“请测试此内容”。由于订阅 PR 的人可能会将此解释为请求他或她测试 PR，因此您必须直接针对 Jenkins。例如，写“jenkins 重新测试此内容”。如果您只需要运行一个测试，您可以使用像“jenkins 测试签名”这样的命令来请求它。这些请求的列表会自动添加到每个新 PR 描述的末尾，因此请在那里查找您需要的单个测试。

如果有构建失败并且您不确定是什么原因造成的，请检查make check日志。要访问 make check 日志，请点击 PR 中的“详细信息”（位于make check测试旁边）链接以进入 Jenkins Web GUI。然后点击左侧的“控制台输出”。

Jenkins 被配置为在日志中搜索过去与make check失败相关的字符串。然而，没有保证这些已知字符串与任何给定的make check失败相关。您必须阅读日志以确定您特定失败的原因。

集成测试，又名 ceph-qa-suite

可能需要在实际运行的 Ceph 集群上测试您的修复，这些集群在物理或虚拟硬件上运行。为此目的设计的测试位于ceph/qa子目录teuthology 框架.

中，并通过Sepia实验室其中集成测试并可以在物理硬件上运行。

其他贡献者可能会在您的 PR 中添加标签，如needs-qa，这允许 PR 合并到单个分支，然后有效地一起测试。Teuthology 测试套件可能需要数小时（在某些情况下，甚至需要数天）才能完成，因此批量测试减少了资源争用并节省了时间。

如果您的代码更改会影响升级，请添加needs-upgrade-testing标签。这表示应该安排升级测试套件。

要请求访问 Sepia 实验室，请开始这里.

集成测试在集成测试章节中讨论得更详细。

代码审查

在您的错误修复经过彻底测试后——有时甚至在测试期间——它将受到其他开发者的代码审查。这通常以 PR 本身中的评论的形式出现，但可以由关于IRC的讨论补充，或是在Slack或是在邮件列表上。.

修改您的 PR

在您的 PR 正在测试和代码审查期间，您可以通过编辑本地分支中的文件随时修改它。

更新提交到本地后（在我们的示例中为fix_1分支），必须将它们推送到 GitHub，以便在 PR 中显示。

修改 PR 是通过向基于它的fix_1分支添加提交来完成的，通常随后是重新基础以修改分支的 git 历史。参考这篇教程了解重新基础。当您完成修改后，您需要通过运行以下形式的命令强制推送您的分支：

git push --force origin fix_1

为什么我们采取这些额外的步骤，而不是简单地向 PR 添加额外的提交？PR 最好由单个提交组成；这使得维护干净的历

合并

The bugfix process completes when a project lead merges your PR.

When this happens, it is a signal for you (or the lead who merged the PR) to change the 问题跟踪器 status to “Resolved”. Some issues may be flagged for backporting, in which case the status should be changed to “Pending Backport” (see the Backporting chapter for details).

请参阅Commit merging: scope and cadence for more information on merging.

正确的合并提交格式

This is the most basic form of a merge commit:

doc/component: title of the commit

Reviewed-by: Reviewer Name <rname@example.com>

This consists of two parts:

  1. The title of the commit to be merged.

  2. The name and email address of the reviewer. Enclose the reviewer’s email address in angle brackets.

使用浏览器扩展自动填充合并消息

If you use a browser to merge GitHub PRs, the easiest way to fill in the merge message is with the “Ceph GitHub Helper Extension” (available for Chrome和Firefox).

After enabling this extension, if you go to a GitHub PR page, a vertical helper will be displayed at the top-right corner. If you click on the user silhouette button the merge message input will be automatically populated.

使用 .githubmap 找到审查者的电子邮件地址

If you cannot find the email address of the reviewer on his or her GitHub page, you can look it up in the .githubmap file, which can be found in the repository at /ceph/.githubmap.

使用“git log”找到审查者的电子邮件地址

If you cannot find a reviewer’s email address by using the above methods, you can search the git log for their email address. Reviewers are likely to have committed something before. If they have made previous contributions, the git log will probably contain their email address.

Use the following command:

git log

使用 ptl-tool 生成合并提交

Another method of generating merge commits involves using Patrick Donnelly’s ptl-tool to pull commits. This tool can be found at /ceph/src/script/ptl-tool.py. Merge commits that have been generated by the ptl-tool have the following form:

Merge PR #36257 into main
* refs/pull/36257/head:
        client: move client_lock to _unmount()
        client: add timer_lock support
Reviewed-by: Patrick Donnelly <pdonnell@redhat.com>

Miscellaneous

--set-upstream

If you forget to include the --set-upstream origin x option in your git push command, you will see the following error message:

fatal: The current branch {x} has no upstream branch.
To push the current branch and set the remote as upstream, use
   git push --set-upstream origin {x}

To set up git to automatically create the upstream branch that corresponds to the branch in your local working copy (without having to add the option --set-upstream origin x every time), run this command from within the ceph/目录：

git config --global push.autoSetupRemote true

本地删除分支

To delete the branch named localBranchName from the local working copy, run a command of this form:

git branch -d localBranchName

远程删除分支

To delete the branch named remoteBranchName from the remote upstream branch (which is also your fork of ceph/ceph, as described in 创建 Ceph 仓库的分支), run a command of the following form:

git push origin --delete remoteBranchName

横向搜索文件中的字符串

To search for the commit that introduced a given string (in this example, that string is foo) into a given file (in this example, that file is file.rst)，使用-S <string> option. Run a command of the following form:

git log -S 'foo' file.rst

由 Ceph 基金会带给您

Ceph 文档是一个社区资源，由非盈利的 Ceph 基金会资助和托管Ceph Foundation. 如果您想支持这一点和我们的其他工作，请考虑加入现在加入.