注意

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

基本工作流程

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

本页假设您是新贡献者，有一个错误修复或增强的想法，但不知道如何进行。观看Ceph 开发入门视频（1 小时 15 分钟），了解此工作流程的实用总结。

更新跟踪器

找到您打算修复的错误的问题跟踪器（Redmine）编号。如果不存在跟踪器问题，请创建一个。只有一种情况不需要创建 Redmine 跟踪器问题：对文档进行微小更改的情况。

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

（Redmine）跟踪器工单向其他 Ceph 开发人员解释了问题（错误），以便在错误接近解决时让他们了解情况。提供有用、清晰的标题，并在描述中包含详细信息。撰写工单标题时，问自己“如果我需要在两年后搜索此工单，我可能会搜索哪些关键字？”然后将这些关键字包含在标题中。

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

Ceph 工作流程概述

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

  1. 上游仓库（ceph/ceph）

  2. 您的上游仓库分支（your_github_id/ceph）

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

修改 Ceph 仓库的步骤如下

  1. 配置本地环境

    1. 创建“上游 Ceph”仓库的分支。

    2. 将该分支克隆到您的本地文件系统。

  2. 修复错误

    1. 将本地主分支与上游主分支同步.

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

    3. 修改本地文件系统中的仓库本地工作副本.

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

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

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

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

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

创建 Ceph 仓库的分支

有关分支的详细说明，请参阅GitHub 文档。简而言之，如果您的 GitHub 用户名是“mygithubaccount”，您的上游仓库分支将出现在https://github.com/mygithubaccount/ceph。

克隆您的分支

创建分支后，运行以下命令克隆它

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

您必须在克隆之前先派生 Ceph 仓库。如果您未派生，则无法打开 GitHub 拉取请求。

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

配置本地环境

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

本节中的命令仅在首次设置本地工作副本时必需。这意味着这些命令仅在您第一次使用 Ceph 仓库时必需。但是，它们是不可避免的，如果您未能运行它们，您将无法使用 Ceph 仓库。

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

    注意

    这些命令只能在克隆分支时创建的ceph/目录中运行。

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

  2. 将上游仓库添加为“remote”并获取它

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

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

修复错误

将本地主分支与上游主分支同步

在您的本地工作副本中，remotes/origin/main中有一个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返回一行“Untracked files”，请参阅更新子模块的过程。

创建错误修复分支

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

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 问题跟踪器中，将跟踪器问题的状态更改为“In progress”。这会向其他 Ceph 贡献者表明您已开始处理修复，这有助于避免重复工作。如果您没有权限更改该字段，只需评论您正在处理该问题。

  2. 修复错误本身

    本指南无法告诉您如何修复您选择修复的错误。本指南假设您已确定需要改进的领域，并且知道如何进行改进。

    您的修复可能很简单，只需要最少的测试。但这不太可能，除非您只更新文档。更有可能的是，修复错误的过程需要几轮测试。测试过程可能是迭代的，涉及试验、错误、技能和耐心。

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

将修复推送到您的分支

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

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

    使用--signoff选项（此处表示为-as标志的s部分）将更改提交到本地工作副本的fix_1分支

    git commit -as

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

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

    git push origin fix_1

    注意

    在命令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 拉取请求教程。

要了解什么构成一个“好的”拉取请求，请参阅 OpenStack 项目 Wiki 上的Git 提交良好实践文章。

另请参阅 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 test

可能会运行额外的测试，具体取决于您的 PR 修改了哪些文件。

The make check test builds the PR and runs it through a battery of tests. These tests run on servers that are operated by the Ceph Continuous Integration (CI) team. When the tests have completed their run, the result is shown on GitHub in the pull request itself.

在打开 PR 之前测试您的修改。有关详细信息，请参阅有关测试的部分。

关于 PR make check 测试的说明

GitHub make check 测试由 Jenkins 实例驱动。

Jenkins 会将您的 PR 分支合并到基础分支的最新版本中，然后再开始任何测试。这意味着您无需重新设置 PR 基准来获取任何修复。

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

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

Jenkins 配置为搜索日志中已知与过去的 make check 失败相关的字符串。但是，不能保证这些已知字符串与任何给定的 make check 失败相关联。您必须通读日志以确定特定失败的原因。

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

