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

Posted 2021-05-25 OSC开源社区

给 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 参数，它可以把主仓库和子仓库源码都同时拉取。

1.1 设置 maven 加速

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

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

<?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 仓库也做代理：

<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 加速

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

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 项目的依赖关系，以及查找某个包被哪几个依赖给同时依赖的，在复杂项目中，分析项目的依赖关系很方便。

觉得不错，请点个在看呀