【融入开源】手把手带你给知名仓库贡献代码(Element Plus实战)

前言

为什么有野心有梦想的前端,一定要尝试去融入开源社区?

因为开源社区内藏着无数的宝藏,真正的宝藏。

最新的工具!对趋势的把握!亲眼见证大佬如何拆解复杂问题!看知名团队如何在两难中做出抉择!解决难题的技巧,迂回兼容的巧妙!
太多太多!
都是日常工作极少有机会面对,更遑论与人探讨的。
但是,在开源社区里,你可以向 Evan You 提出疑问,可以向 iamkun 贡献代码,可以和更多比你更加优秀的人一起完成一项工作;
那么,是的。
没有疑问,我们——选择加入!

第一步:如何筛选仓库?

要加入社区,但我们应该从哪里开始呢?
我的建议是,先选择 1~2 你平时工作/学习里最常用到的,且还不是特别稳定的库,如果是 alphabeta 版本优佳。

  • 经常用到。意味着你会更懂它,也更容易发现问题。
  • 版本还不稳定。意味着问题更多也更容易出现容易修复的问题。(对于咱初入者而言,这很重要)
  • Star较多。Star多意味着这个库有一定影响力,被很多人用,更容易发现问题;
  • 维护频繁。维护频繁,意味着你的PR会在短周期内被处理,这对维持积极性而言非常重要。

以我个人情况为例,我当前的主要技术栈以 vue3.x 为主,配合 Element Plus , vite , vite-press 等,按上面提到的几点综合考虑,我会选择这个库作为我近期 学习 的主要目标:

  • Element Plus (版本:1.2.0-beta.5)
  • vitepress (版本:0.20.2)

这两个库基本都充分符合上面我列举的几个要点。

image

Element Plus 为例:

  • 12.8K Star (超多点赞)
  • 2.2K Fork (被2.2K人次拉到自己的仓库)
  • 236K+ Download /Month (每月23万次+下载 )
  • 300+ Open Issues (至少有300个正在讨论未被关掉的问题)
  • 90+ Open PullRequest (90+个还未被合并的合并请求)
  • 170+ Commit Last Month (近1个月有170+ 次提交)
  • 著名UI库 ElementUI 2.x正统续作,专业性上不用担心,能学到更多东西和规范。
  • 我每天 8小时 用到它,更容易发现问题。

就我个人而言,这绝对是当前最最最适合我进行 尝试贡献 的库之一了。
如果按以上思路,最适合你进行 尝试 的库是什么呢?
如果也是 Element Plus,那也太有缘分了,可以多交流。

第二步: 如何寻找修改点 ?

一般而言,修改点有两种来源:

  • 在仓库的 issues列表 里寻找适合自己的问题。
  • 你自己在使用过程中遇到的问题。

a. 如何在 issues列表 淘问题?

Issues 可以被翻译成 问题。通常被用来 求助报告问题,寻求新特性等。

在项目的 issues列表 找适合自己的问题,绝对不是漫无目的的凭运气乱撞。而是有技巧的

首先,筛选 Open 状态的问题

Issue 分为 OpenClosed 两种状态。
Closed 状态的问题,要么已经被官方判定为无效issue,要么已经解决
因此,对于我们而言,完全可以保持 issue 列表页的搜索框里常年保持以下筛选条件:

 is:open 

其次,学会通过 Label 过滤

Label 的含义是标签,通常开源库的 维护者 会通过给不同类别的问题打不同的 Label 来更便捷的管理。

Element Plus 为例,它拥有72种不同的 Label:

image

有的表明 issue的种类 ,有点表明 涉及的组件,有的表明 它来自社区贡献,等等等等。但最最最重要的却是下面这两个tag:

  • PR welcome (欢迎提交PR)
  • Good for new contributor (适合新人贡献)

因此,我们可以直接选中二者之一,开始我们的 issue 探索之旅。

image

就像这样进行筛选。
然后,找到自己有思路的问题。

不要害怕英语,使用浏览器翻译或翻译插件!如果你英语特别好,那当我没说。

经过5分钟 中英结合 的搜寻,我锁定了一个问题:

image

"级联组件: 请添加一个选项,使筛选(搜索)不区分大小写。"

确认过眼神,是我能力范围内的问题。

点进去,经过对 Label 的判断,此 Issue 欢迎提交PR,且有 Feature Request(特性需求)。

因此,我们完全可以大胆地进行开发!

ok,以此为例,我们了解了 如何通过issue列表 找到适合我们的问题。

b. 自己发现的问题怎么办?

发现问题千万别急着提PR!先去 issue 列表搜一下!

