Skip to main content

贡献指南

本文介绍了如何为 Apache APISIX 社区做出贡献。

我能贡献什么？#

你可以通过以下方式为 Apache APISIX 做出贡献：

如果你有任何关于 Apache APISIX 做贡献的想法，也欢迎随时发邮件到 dev@apisix.apache.org 进行社区讨论。

选择想要修复的 issue#

你可以选择修复一个正在进行的 Issues。

  1. 一旦你选择了一个 issue 进行工作或创建新的 issue，请在该 issue 下留言，并让一个 Committer 或者 PMC 将它分配给你。

  2. 请检查 issue 的状态，并推断你是否能够完成该 issue。

  3. 联系 Committer 或者 PMC 为你处理的 issue 提供反馈和 Review。

Good first issues#

带有 good first issues 标签的 issue 通常是对新手友好且上手较简单的类型，你可以此作为突破口，开始你对 APISIX 的第一个贡献。

你可以浏览 good first issues 列表，并选择想要贡献的 issue。

搭建本地开发环境#

贡献代码或文档前，请搭建你的本地开发环境。

Fork 项目仓库并 Clone 到本地#

首先前往 Github 上的 APISIX repo 仓库。在页面右上角处，点击 Fork 按键，然后在你 Fork 的仓库中克隆到你的本地环境。

git clone https://github.com/${your-username}/apisix.git

添加 upstream 仓库作为本地的远程仓库#

你可以通过以下命令，检查上游 repo 是否已经被配置，如果返回结果中存在四条记录则说明已经被配置。

git remote -v

如果返回结果中只有两条记录，你可以通过以下命令配置：

git remote add upstream https://github.com/apache/apisix.git

如果你需要了解更多关于 Git 和 GitHub 流程的信息，请参考 GitHub 文档。

note

你需要设置你的姓名和邮件地址，以确保你的 ID 显示在贡献者名单上。

你可以使用以下命令进行设置：

git config --global user.name "full name"git config --global user.email "mail address"

创建你的分支#

为了保证本地分支保持最新，你可以拉取上游的最新变更并应用到本地分支：

git fetch upstreamgit checkout mastergit rebase upstream/mastergit push origin master

如果需要修改代码，你可以通过以下命令在本地创建一个新分支：

git checkout -b issue-no
note

每个 PR 中的提交在合并之前都会被压缩。如果你使用的是较早的分支，可能会导致提交日志与上游不同。

提交你的改动#

贡献者应在整个过程中遵守代码行为准则。

当你完成了修改，就可以提交文件并推送到你的分叉上。

git add modified-file-namesgit commit -m 'commit message'git push origin issue-no

创建一个 PR#

当你把修改推送到你的分支上后，就可以创建一个 PR 把它合并到上游仓库中。

查阅 GitHub 工作流程 了解提交 PR 的详细细节。

  1. 创建一个到 master 分支的 PR。

  2. 请确保 PR 标题有如 fix:，feat: 或者其他提交类型的前缀。

  3. 联系相关问题领域的 Committer/PMC 成员，开始进入 Review 流程。

  4. 参与讨论并对 reviewer 的问题进行解答。

  5. 等待你的 PR 被同意并合并。

  6. 祝贺你成为 Apache APISIX 的官方贡献者!

建议操作：双重认证 (2FA)#

双重认证（Two-factor authentication，下称 2FA）是指将密码和对象（如信用卡、短信、令牌或如指纹的生物标志物）结合起来识别用户的认证方法。

为了保证贡献者账户的安全，在 GitHub 上登录贡献代码时，你需要配置 2FA 。更多细节请参考用 2FA 保护你的账户。

note

如果没有启用 2FA，你有可能会被项目移除，并且无法访问 Apache APISIX 的存储库。

在 GitHub 上配置 2FA#

你可以使用一个手机 APP 或通过短信来配置 2FA。

GitHub 建议使用基于时间的一次性密码（TOTP）手机 APP 来配置 2FA。阅读配置 2FA获得更细节的信息。

提交代码#

在开启了 2FA 之后，创建一个个人访问令牌来执行 Git 操作。

在推送代码时，你可以使用用户名+个人访问令牌组合来代替用户名+密码组合。