我参与了两个接近100k+star的开源项目！聊聊开源项目贡献指南

2020-08-28 11:12:33 浏览数 (1)

给 SkyWalking 以及 JavaGuide 项目贡献后的总结

  1. JavaGuide：https://github.com/Snailclimb/JavaGuide
  2. SkyWalking：https://github.com/apache/skywalking

1. 本地开发

以 SkyWalking 举例。在本地编译源码前，先查看相关的文档：https://github.com/apache/skywalking/blob/v8.0.1/docs/en/guides/How-to-build.md 。大致了解后，我们就可以开始操作了。

  1. 在 Github 上 fork 你想要贡献的项目
  2. 接着在本地拉取自己的项目：git clone --recurse-submodules https://github.com/$Name/skywalking.git

这是因为 SkyWalking 它包含了子仓库，因此加入了 --recurse-submodules 参数，它可以把主仓库和子仓库源码都同时拉取。

代码拉到本地后，接着我们使用 idea 打开该项目。 但是可能我们网络不够给力或有“奇怪的力量”干扰，我们则需要改动一些配置以方便快速编译。 对 maven 来说一般都是设置 maven 加速器，如果你拉的是 docker 相关，还需要配置 docker 容器阿里云地址加速。 而我们这里主要是设置 maven 阿里云镜像以及 npm 设置淘宝镜像。

1.1 设置 maven 加速

当你执行 ./mvnw clean package -DskipTests 会发现以下很慢：

说明从 apache.snapshots 仓库拉的很慢，因此我们对它使用镜像仓库代理，其中 mirrorOf 指定对某个仓库镜像做镜像代理加速，建议 mirrorOf 做明确指定代码的镜像仓库，避免直接使用 * 代理所有镜像，导致你公司的私仓或其它仓库出现拉不到包的情况：

代码语言：javascript复制
<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
    <mirrors>
        <mirror>
            <id>aliyun-apache.snapshots</id>
            <mirrorOf>apache.snapshots</mirrorOf>
            <name>aliyun-for-apahce.snapshots</name>
            <url>https://maven.aliyun.com/repository/apache-snapshots</url>
        </mirror>
    </mirrors>
</settings>

接着再执行 ./mvnw clean package -DskipTests，就发现开始使用我们代理仓库下载了：

同理对 center 仓库也做代理：

代码语言：javascript复制
<mirror>
    <id>aliyun-center</id>
    <mirrorOf>center</mirrorOf>
    <name>aliyun-for-center</name>
    <url>https://maven.aliyun.com/repository/public</url>
</mirror>

1.2 设置 npm 加速

因为有些项目里面包含前端项目（例如 Skywalking-ui），并且前端使用了 node 技术，则建议用淘宝镜像加速，在这个案例中，如下 skywalking/apm-webapp 模块中代码如下：

它使用了插件来执行 npm 命令用于生成前端代码，但是 npm 拉依赖包会比较慢，因此这里修改为淘宝镜像地址：将 registry.npmjs.org 修改为：registry.npm.taobao.org。

1.3 编译

还有其它的设置，例如在 SkyWalking 中需要设置 gRPC 为源码包等，因为在官方的文档有详细步骤，就不做说明了。而 JavaGuide 项目不用编译，打开即可，都是 md 类型的文档。

2. 提 Issue

本地代码编译后，接着你可能会有两个操作：

  1. 你发现仓库中有个地方的代码写的不好，而且你正好对这块代码所涉及的技术深有研究，那么你先不用直接写代码，而是先去对应的仓库提 Issue，因为很多的仓库，不会莫名其妙的接收用户的 PR，需要先有对应的 Issue，便于作者了解需要改进的地方或知道你即将发起 PR 的缘由。Issue 一般会有模板并用 markdown 语法，只需要清楚的表达自己的问题描述就可以了。
  2. 你发现仓库已有了某个 Issue，而且你知道怎么解决该问题，以 JavaGuide 举例，里面有时候会有些文字描述不当或文章有错别字等这些错误，这对大家来说改进比较容易，因此你可以直接在本地新建分支做对应的改动。

2.1 Issue 艺术

Issue 本质也类似于提问，因此需要清楚的表达你的疑惑并能让别人看得懂。假如你是作者，你看到你的仓库有如下两个 Issue，你更加中意哪个？

但是很多项目都是要求英语交流，我都是先通过谷歌翻译，接着看下翻译之后的地方哪里表述有问题，再自己手动调整，其实表述大家都看得懂，还能顺便学英语，例如我之前的 Issue：

2.2 Issue 的交流

一般 Issue 提出后，都会有相关的人做讨论和交流。以 JavaGuide 举例，里面有些 Issue 讨论也可以学到很多的东西的，如下：

上图可以看出作者对这类文章标记了 discuss 标签，这样你可以更加方便的搜索该标签查找有价值的 Issue 了。

2.3 本地基本操作

