参与 Xorbits 项目

如何开始

我们欢迎你以任何形式参与 Xorbits，包括报告 bug，修复 bug，文档优化，功能增强，或是贡献新的想法。

If you are brand new to Xorbits or open-source development, we recommend going through the GitHub “issues” tab to find issues that interest you. There are a number of issues listed under Docs and good first issue where you could start out. Once you’ve found an interesting issue, you can return here to get your development environment setup.

当你开始解决一个 issue 时，请先将 issue 分配给自己，避免其他人重复你的工作。

你可以在 issue 下回复 take，此时 GitHub 将自动把这个 issue 分配给你（这可能需要几秒钟，并且需要刷新页面）。这样，我们便可以过滤出未被分配的 issue。

So, a good way to find an issue to start contributing to Xorbits is to check the list of unassigned good first issues and assign yourself one you like by writing a comment with the exact text take.

如果因为某些原因，你无法继续解决这个问题，请取消分配。你也可以查看已被分配的 issue 列表。如果你想解决已被分配的问题，请礼貌地询问当前在处理该 issue 的人是否可以接手（请在考虑接手前至少等待一周时间）。

欢迎加入我们的社区交流群，讨论 Xorbits 的相关问题。我们有 slack 群与微信群等方式，以帮助 Xorbits 的开发者相互取得联系。即使是熟练的开发者，在刚开始的时候也和您一样对 Xorbits 感到陌生和好奇。他们很乐意欢迎你并帮助你了解 Xorbits。请查看下一节以了解更多信息。

报告 bug 与提出功能诉求

Bug 报告是让 Xorbits 更加稳定的重要方式。一份完整的 bug 报告能够让维护者复现你遇到的 bug 并提出修复建议。关于撰写 Bug 报告，请参考这篇 stackoverflow 文章 与这篇 博客 。

报告 bug 前，我们建议在 主干 (main) 分支 尝试运行 bug 复现代码，以确认 bug 仍存在。此外，也建议先查看现有的 bug 报告和 pull request，看看该问题是否已经被报告或修复了。

Bug 报告需要:

1. 包含一段简短，自洽的 Python 代码片段，以便重现问题:

   ```python
   >>> from xorbits.pandas import DataFrame
   >>> df = DataFrame(...)
   ...
   ```
   

2. 包含 Xorbits 的完整版本及相关依赖的版本。

3. 解释为什么当前的行为不正确，以及预期的行为是什么。

提交 bug 报告后，该 issue 将会稍后显示在 Xorbits 社区中，并允许其他开发者进行回复。

代码开发

当你有一个需要修复的问题、需要添加的增强功能或需要改进的文档时，你需要学习如何使用 GitHub 并了解 Xorbits 代码库。

版本控制，Git，以及 GitHub

对新用户来说,使用 Git 是参与 Xorbits 开发最令人畏惧的方面之一。开发工作可能因为 Git 变得混乱不堪。以下指南会帮助你把 Git 变得简单直接且基本上不出错。如果您遇到难以解决的问题，欢迎在社区寻求帮助。

The code is hosted on GitHub. To contribute you will need to sign up for a free GitHub account. We use Git for version control to allow many people to work together on the project.

以下是一些很好的学习 Git 的资源:

• GitHub 帮助页面 。

• NumPy 开发流程 。

• Matthew Brett 的 Pydagogue 。

开始使用 Git

你可以参考 GitHub 指南 来安装 git，设置 SSH key，并配置 git。你需要完成这些步骤以确保你的本地仓库和 GitHub 可以正常工作，后续的工作才可以顺利进行。

创建分叉 (forking)

在开发之前，你需要创建自己的 fork。访问 Xorbits 项目页面 并点击右上角 Fork 按钮。之后克隆你的 fork 到本地:

git clone --recursive https://github.com/your-user-name/xorbits.git xorbits-yourname
cd xorbits-yourname
git remote add upstream https://github.com/xorbitsai/xorbits.git

