有赞开源项目最佳实践

由于业务需求，有赞本身造了不少轮子，组件库尤为多，React，Vue，小程序都有涉及，其余开源项目有 zan-proxy 代理，PHP 的框架 zanphp 等。有人可能会以为奇怪，为何有赞要造这么多轮子？其实缘由真的很简单，就是由于现有的替代品没法知足咱们自身业务的需求，多是不知足咱们的定制需求，也多是功能不符合咱们要求。根据业务须要，咱们总结了一套适合本身的套路、规范，并把这些套路、规范作成了工具、组件库或者框架。

这大概即是有赞内部启动这些项目的原因了。后来，随着这些项目的逐步完善，一个天然而然的想法就是把它们开源了，也许别人也有相似咱们的需求。

慢慢的，有赞的 Github 上就有了好多开源项目。在维护这些开源项目的过程当中咱们总结了一些经验教训，在此跟你们分享。

1、有赞的 Github 使用姿式

Github 有必定的社交属性，维护好一个开源项目除了代码写得好，有一些使用姿式也是很重要的，咱们总结了几点跟你们分享。

1. 一个好的 README 很重要

README 文件是项目给人的第一印象，所谓人靠衣装马靠鞍，开源项目有个好的脸面是很重要的，尤为是当这个项目仍是一个前端项目的时候。针对 README 文件咱们给出如下几点建议：

• 同一个组织的 README 统一格式
• 最好有个英文版的 README
• 加上开发指南的连接

统一 README 格式的好处是让别人一眼就认出这个项目是某某公司或者某某人的，有赞内部就维护了一份 README 的规范。模版内容很简单，可是它保证了咱们的项目有必定的识别度。

英文版的 README 不是为了装逼，若是你笃定本身的用户都在国内，那就只须要中文版的 README 就能够了。可是大部分状况下，项目维护者都但愿本身的代码可以帮助到更多人，包括国外的用户，这时候英文 README 的价值就体现出来了。

开发指南很容易被忽略，它存在的目是帮助那些但愿加入项目开发的开发者们快速上手。做为参与开源项目的开发者，他们对开发指南有哪些指望？我以为无外乎几点：

• 如何搭建开发环境？
• 有哪些未解决的问题须要帮助？
• 如何提交代码？

若是开发指南可以回答这几个问题，有经验的开发者就能够比较快的参与进来。

2. 善用 Github 的 Issue 和 PR 模版

相信不少人都遇到过这样一个尴尬的事情：有人在 Github 上提了一个 Issue，可是你看不懂这个 Issue 的描述，也不知道如何重现这个 Issue。

Github 提供了一个机制让项目维护者可以预先写好 Issue 或者 PR 的模版，其余人过来提 Issue 或者 PR 的时候就能够在这个模版上修改。模版里能够有针对性的告诉提 Issue 的人须要填写那些信息，这样子大部分时候均可以免上面提到的尴尬场面。

建立这些模版也很简单，常见的方式是在仓库的 .github 隐藏目录下建立对应的模版 Markdown 文件。最近 Github 刚刚更新了模版机制，容许同时建立多个 Issue / PR 的模版。

例如 babel 仓库的 Issue 模版就有多个模版，每一个模版对应不一样的 Issue 类型，具体配置文档能够看这里。

3. Labels

Github 的 Labels 功能主要是用来给 Issue / PR 作分类的，方便索引和搜索。这里主要想说的一点是 Github 默认建好的 Labels 其实并很差用，咱们推荐将 Label 分红几个正交的惟独，每一个维度对应几个不一样的 Label，能够参看这篇文章。

不少新手容易忽略 Label 这个功能，配合适当的 Label 分类，每一个 Issue 均可以有一个很直观的状态展现。

4. 持续集成系统

Github 和 CI 系统的整合很是紧密，我的以为体验作的很好。CI 系统能够用来作一些单元测试，代码风格检查等。不少仓库里 README 文件上的代码覆盖率数据都是在 CI 系统中生成提交的。

CI 除了用来运行单侧，还能够用来作其余必要的代码检查。例如 Zent 仓库中有一个脚本会在 CI 上检查提交的代码有没有按规范书写，若是发现代码格式不对，那么颇有可能开发者没有在本地安装咱们的 git 钩子，这时咱们会提示开发者在本地安装钩子，格式化代码而后从新提交。

#!/bin/bash 
# Ensure everyone installs the git hook.
# The result is a guess, but false positive
# is not an issue here.

RED='\033[0;31m'
basepath=$(dirname $0)

fail () {
    printf "${RED}$@\nAborting\n"
    exit -1
}