这时候我们可以撸起袖子敲代码了。定位你想要修改的代码块，你可以动手本地新建分支，修改，测试代码。 注意：秉承一个分支改动一个功能点的理念。你改动代码时，建议只改动 Issue 提及的相关的代码，如果你想这个分支做多个改动，记得同步到 Issue 中。但是如果你发现了另一个改进点，但是这两个改进点无任何联系，建议再新建个 Issue，并再建个分支，在两个分支分别做改动。这样主要是如下理由：

  1. 假如你在改动点 1 的代码有问题，而在改动点 2 的代码没问题。但是由于它们是两个独立的分支，因此就不会互相影响，作者可以先 merge 你的分支 2（在公司也建议如下操作，一个分支一个改动点，方便出问题回滚）。

如果你本地做了多个提交，建议使用 git rebase 命令将多个提交合并为一个提交（仅建议）。

涉及到的基本命令：

  1. 本地新建分支：git checkout -b feature/word_typo
  2. 本地所有改动加入暂存区：git add .
  3. 将暂存区提交：git commit -m "commit message"
  4. 增加原仓库上游地址：git remote add upstream https://github.com/apache/skywalking.git
  5. 与远程 master 分支合并：git merge upstream/master
  6. 提交到自己的远程仓库：git push --set-upstream origin feature/word_typo

对第 4 步的解释：因为你本地仓库的远程地址默认为你自己的远程仓库，但是你需要实时和源仓库做同步更新，因此你额外需要保存源仓库的地址，用于与源 master 合并，同步来自源仓库的最新代码。

3. 准备 PR

3.1 PR 通过

当你 push 当你的远程仓库后，此时你打开源仓库，你会发现多了如下提示：

我们点击 Compare & pull request 按钮，就会到 PR 界面了，如果作者配置了 PR 模板，我们跟着提示输入即可，PR 界面主要做两个事：

  1. 查看你本次提交代码与源仓库主干的改动点。
  2. 与作者讨论此时 PR 的代码，以及你此时 PR 的理由（在这里你可以使用 #111 来与你之前的 Issue 做关联）。
  3. 做对应的持续集成。

如果跟作者进行友好的交流讨论后，没什么问题，你的 PR 就会被合并

接着在源仓库中就会显示当前的 PR 标题，以及你 PR 对应的 Issue。

3.2 PR 不通过

但是更多时候 PR 会不通过，一般大概有两种：

  1. 代码审核不通过：你提交的 PR 代码有问题，审核你代码的作者会在 PR 讨论跟你说哪里有问题，哪个地方需要改进，我们只需要跟着改动即可。
  2. CI(持续集成) 有问题。这表明你的代码没问题，但是单元测试或持续集成验证没通过：在大型项目中，都会集成持续集成方案，如果你公司已经在使用了 CI，那就比较熟练了，跟着 Docker 报错日志仔细看看哪个地方有问题就行了。以 SkyWalking 举例，它有个持续集成的测试步骤是这样的：启动 Docker 模拟项目启动，模拟对应的请求，并与预期结果文件做对比，如果发现响应与预期结果文本对比异常，就会报错不通过。这种情况我们可以通过 Github 的 Action 日志做排查。

这里建议了解如下：

  1. Github Action：持续集成方案。公司一般会用 GitLab/Jenkins 多点。大概是监听你的代码某个分支的提交/合并来做一系列的事，比如触发某个脚本等。
  2. Codecov：测试覆盖率方案。公司一般会用 Sonar 比较多。
  3. Checkstyle：如果你代码没问题，但是规则检查没通过，也会不允许合并。具体是注释不规范还是代码格式不规范查看具体的报错即可。

4. 跟踪项目进度

我们想实时跟进项目的进度或讨论的话，可以有以下方式（国外的讨论方式就不做列举了）分别以 JavaGuide 和 SkyWalking 举例：

  1. RSS 订阅 Issue 相关信息，例如：https://rsshub.app/github/issue/Snailclimb/JavaGuide 。最后两个为变量，可以自由修改，规则为：UserName/RepositoryName
  2. 加入群/关注 B 站，探（mo）讨（yu）技术
  3. 邮件订阅，具体参考 dubbo：http://dubbo.apache.org/zh-cn/docs/developers/contributor-guide/mailing-list-subscription-guide_dev.html。适用于任何 apahce 项目，记得把 dubbo 改为具体项目即可（这里改为 skywalking）。
  4. 参加线下活动：例如和某个社区伙伴面基、在活动行 APP 里面中关注项目线下宣传什么的（而且阿里云相关的线下活动都有抽奖和零食）。

5. 额外

实际上，我们需要额外的插件来提高我们的效率。

Github 插件推荐两个：

  1. Octotree 用于可视化 Github 项目文件层级，你不用一个一个点进去就能看到全貌了。
  2. GitZip 用于单独下载某个文件/文件夹，不用为了下载某个文件，要把整个项目下载下来。

idea 插件推荐一个：Maven Help：分析某个 maven 项目的依赖关系，以及查找某个包被哪几个依赖给同时依赖的，在复杂项目中，分析项目的依赖关系很方便。

其实关注 JavaGuide 微信公众号的都会了解 JavaGuide 项目，但是项目贡献的人很少，也有很多人很久没有再继续贡献和讨论了。这篇文章只是做抛砖引玉，希望大家能能了解 JavaGuide 原项目，当然能参与进来贡献那肯定是最好的。毕竟 JavaGuide 是我贡献的开源项目里坚持最久的~希望它能一直活力四射~

https 网络安全 cci持续集成 git

0 人点赞