上面的代码会创建一个名为 xorbits-yourname 的本地仓库，并将该本地仓库与 Xorbits 主仓 关联。

需要注意的是，进行浅克隆 (带有选项 --depth==N, N 大于等于 1) 可能会导致某些测试失败。

创建分支(branch)

你的主干 (main) 分支通常应该是能够用于正式生产的，因此在进行代码修改前，你需要创建新的功能 (feature) 分支。举例来说:

git branch shiny-new-feature
git checkout shiny-new-feature

上面的代码可以简化为:

git checkout -b shiny-new-feature

这会将你的当前分支切换为 shiny-new-feature。在这个分支下的改动应该限制在一个 bug 或功能的范围内，这样这个分支上的改动对 Xorbits 的影响将会非常清晰。你可以有多个功能分支，并使用 git checkout 命令在这些分支之间来回切换。

从主干分支创建分支前，请确保你的主干分支是最新的。你可以用下面的命令更新主干分支:

git checkout main
git pull upstream main --ff-only

当你想添加主干分支的改动到你的功能分支时，请见 更新你的 pull request 。

将改动贡献到 Xorbits

提交你的代码

请保持每次 commit 的代码风格一致，以便使你的 pull request 更具有可读性。

每当你对代码做出更改后，你可以通过输入如下指令来查看:

git status

新创建的文件不会被 git 追踪，通过以下指令将其加入代码仓库:

git add path/to/file-to-be-added.py

再次输入 ‘git status’ 指令应出现:

# On branch shiny-new-feature
#
#       modified:   /relative/path/to/file-you-added.py
#

最后，将你的更改和更改的解释说明commit到本地的repository当中。Xorbits 使用一种关于commit message前缀和布局的约定。以下是一些常见的前缀以及何时使用它们的一般指南：

• FEATURE: 特性与新功能

• ENH: 改进与提升

• BUG: Bug 修复

• DOC: 文档的删改与添加

• TST: 测试的删改与添加

• BLD: 构建过程或脚本的更新

• PERF: 性能提升

• TYP: 类型注解

• CLN: 代码清理

• REF: 重构

• CHORE: 辅助任务

以下定义了 commit message 的结构应如何来书写。在 commit message 中，请用 GH1234 或 #1234 的格式关联与你的更改内容对应的 GitHub issues。两种格式均可，但推荐使用前者:

• 小于 80 个字符的主题描述

• 空一行

• commit message 主体 (可为空)

现在你可以将你的更改 commit 到本地的代码仓库:

git commit -m

提交你的更改

当你想在你的 GitHub 页面上公开你的更改时，将你在 fork 的对应功能分支上所做的修改提交:

git push origin shiny-new-feature

这里的 origin 是你 GitHub 上的远程代码仓库的默认命名，你可以通过如下指令查看所有远程代码仓库:

git remote -v

如果你按照前面的指令正确添加了上游仓库，你应该能看到类似于以下的信息:

origin  git@github.com:yourname/xorbits.git (fetch)
origin  git@github.com:yourname/xorbits.git (push)
upstream        git://github.com/xorbitsai/xorbits.git (fetch)
upstream        git://github.com/xorbitsai/xorbits.git (push)

现在你的代码已经被上传至 GitHub，但它还不是 Xorbits 代码的一部分。要想让你的代码真正合并到 Xorbits，你还需要创建一个 pull request。

检查你的代码

当你已经准备好请 Xorbits 核心开发人员对你的代码审查时，提交一个 pull request。请在提交前再次确认你的代码格式已符合所有要求，包括但不限于代码风格，测试，性能测试，文档等方面。同时，也请检查对应分支更改前后的变化:

1. 跳转至你的GitHub 代码仓库 – your-user-name/xorbits

2. 点击 Branches

3. 在你的功能分支上点击 Compare

