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

原创
08/27 09:19
阅读数 2.6W

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

  1. JavaGuidehttps://github.com/Snailclimb/JavaGuide
  2. SkyWalkinghttps://github.com/apache/skywalking

1. 本地开发

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

  1. Githubfork 你想要贡献的项目
  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 做明确指定代码的镜像仓库,避免直接使用 * 代理所有镜像,导致你公司的私仓或其它仓库出现拉不到包的情况:

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

因为有些项目里面包含前端项目(例如 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 模拟项目启动,模拟对应的请求,并与预期结果文件做对比,如果发现响应与预期结果文本对比异常,就会报错不通过。这种情况我们可以通过 GithubAction 日志做排查。

这里建议了解如下:

  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 是我贡献的开源项目里坚持最久的~希望它能一直活力四射~

最后

我整理的4本PDF文档,本公众号后台回复“面试突击”即可免费获取。

文章有帮助可以点个「在看」或「分享」,都是支持,我都喜欢!

我是Guide哥,Java后端开发,会一点前端知识,喜欢烹饪,自由的少年。一个三观比主角还正的技术人。我们下期再见!


往期推荐



大白话带你认识 ZooKeeper !重要概念一网打尽!

简单聊聊为什么有些大公司技术弱爆了?

入职外包3个月,我离职了...

为什么我要从 Windows 切换到 Linux?

以 B 站为例,聊聊站内消息系统的设计

来吧!手写一个 RPC 框架。毕设/项目经验稳了!

本文分享自微信公众号 - JavaGuide(JavaGuide)。
如有侵权,请联系 support@oschina.cn 删除。
本文参与“OSC源创计划”,欢迎正在阅读的你也加入,一起分享。

展开阅读全文
打赏
1
44 收藏
分享
加载中
感谢分享,我也在尝试,希望能给开源做些贡献
前天 14:40
回复
举报
不错哦
前天 11:14
回复
举报
感谢分享
10/18 22:46
回复
举报
很不错👍
10/18 22:31
回复
举报
更多评论
打赏
4 评论
44 收藏
1
分享
返回顶部
顶部