我们在日常工作中经常会使用到很多的开源项目，开源也是一个在工作和学习中都离不开的内容。一般来说，开源项目可以选择直接开源，也可以选择捐赠给某些基金会，例如Linux Foundation、CNCF和ASF等等。以ASF为例，如果一个项目想要成为顶级项目，则需要先通过孵化器孵化，孵化结束毕业才能成为顶级项目。最近我因为一些原因参与了云原生网关APISIX开源项目，这里做一下介绍。

搭建环境

首先我们需要下载源代码并且构建开发流程，根据官网介绍，我们把项目代码fork到自己的仓库并clone到本地，随后在本地仓库中将原始的项目设置为上游upstream，之后新建分支进行开发即可

~ git clone git@github.com:RitterHou/apisix.git~ cd apisix~ git remote -v~ git remote add upstream https://github.com/apache/apisix.git~ git config --global user.name "derobukal"~ git config --global user.email "derobukal@gmail.com"~ git fetch upstream~ git checkout master~ git rebase upstream/master~ git push origin master~ git checkout -b issue-10484~ cd ..

根据官方教程，我们还需要安装APISIX的开发环境

~ export https_proxy="http://192.168.65.100:7890"~ export http_proxy="http://192.168.65.100:7890"~ wget https://raw.githubusercontent.com/apache/apisix/master/utils/install-dependencies.sh~ APISIX_RUNTIME='1.1.1' bash install-dependencies.sh~ cd apisix~ make deps~ sudo mkdir /usr/local/apisix~ sudo mkdir /usr/local/apisix/logs~ sudo chown raymond:raymond /usr/local/apisix -R~ sudo make install

以及安装和启动etcd

~ ETCD_VERSION='3.4.18' wget https://github.com/etcd-io/etcd/releases/download/v${ETCD_VERSION}/etcd-v${ETCD_VERSION}-linux-amd64.tar.gz && tar -xvf etcd-v${ETCD_VERSION}-linux-amd64.tar.gz && cd etcd-v${ETCD_VERSION}-linux-amd64 && sudo cp -a etcd etcdctl /usr/bin/~ cd ..~ etcd

最简单的PR

搭建好了环境之后，就可以修改代码并提交PR了。一般来说开源项目都会有多种类型的改动，以apisix为例，它限制了PR可以为固定的几种类型：

featfixdocsstylerefactorperftestbuildcichorerevertchange

包含了文档修改、新功能、bug修复等等，我们选择比较简单的文档修改作为第一个PR。我在使用APISIX的过程中，发现它证书相关的文档中存在一个错误

在上图中，这里的地址不应该是/hello而应该是/get，因此我们可以在本地仓库新建一个分支并对这个问题作出修改。修改后我们将这次改动提交（为了使提交更加的清晰和安全，建议合并commit并对commit进行签名）并push到我们自己的远程仓库，随后在GitHub上面创建一个针对原始仓库的Pull Request。一般项目在创建一个PR的时候都会有模板信息，照着模板信息进行填写即可，填写完毕就可以提交PR并等待项目的成员进行处理了

修复issue中的问题

在APISIX中有着很多的ISSUE

我们可以关注这些ISSUE看有没有自己能解决的问题。一般来说，带有good first issue标签的都是比较简单并且适合新人的，我们可以优先从这些issue中寻找自己能解决的问题

在确定了issue之后，我们可以请求管理员将这个issue分配给自己，防止别人也会去解决这个问题从而浪费时间。当然，有的时候issue即使已经被分配给别人了，但是如果他一直没有解决这个问题，我们仍然可以请求将这个issue分配给自己

搭建测试环境

对于issue-10484，因为涉及到代码更改，因此需要执行测试。APISIX使用了test-nginx框架来执行测试，官方有关于如何进行测试的介绍

• https://apisix.apache.org/docs/apisix/internal/testing-framework/
• https://apisix.apache.org/blog/2022/06/27/getting-start-with-apisix-test-cases/

我们需要安装测试框架

sudo cpan Test::Nginx

并下载依赖测试模块

➜  apisix git:(issue-10484) git clone https://github.com/api7/test-toolkit/ t/toolkit

修改完代码之后可以执行相关的测试

~ PATH=/usr/local/openresty/nginx/sbin:/usr/bin PERL5LIB=.:$PERL5LIB FLUSH_ETCD=1 prove -Itest-nginx/lib -r t/admin/ssl2.tt/admin/ssl2.t .. ok    All tests successful.Files=1, Tests=52, 11 wallclock secs ( 0.06 usr  0.01 sys +  3.61 cusr  1.05 csys =  4.73 CPU)Result: PASS

如果测试没有问题就可以提交PR了。

通过CI的测试

apisix使用GitHub的workflow进行CI执行测试，以redhat-ci.yaml为例，它会在多个平台上执行多个文件夹内的测试。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

jobs:
  test_apisix:
    name: run ci on redhat ubi
    runs-on: ubuntu-20.04
    timeout-minutes: 90
    strategy:
      fail-fast: false
      matrix:
        events_module:
          - lua-resty-worker-events
          - lua-resty-events
        test_dir:
          - t/plugin/[a-k]*
          - t/plugin/[l-z]*
          - t/admin t/cli t/config-center-yaml t/control t/core t/debug t/discovery t/error_page t/misc
          - t/node t/pubsub t/router t/script t/secret t/stream-node t/utils t/xds-library

如上所示，GitHub action中的matrix默认会对其下面的的多个选项进行合并，例如redhat-ci.yaml的events_module和test_dir组合起来就会构成8个执行脚本

lua-resty-worker-events t/plugin/[a-k]*lua-resty-worker-events t/plugin/[l-z]*lua-resty-worker-events t/admin t/cli t/config-center-yaml t/control t/core t/debug t/discovery t/error_page t/misclua-resty-worker-events t/node t/pubsub t/router t/script t/secret t/stream-node t/utils t/xds-librarylua-resty-events t/plugin/[a-k]*lua-resty-events t/plugin/[l-z]*lua-resty-events t/admin t/cli t/config-center-yaml t/control t/core t/debug t/discovery t/error_page t/misclua-resty-events t/node t/pubsub t/router t/script t/secret t/stream-node t/utils t/xds-library

github的CI会对这些所有的任务执行测试。如果测试执行失败了，需要重点关注失败的日志，并在本地调试直到可以通过测试。如果遇到数据不对的问题，可以重新对数据进行初始化

apisix quit && apisix init && apisix init_etcd && apisix start

社区交流

在代码提交并创建了PR之后，我们可能会收到一些反馈，这时候我们就需要针对这些反馈作出回应。以#10771为例

我在提交了代码之后，管理员认为需要将aes_encrypt_pkey和aes_decrypt_pkey方法中的field字段去掉。我一开始在写代码的时候就发现这个字段去掉会导致数据加解密过程中ssl和data的行为不一致，可能导致错误。不过管理员让我放心删，没问题，本着信任的态度我就把参数删除掉了

但是删除掉了之后测试却怎么也跑不过，我因为非常信任社区管理员也没有怀疑是因为ssl和data逻辑不一致导致的，而是从其它地方入手进行排查。最终花了大量的时间经过了很多**的排查之后，发现其实就是因为ssl和data的行为逻辑不一致导致的。我随后询问了管理员，并且把field参数加了回来

把field参数加回来之后，所有的test cases就都能跑过了

参考

Revolution OS
S04E00-吴晟：开源项目进入 Apache 孵化器意味着什么
Apache 是如何运作的？
新手如何快速参与开源项目
如何从小白成长为 Apache Committer?