4. 如有必要，请选择 base 和 compare 分支。他们将会依次是 main 和 shiny-new-feature。

最后，创建 pull request

若无异常，你就准备好提交pull request了。Pull request 是将本地仓库中的代码提供给 GitHub 社区并进行查看和最终合并到主要版本的方式。这个pull request及其关联的更改最终将被提交到主分支，并在下一个版本中可用。要提交一个pull request，请按照以下步骤进行:

1. 跳转到你的 GitHub repository

2. 点击 Pull Request 按钮

3. 然后你可以点击 Commits 和 Files Changed 来最后确认你的更改

4. 在 Preview Discussion 中描述你的更改

5. 点击 Send Pull Request。

你的请求将会送达到核心开发人员端并被审查。

更新你的 pull request

基于核心开发人员对你的代码的审查结果，你可能需要对其做一些改动。你可以在你的分支上进行进行修改，随后 commit 并将这些修改提交至 GitHub 上。你的 pull request 会根据提交结果自动更新。用以下操作将你的更新提交至 GitHub:

git push origin shiny-new-feature

这会自动更新你的 pull request 至最新的代码版本并且重新执行 持续集成 测试。

另外， 当与自你提交 pull request 以来已合并到主分支的更改产生的冲突时，你也需要对 pull request 进行更改。

你需要合并上游代码仓库的主干分支来解决上述问题:

git checkout shiny-new-feature
git fetch upstream
git merge upstream/main

如果没有冲突，将会自动打开一份含有默认 commit message 的文件，然后你就可以保存并关闭这个文档。

如果有合并冲突，则你需要解决这些冲突，请通过以下例子：https://help.github.com/articles/resolving-a-merge-conflict-using-the-command-line/ 了解如何解决。当所有的冲突都被解决并合并后，执行 git commit 来保存这些更改。

如果你在要更新同步本地分支与主分支的代码之前有本地分支还有未提交的更改，你需要在更新之前将它们存储 (stash) 起来(请参见文档 stash docs)。 这将有效地保存你的更改，并且在更新后可以重新应用它们。

在本地更新了功能分支之后，你可以通过将其推送到 GitHub 上的分支来更新你的 pull request

git push origin shiny-new-feature

自动修正格式问题

Xorbits 项目使用多个样式检查工具（例如 black、 flake8、 isort），这些工具会在你发起 pull request 后运行。

你可以通过自己配置 pre-commit 工具来自动修正每一次 commit 中的格式错误。首先，创建一个Python 环境，然后配置 pre-commit 。

(可选) 删除已合并的分支。

当上游代码仓库接受并合并了你的功能分支后，你可以删掉这些功能分支。首先，将上游主干分支合并到你的分支，让 git 了解可以安全的删除当前功能分支:

git fetch upstream
git checkout main
git merge upstream/main

然后你可以执行:

git branch -d shiny-new-feature

确保你输入的是小写 -d ，否则若你的功能分支没有合并成功，git 将不会警告。

当你执行完上述操作以后，这个分支还会存在在 GitHub 上，你可以通过以下指令进行删除:

git push origin --delete shiny-new-feature

如何创建一个成功的 pull request

如果您已经进入了 检查你的代码 阶段，核心贡献者之一可能会进行审查。然而，少数核心开发者需要负责审查所有的贡献，这往往会导致我们的审查无法顾及所有的需求。

为了提高你的 pull request 被核心开发者查看的机会，你应该:

• 对于较为复杂的更改，可以 引用一个尚未解决的 issue 来明确 pull request 的目的。

• 恰当全面的测试 是所有 pull request 提交的首要部分。

• pull request 应当越简洁越好 ，因为越长的 pull request 需要越久的审查时间。

• 审查人可能不会审查不通过 GitHub 持续集成测试 的 pull request，所以请确保你的 pull request 提交时 CI check 为绿色

• 请持续 更新你的 pull request