我参与了两个接近100k+star的开源项目!聊聊开源项目贡献指南
给 SkyWalking
以及 JavaGuide
项目贡献后的总结
-
JavaGuide
:https://github.com/Snailclimb/JavaGuide -
SkyWalking
:https://github.com/apache/skywalking
1. 本地开发
以 SkyWalking
举例。在本地编译源码前,先查看相关的文档:https://github.com/apache/skywalking/blob/v8.0.1/docs/en/guides/How-to-build.md 。大致了解后,我们就可以开始操作了。
- 在
Github
上fork
你想要贡献的项目 - 接着在本地拉取自己的项目:
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
本地代码编译后,接着你可能会有两个操作:
- 你发现仓库中有个地方的代码写的不好,而且你正好对这块代码所涉及的技术深有研究,那么你先不用直接写代码,而是先去对应的仓库提
Issue
,因为很多的仓库,不会莫名其妙的接收用户的PR
,需要先有对应的Issue
,便于作者了解需要改进的地方或知道你即将发起PR
的缘由。Issue
一般会有模板并用markdown
语法,只需要清楚的表达自己的问题描述就可以了。 - 你发现仓库已有了某个
Issue
,而且你知道怎么解决该问题,以JavaGuide
举例,里面有时候会有些文字描述不当或文章有错别字等这些错误,这对大家来说改进比较容易,因此你可以直接在本地新建分支做对应的改动。
2.1 Issue 艺术
Issue
本质也类似于提问,因此需要清楚的表达你的疑惑并能让别人看得懂。假如你是作者,你看到你的仓库有如下两个 Issue
,你更加中意哪个?
但是很多项目都是要求英语交流,我都是先通过谷歌翻译,接着看下翻译之后的地方哪里表述有问题,再自己手动调整,其实表述大家都看得懂,还能顺便学英语,例如我之前的 Issue:
2.2 Issue 的交流
一般 Issue
提出后,都会有相关的人做讨论和交流。以 JavaGuide
举例,里面有些 Issue
讨论也可以学到很多的东西的,如下:
上图可以看出作者对这类文章标记了 discuss
标签,这样你可以更加方便的搜索该标签查找有价值的 Issue
了。
2.3 本地基本操作
这时候我们可以撸起袖子敲代码了。定位你想要修改的代码块,你可以动手本地新建分支,修改,测试代码。
注意:秉承一个分支改动一个功能点的理念。你改动代码时,建议只改动 Issue
提及的相关的代码,如果你想这个分支做多个改动,记得同步到 Issue
中。但是如果你发现了另一个改进点,但是这两个改进点无任何联系,建议再新建个 Issue
,并再建个分支,在两个分支分别做改动。这样主要是如下理由:
- 假如你在改动点 1 的代码有问题,而在改动点 2 的代码没问题。但是由于它们是两个独立的分支,因此就不会互相影响,作者可以先 merge 你的分支 2(在公司也建议如下操作,一个分支一个改动点,方便出问题回滚)。
如果你本地做了多个提交,建议使用 git rebase 命令将多个提交合并为一个提交(仅建议)。
涉及到的基本命令:
- 本地新建分支:
git checkout -b feature/word_typo
- 本地所有改动加入暂存区:
git add .
- 将暂存区提交:
git commit -m "commit message"
- 增加原仓库上游地址:
git remote add upstream https://github.com/apache/skywalking.git
- 与远程 master 分支合并:
git merge upstream/master
- 提交到自己的远程仓库:
git push --set-upstream origin feature/word_typo
对第 4 步的解释:因为你本地仓库的远程地址默认为你自己的远程仓库,但是你需要实时和源仓库做同步更新,因此你额外需要保存源仓库的地址,用于与源
master
合并,同步来自源仓库的最新代码。
3. 准备 PR
3.1 PR 通过
当你 push
当你的远程仓库后,此时你打开源仓库,你会发现多了如下提示:
我们点击 Compare & pull request
按钮,就会到 PR
界面了,如果作者配置了 PR
模板,我们跟着提示输入即可,PR
界面主要做两个事:
- 查看你本次提交代码与源仓库主干的改动点。
- 与作者讨论此时
PR
的代码,以及你此时PR
的理由(在这里你可以使用 #111 来与你之前的 Issue 做关联)。 - 做对应的持续集成。
如果跟作者进行友好的交流讨论后,没什么问题,你的 PR
就会被合并
接着在源仓库中就会显示当前的 PR
标题,以及你 PR
对应的 Issue
。
3.2 PR 不通过
但是更多时候 PR
会不通过,一般大概有两种:
- 代码审核不通过:你提交的
PR
代码有问题,审核你代码的作者会在PR
讨论跟你说哪里有问题,哪个地方需要改进,我们只需要跟着改动即可。 -
CI
(持续集成) 有问题。这表明你的代码没问题,但是单元测试或持续集成验证没通过:在大型项目中,都会集成持续集成方案,如果你公司已经在使用了CI
,那就比较熟练了,跟着Docker
报错日志仔细看看哪个地方有问题就行了。以SkyWalking
举例,它有个持续集成的测试步骤是这样的:启动Docker
模拟项目启动,模拟对应的请求,并与预期结果文件做对比,如果发现响应与预期结果文本对比异常,就会报错不通过。这种情况我们可以通过Github
的Action
日志做排查。
这里建议了解如下:
-
Github Action
:持续集成方案。公司一般会用GitLab
/Jenkins
多点。大概是监听你的代码某个分支的提交/合并来做一系列的事,比如触发某个脚本等。 -
Codecov
:测试覆盖率方案。公司一般会用Sonar
比较多。 -
Checkstyle
:如果你代码没问题,但是规则检查没通过,也会不允许合并。具体是注释不规范还是代码格式不规范查看具体的报错即可。
4. 跟踪项目进度
我们想实时跟进项目的进度或讨论的话,可以有以下方式(国外的讨论方式就不做列举了)分别以 JavaGuide 和 SkyWalking
举例:
- RSS 订阅 Issue 相关信息,例如:https://rsshub.app/github/issue/Snailclimb/JavaGuide 。最后两个为变量,可以自由修改,规则为:UserName/RepositoryName
- 加入群/关注 B 站,探(mo)讨(yu)技术
- 邮件订阅,具体参考 dubbo:http://dubbo.apache.org/zh-cn/docs/developers/contributor-guide/mailing-list-subscription-guide_dev.html。适用于任何
apahce
项目,记得把dubbo
改为具体项目即可(这里改为skywalking
)。 - 参加线下活动:例如和某个社区伙伴面基、在活动行 APP 里面中关注项目线下宣传什么的(而且阿里云相关的线下活动都有抽奖和零食)。
5. 额外
实际上,我们需要额外的插件来提高我们的效率。
Github
插件推荐两个:
-
Octotree
用于可视化Github
项目文件层级,你不用一个一个点进去就能看到全貌了。 -
GitZip
用于单独下载某个文件/文件夹,不用为了下载某个文件,要把整个项目下载下来。
idea
插件推荐一个:Maven Help
:分析某个 maven
项目的依赖关系,以及查找某个包被哪几个依赖给同时依赖的,在复杂项目中,分析项目的依赖关系很方便。
其实关注 JavaGuide
微信公众号的都会了解 JavaGuide
项目,但是项目贡献的人很少,也有很多人很久没有再继续贡献和讨论了。这篇文章只是做抛砖引玉,希望大家能能了解 JavaGuide
原项目,当然能参与进来贡献那肯定是最好的。毕竟 JavaGuide
是我贡献的开源项目里坚持最久的~希望它能一直活力四射~
- JavaScript 教程
- JavaScript 编辑工具
- JavaScript 与HTML
- JavaScript 与Java
- JavaScript 数据结构
- JavaScript 基本数据类型
- JavaScript 特殊数据类型
- JavaScript 运算符
- JavaScript typeof 运算符
- JavaScript 表达式
- JavaScript 类型转换
- JavaScript 基本语法
- JavaScript 注释
- Javascript 基本处理流程
- Javascript 选择结构
- Javascript if 语句
- Javascript if 语句的嵌套
- Javascript switch 语句
- Javascript 循环结构
- Javascript 循环结构实例
- Javascript 跳转语句
- Javascript 控制语句总结
- Javascript 函数介绍
- Javascript 函数的定义
- Javascript 函数调用
- Javascript 几种特殊的函数
- JavaScript 内置函数简介
- Javascript eval() 函数
- Javascript isFinite() 函数
- Javascript isNaN() 函数
- parseInt() 与 parseFloat()
- escape() 与 unescape()
- Javascript 字符串介绍
- Javascript length属性
- javascript 字符串函数
- Javascript 日期对象简介
- Javascript 日期对象用途
- Date 对象属性和方法
- Javascript 数组是什么
- Javascript 创建数组
- Javascript 数组赋值与取值
- Javascript 数组属性和方法
- 原创 | 随机数大家都会用,但是你知道生成随机数的算法吗?
- 原创 | codeforces 1425E,一万种情况的简单题
- 原创 | codeforces 1417C,逆向思考的数据结构题
- 原创 | 操作失误不要慌,这个命令给你的Git一次反悔的机会
- 原创 | 想做推荐算法?先把FM模型搞懂再说
- 活见鬼,明明删除了数据,空间却没减少!
- 原创 | Git仓库的提交记录乱成一团,怎么办?
- 原创 | 平面内有N个点,如何快速求出距离最近的点对?
- 原创 | codeforces 1426F,初学者也能做,div3的最难题
- 安全研究 | YARA规则阻止Windows事件日志记录
- 研究人员如何使用Shhgit搜索GitHub中的敏感数据
- 使用nProbe监控移动网络(2G,3G和LTE)
- Mykings僵尸网络新变种已感染超5万台电脑
- 谁告诉你鸿蒙(HarmonyOS)不能在macOS下玩,一副没见过世面的样子!
- 连Python产生器(Generator)的原理都解释不了,还敢说Python用了5年?