可能有必要在运行在物理或虚拟硬件上的真实 Ceph 集群上测试您的修复。为此目的设计的测试位于ceph/qa 子目录中，并通过teuthology 框架运行。

Ceph 社区可以访问 Sepia lab，在那里可以在物理硬件上运行集成测试。

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

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

要请求访问 Sepia lab，请从这里开始。

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

代码审查

在您的错误修复经过彻底测试之后（有时甚至在测试期间），它将接受其他开发人员的代码审查。这通常以 PR 中的评论形式进行，但可以通过IRC或Slack或邮件列表上的讨论进行补充。

修改您的 PR

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

更新在本地提交（在我们的示例中是fix_1分支）后，必须将它们推送到 GitHub 才能出现在 PR 中。

修改 PR 是通过向其所基于的fix_1分支添加提交来完成的，通常随后通过重新设置基准来修改分支的 git 历史记录。有关重新设置基准的介绍，请参阅此教程。完成修改后，您需要通过运行以下形式的命令来强制推送分支

git push --force origin fix_1

为什么我们要采取这些额外的步骤而不是简单地向 PR 添加额外的提交？PR 由单个提交组成是最佳实践；这使得保持干净的历史记录成为可能，它简化了对更改的同行评审，并使合并 PR 更容易。万一您的 PR 必须恢复，与该 PR 相关联的单个提交使恢复过程更容易。

合并

当项目负责人合并您的 PR 时，错误修复过程完成。

发生这种情况时，它会向您（或合并 PR 的负责人）发出信号，将问题跟踪器状态更改为“Resolved”。某些问题可能会被标记为回迁，在这种情况下，状态应更改为“Pending Backport”（有关详细信息，请参阅回迁章节）。

有关合并的更多信息，请参阅提交合并：范围和节奏。

正确的合并提交格式

这是合并提交的最基本形式

doc/component: title of the commit

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

这包括两部分

  1. 要合并的提交的标题。

  2. 审阅者的姓名和电子邮件地址。将审阅者的电子邮件地址括在尖括号中。

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

如果您使用浏览器合并 GitHub PR，填充合并消息的最简单方法是使用“Ceph GitHub Helper Extension”（适用于 Chrome 和 Firefox）。

启用此扩展后，如果您转到 GitHub PR 页面，将在右上角显示一个垂直助手。如果您单击用户剪影按钮，合并消息输入将自动填充。

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

如果您无法在审阅者的 GitHub 页面上找到他们的电子邮件地址，您可以在.githubmap文件中查找，该文件可以在仓库中找到/ceph/.githubmap。

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

如果您无法通过上述方法找到审阅者的电子邮件地址，您可以在 git 日志中搜索他们的电子邮件地址。审阅者可能以前提交过内容。如果他们有以前的贡献，git 日志中可能包含他们的电子邮件地址。

使用以下命令

git log

使用 ptl-tool 生成合并提交

另一种生成合并提交的方法是使用 Patrick Donnelly 的ptl-tool来拉取提交。该工具可以在/ceph/src/script/ptl-tool.py找到。由ptl-tool生成的合并提交具有以下形式

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>

杂项

--set-upstream

如果您在git push命令中忘记包含--set-upstream origin x选项，您将看到以下错误消息

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}

要设置 git 自动创建与本地工作副本中的分支相对应的上游分支（无需每次都添加--set-upstream origin x选项），请在ceph/目录中运行此命令

git config --global push.autoSetupRemote true

在本地删除分支

要从本地工作副本中删除名为localBranchName的分支，请运行以下形式的命令

git branch -d localBranchName

在远程删除分支

要从远程上游分支（也是您的ceph/ceph分支，如创建 Ceph 仓库的分支中所述）中删除名为remoteBranchName的分支，请运行以下形式的命令

git push origin --delete remoteBranchName

按时间顺序搜索文件中的字符串

要搜索将给定字符串（在此示例中为foo）引入给定文件（在此示例中为file.rst）的提交，请使用-S <string>选项。运行以下形式的命令

git log -S 'foo' file.rst

由 Ceph 基金会为您呈现

Ceph 文档是由非营利性 Ceph 基金会 资助和托管的社区资源。如果您希望支持这项工作和我们的其他努力，请考虑 立即加入。