Skip to content
Xu,Yizhi edited this page Dec 28, 2015 · 16 revisions

这篇文章将描述我们大家如何一起完善lark.js框架的机制。

准备工作

贡献代码前需要先了解git工具的使用和github网站的使用。

github 贡献代码流程

提issue

不管你是修复lark.js的bug还是新增lark.js的功能,在你提交代码之前,在lark.js的github上提交一个 issue, 描述你要修复的问题或者要增加的功能。这么做有几个好处:

  • 不会与其它开发者的开发或是他们对这个项目的计划发生冲突.
  • lark.js的维护人员会对你提的bug或者新增功能进行相关讨论,确定该修改是不是必要,有没有提升的空间或更好的办法。
  • 在达成一致后再提交代码,减少双方沟通成本,也减少pull request被拒绝的情况。

获取源码

要修改或新增功能,在提issue后,点击左上角的fork按钮,复制一份lark.js主干代码到你的代码仓库。

(如果你是lark.js github维护人员,有lark.js在github上的权限,那么你要贡献代码时可以直接拉取主干最新代码。)

拉分支

lark.js 所有修改都在分支上进行,修改完后提交 pull request , 在code review 后由项目维护人员 merge 到主干。 因此,在获取源码步骤介绍后,你需要:

  • 下载代码到本地
git clone https://github.com/你的仓库名/lark.git 
  • 拉分支准备修改代码
git branch update_xxx_feature

执行完上述命令后,你的代码仓库就切换到相应分支了。执行如下命令可以看到你当前分支:

git branch -a

如果你想切换回主干,执行下面命令:

git checkout -b master

如果你想切换回分支,执行下面命令:

git checkout -b "branchName"

想直接从github上拉取分支到本地

git clone -b branchname https://xxx.git

修改代码提交到本地

拉完分支后,就可以修改代码了。

修改代码注意事项

  • 代码风格保持一致

lark.js 通过 jshint 保持代码风格的一致。首先你要安装jshint工具。

sudo npm install -g jshint

在你修改完代码后,准备提交代码之前,运行

jshint .

jshint 会自动检查代码风格是否符合要求,并对不符合要求的代码进行提示。你安装提示修改完代码,直到不再有错误提示。这时候你的代码就符合lark.js约定俗成的代码风格了。

  • 补充单元测试代码

    • 新有修改应该通过已有的单元测试.
    • 应该提供新的单元测试来证明以前的代码存在bugs,而新的代码已经解决了这些bugs

你可以用如下命令运行所有测试

npm test
  • 代码修改完后进行性能测试

其它注意事项

  • 请保持你编辑的代码的原有风格
  • 对于无用的注释, 请删除它们
  • 对逻辑和功能不容易被理解的地方添加注释
  • 更新文档

修改完代码后,执行如下命令提交所有修改到本地:

git commit -am '添加本次提交说明'

提交代码到远程仓库

在代码提交到本地后,就是与远程仓库同步代码了。执行如下命令提交本地修改到github上:

git push origin "branchname"

需要注意的是,如果你没有lark.js代码仓库的权限,那么这里的 origin 是你的代码仓库,而不是lark.js的代码仓库

提交合并代码到主干的请求

在你的代码提交到github后,并一切准备就绪后,你就可以发送请求来把你改好的代码合入lark.js主干代码了。此时你需要进入你的github上的对应仓库,按右上角的 pull request按钮。系统会通知lark.js的维护人员,有一份新的代码修改提交了。lark.js维护人员会review你的代码,符合要求后就会合入主干,成为lark.js的一部分。

代码review

在你提交代码后,你的代码会被指派给至少一个代码维护人员review。请保持耐心。如果在数天后,仍然没有人对你的补丁给予任何回复,请给予一些友好的提示。

在你按了pull request按钮后,你可以去之前提的 issue 下面恢复该提交的 hash 值,让本次提交和issue关联上,方面reviewer 检查相关情况。

reviewer的意见会提交到对应issue。如果你觉得其它人的建议是合理的,也请你把这些建议加入到你的补丁中。

合并代码到主干

在代码review 通过后,就由larkjs 维护人员操作合入主干了。如果你是larkjs的维护人员,拥有larkjs仓库权限,并且代码提交到了larkjs的主干,那么你需要进入larkjs的代码仓库, 这时在仓库的页面头部会有github提示的合并分支到主干的提示,按下这个按钮进行合并就好了。

npm 发布

代码合入主干后,会随定期发布的新版发布到npm上。

如果你是npm上的larkjs包管理员,你可以通过如下步骤发布新版本到npm上

查看有larkjs npm 管理权限的用户组

npm owner ls

如果你没有权限,找相关人员给你添加权限

npm owner add <user> 

更多细节查看npm官方文档

最后,请注意一点:即使你的补丁没有被提交,它仍然有用的。

相关文档: git flow