pushd $basepath/.. >/dev/null 2>&1
yarn prettify
git diff-index --quiet HEAD --
rv=$?
popd >/dev/null 2>&1

if [ $rv -ne 0 ]; then
  git diff-index HEAD --
  fail 'Git hooks not installed. Follow these instructions on your local machine:\n1. yarn install\n2. yarn prettify\n3. Commit your changes and push.'
fi
复制代码

这里顺带说一下 Github 上经常使用的两个 CI 系统使用感觉：

• Travis 服务稳定性比较好，并且 Travis PR 的 build 是运行在源分支和当前 PR 分支的 merge 结果上的
• CircleCI 性能较好，可是稳定性相对较差，偶尔会抽风

Github 最近又上了一个新功能 Checks API，这个功能能够当作是原来 PR 和 CI 集成的一个升级版本，能够看见更加详细的测试以及 Lint 报告。

5. 项目进度把控

GitHub 有两个项目管理的工具，Milestone 和 Project。Project 能够显示一个相似看板的功能，而 Milestone 的定位更加轻量，相似一个任务集合的 deadline 管理工具。对大部分开源项目而言，可能 Milestone 更加合适。

2、技巧分享

上面介绍了一些 Github 的使用技巧，这里再分享一些项目开发、发布以及维护过程的一些小技巧。一个开源项目决不只仅是一串代码而已，它更是一个技术产品，这就要求咱们以产品的要求来看待这个问题。

1. 版本发布遵循生态系统的规范

之前端为例，NPM 的生态中绝大部分包都是使用 Semantic Versioning 的，若是咱们项目的包不按照这个规则作，那么很容易给使用者一个 “surprise”。对于版本号没必要恐惧它的数字愈来愈大，它仅仅是一个数字而已。

2. 代码规范

相信只要是个成熟的项目确定都有本身的编码规范，有些项目可能提供了文档，告诉代码贡献者应该如何编码，同时也会有相应的 review，确保代码是符合规范的。可是，若是仅仅是代码样式方面的规范，咱们建议经过工具来确保规范的落地。咱们不提供编码规范的文档，可是咱们有脚原本格式化全部提交过来的代码。效果就是代码随你怎么写，可是最终提交到 master 分支上都确定都是按相同的规范书写的。

这类格式化工具备不少，例如前端领域用的比较多的 Prettier，Go 语言自带的 gofmt，以及 Reason 的 refmt 等。花点时间 Google 一下，找一个适合你项目的格式化工具。

3. Squash Merging

Github 针对 PR 提供了三种 merge 选项，这里推荐只开启 squash merge 这一种。所谓 squash merge 是指将 PR 分支上全部提交合并成一个新的 commit，而后将这个 commit 经过 fast-forward 的方式合并到目标分支，咱们认为这种方式是最适合走 PR 的项目的。固然，若是你但愿保留 PR 上的每个提交记录，那么建议使用 rebase 的方式，无论是经过 Github 操做仍是本身本地 rebase 后再提交。

4. 更新日志

为了减小每次发布的工做量，咱们之前的更新日志是脚本根据 Github 的 Issue 以及 PR 记录自动生成的。可是咱们慢慢发现因为 Isssue 以及 PR 的标题规范性不是那么好，致使更新日志的可读性变得比较差。另一个问题是机器生成的更新日志它无法作到把同一组件的修改归类整理到一块儿，这也是可读性较差的一个缘由。

咱们如今的更新日志是经过脚本先生成一份“草稿”，而后由包的发布者在这个基础上总结提炼出一份方便阅读的更新日志。这种方式增长了一些发布者的工做量，可是更新日志的可读性有较大提高，投入产出比仍是能够接受的。

5. 技术产品的售后服务

“售后服务”是作开源项目的时候最容易被忽视的一点，若是咱们以技术产品的要求去维护一个开源项目，那么咱们就有责任给用户提供必要的支持。这些支持包括：完善的产品文档，答疑的群组以及一些产品技术博客。有了这些“售后服务”咱们才能造成一个完整的技术产品闭环，经过用户的反馈不断完善。

3、总结

本文从 Github 的使用姿式切入，在项目开发、发布、维护以及文档生成等方面分享了一些咱们认为正确的开源项目维护心得。咱们始终保持开放的心态，欢迎各位给咱们提建议，一块儿改进开源项目的管理方式。

附录

一些可能有用的工具连接：

• lerna: 大仓库（Mono Repository）管理工具
• github-changelog-generator: Change log 自动生成工具
• conventional-changelog: 另外一个 Change log 生成工具
• git-labelmaker: 自动建立 Github Labels