某个问题,你是 第一个发现者 的概率其实并不大,因此对于咱们普通开发者而言,遇到的大多数问题,应该都能在 issue 列表里找到答案。
如果翻遍 issue 列表都没找到同病相怜者,恭喜你!你发现了一个新问题!
如果你经过研究,发现自己就能解决问题,那可太好了。
不过我推荐你还是要先建一个 issue 来描述你的问题,后续再解决这个 issue
这样,后来者可以发现这个问题已经被解决,也可以进行更详细的问题记录与跟踪。

image

注: 提ISSUE时不仅要遵循仓库的规范,请一定提供最小可复现实例

jsfiddle, codepen, codesandbox 都是极好的 最小可复现实例 工具。

比方说

我某天在工作时发现 El-Table 当设置了 tooltipEffect="light" 属性后,带有 show-overflow-tooltip 属性的列,在文本超长时,弹出的 tool-tip 样式存在1px的错位。

长这样:

image

在粗略看了一遍源码之后,我立刻意识到:
这bug我能改!

于是我利用工作之余的时间创建了 issue 并提交了解决此 issuePull Request

那么?

什么是 Pull Request 呢?又该如何提交?继续向下看吧。

第三步: 怎么fork仓库?

在进行代码修改之前,我们得先了解一下 github 开源仓库代码提交的基本模式: fork => Pull Request 模式。

image

通常情况下,你要向某个开源仓库贡献自己的代码(以 element-plus 为例):

  1. Fork!

element-plus 主仓库 fork 一份代码到你主页的 xxx/element-plus 仓库。(可以理解从 element-plus 复制了一份一模一样的代码)

  1. Commit!

在自己的仓库里修改 bug,并提交 commit 到自己的 xxx/element-plus 仓库里。

  1. PR!

element-plus 主仓库提起 Pull Request ,申请合入。(把自己的 commit 择出来,寄给主仓库的维护者,并告知他们你期望自己的代码能被合入到主仓库)

  1. NICE!

你的代码被合入,等待发版。

站在一个贡献者角度来看,贡献代码只需要按上面的步骤一步步执行即可。

那么,我们应该怎么 fork 代码呢?很简单,一键完成。

image

对,你只需要在 主仓库 的右上角轻轻点一下鼠标,就能完成 fork
很快,你的个人主页里,就会多出一个仓库:

image

没错,这就是你成功fork到的仓库,后续你的代码提交和推送,都需要在这个仓库里完成。

第四步:如何找到仓库的调试方法?

说到修复 bug ,那么 调试 一定是必不可少的一部,毕竟我们都只是凡人。

但是,我们所贡献的很多代码都不是 应用APP,而更大可能是一些提供 能力 的类库,如:
UI库调试工具脚本等等...
这样一来,我们就必须找到 如何高效调试 的方法。

方法1: 看 Contribute.md

大部分的仓库,都有专门写给贡献者看的贡献指南,它们的名字不一而足,有的叫 CONTRIBUTE.md,有的叫 DEV.md ,也有的叫 DEV_FAQ.md
通常这个文档都会告诉你应该"如何启动项目",以及"如何调试项目"。
element-plus 为例,它的 开发者指南 就名叫 DEV_FAQ.md
并在这个 .md 文件中介绍了三件事:

  1. 使用 pnpm i 安装依赖
  2. 使用 pnpm link 方式调试
  3. 别在 themescss 文件里写中文注释。
image

"开发者指南"的详尽指南需要碰运气,而我们必须通过其他途径了解项目的技能能力,那我们应该怎么做呢?

方法2:看 package.json 里的 scripts

众所周知,前端项目 package.json 里的 scripts 通常是整个项目各类脚本的 控制中心。包含但不限于:
commit 规范调试命令构建命令文档构建版本升级... 等等,各种各样的能力都在此汇聚。

可以说,了解了 scripts,也就了解了项目在 开发过程中 究竟能做哪些事。

element-plus 为例,让我们快速扫一眼它的 scripts 吧!

image

经过简单一扫,发现了一个可能会对我们调试非常有用的 脚本:

pnpm run dev

执行上面的命令,就能快速启动一个3000端口的服务,打开时会发现加载了几个 element-plus 组件。

而此 调试页面的入口 在这里:

play/main.ts

第五步:编写代码,修复BUG!

这一节,我本来想 略过 的。
毕竟:

改bug嘛!这谁不会啊?

image

好了,玩笑就开到这。
以我改的这个 issue #4697 为例。
为了修复这个bug,我总共做了一件事:

image

没错,一共就只删了一行代码而已。

第六步:按规范提交代码

看到这里,我先假设你已经完全"修复了 bug" 或 "实现了特性"。

那么,该如何提交代码呢?

1. 手动填写 commit-msg

不同的 项目 在细节上通常会有不同的要求。
commit 规范 通常情况下都是要求遵循 conventionalcommits 规范的。
# conventionalcommits 链接
conventionalcommits 规范,简单概括,其格式大抵如下:

# 类别 影响范围 : 简单描述
[optional scope]: 
# 详细描述
[optional body]
# 一些关联信息,如关联issue
[optional footer(s)]

举个栗子

# 类别 + 简单描述
feat: allow provided config object to extend other configs
# 类别 + 简单描述 + 不兼容更新声明(感叹号)
feat!: send an email to the customer when a product is shipped
# 类别 + 简单描述 + 不兼容更新声明(感叹号)+ 影响范围(括号内的内容)
feat(api)!: send an email to the customer when a product is shipped

更具体的描述大家可以点击上面的链接进行更加细致的学习,此处不再过多介绍。

2. 通过工具交互式提交

此方案不是方案1的替代式方案,而是某些仓库强制要求的 commit 规范!

熟悉开源社区的朋友可能会发现,越来越多的开源项目都开始 直接或间接 的依赖一款叫 commitizen (# 地址) 的 npm 包或者它的间接产物。
比如:element-plusyarn 就直接使用了它

image

这个工具的作用,便是"交互式"地"规范你的提交记录"。

ok,明白了这点,我们便可以"交互式"地开始提交我们的 commit-msg

element-plus 的提交过程为例,具体过程如下:

yarn cz
? Select the type of change that you're committing:
# 然后就会交互式地让你选择类别,包括:特性/feat,fix/修复,docs/文档,style/样式 等等
# 根据你的提交内容,选择合适的类别,比如你修复了一个bug,则通过移动光标选择 fix
> fix
? What is the scope of this change (e.g. component or file name): 
# 你的修改范围是什么?比如如果你修改了组件,就输入:components
> components
? Write a short, imperative tense description of the change (max 83 chars):
# 请您填写一个简短的祈使句来描述你做的变更。
# 祈使句的意思,如:让表格支持变形;修复 #0001;
# 以上面 “删掉一行代码” 的修复为例
> fix #4697 
? Provide a longer description of the change: (press enter to skip)
# 提供一个详细的描述
# 可以跳过
? Are there any breaking changes?
# 有不兼容的变更吗?
# N没有/Y有
? Does this change affect any open issues?
# 有什么相关的open状态的issue吗?
# 有点话Y,没有N

然后还会触发一些文件格式规范的流程,接着,你的commit才能成功。

这样做的好处,在于后续element-plus官方可以通过commit记录生成每个版本的CHANGELOG

第七步:全部通过单元测试

其实,这一步理论上来说,写在 commit 之前更加妥帖,毕竟改完代码你不跑跑测试用例,简直有点过分自信了。

如果你的修改是 bug-fix ,你只要正常通过 yarn test 问题通常就不大了。

但如果你的修改是新特性,那你可能还得自行添加一些用例。

比如,你添加的特性是:

增加一个 prop,当它为 true 时,按钮变成彩虹色

那你就必须增加一个测试用例,确保当它为 true 的时候,它真的已经变成了彩虹色,不然万一后续有哪个兄弟新增了一个特性或修复了一个bug,导致你的 按钮彩虹色 功能失效了,直到版本发布都不会有人发现。

这会直接导致某些特性在生产环境产生严重作用。

因此,跑用例写用例是每个想参与开源的朋友,必须养成的意识。

第八步:提交PR!

8.1 把代码推送到你 fork 出来的分支里去吧

# 假设你在 fix-4697 这个分支上修复bug
git push  origin fix-4697

8.2 生成PR

image

在你 fork 出来的项目里,打开 Pull Request tab,然后点击最右边绿色的 New Pull Request 按钮。
image

浏览你的 merge 信息,确认它们是否正是你想要提交的内容。

第九步:静候佳音

当你的PR被创建之后,不要焦虑,你能做的可能只有等待。

也许你会突然收到 github 站内信,你的 PR 被成功 合入,那就表示,从这一刻开始,你成为了这个 开源仓库 的贡献者之一。

主仓库insight标签里点击Contributors,开始尝试寻找你的名字吧!

image

现在开始,你可能已经算是这个开源仓库的贡献者之一了。

关于我

我是专注前端,专注vue,专注Element等框架的“前端要摸鱼”。
我的微公信众上号也叫 前端要摸鱼

获取最实用的前端技巧,每天快乐摸鱼,早早下班

你可能感兴趣的:(【融入开源】手把手带你给知名仓库贡献代码(Element Plus实战))