4月10-12日 QCon 北京,与全球 140+ 顶尖工程师共同解构 AI 时代的技术浪潮! 了解详情
写点什么

有赞开源项目最佳实践

  • 2020-03-08
  • 本文字数:3333 字

    阅读完需:约 11 分钟

有赞开源项目最佳实践

因为业务需求,有赞自己造了很多轮子,组件库尤其多,React,Vue,小程序都有涉及,其他开源项目有 zan-proxy 代理,PHP 的框架 zanphp 等。有人可能会觉得奇怪,为什么有赞要造这么多轮子?其实原因真的很简单,就是因为现有的替代品无法满足我们自身业务的需求,可能是不满足我们的定制需求,也可能是功能不符合我们要求。根据业务需要,我们总结了一套适合自己的套路、规范,并把这些套路、规范做成了工具、组件库或者框架。


这大概便是有赞内部启动这些项目的缘由了。后来,随着这些项目的逐步完善,一个自然而然的想法就是把它们开源了,也许别人也有类似我们的需求。


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

一、有赞的 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>&1yarn prettifygit 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 更加合适。

二、技巧分享

上面介绍了一些 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. 技术产品的售后服务

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

三、总结

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

附录

一些可能有用的工具链接:


  • lerna: 大仓库(Mono Repository)管理工具

  • github-changelog-generator: Change log 自动生成工具

  • conventional-changelog: 另一个 Change log 生成工具

  • git-labelmaker: 自动创建 Github Labels


2020-03-08 19:24805

评论

发布
暂无评论
发现更多内容

太方便了,钉钉上就可完成代码发布审批啦!

阿里云云效

云计算 阿里云 钉钉 jenkins 代码

第十八届IET交直流输电国际会议(ACDC2022)于线上成功举办

E科讯

PingCode 性能测试之负载测试实践

PingCode研发中心

软件测试 PingCode

DataKit——真正的统一可观测性 Agent

观测云

智捷云——元宇宙综合解决方案服务商

智捷云

区块链 元宇宙 智捷云 区块链技术开发

什么是低代码开发?

AIRIOT

低代码 物联网 低代码,项目开发

五千字讲清楚团队自组织建设 | Liga 妙谈

LigaAI

团队管理 个人提升 敏捷开发管理 LigaAI 自组织协作

Python 入门指南之使用 Python 解释器

海拥(haiyong.site)

7月月更

TCP两次挥手,你见过吗?那四次握手呢?

C++后台开发

网络编程 网络协议 TCP/IP 后端开发 C++开发

激进技术派 vs 项目保守派的微服务架构之争

BoCloud博云

微服务 微服务架构 云原生 istio 服务网格

整理混乱的头文件,我用include what you use

华为云开发者联盟

c++ 开发 C语言 技能

Numpy 的仿制 2

祖维

c slice Numpy

同事悄悄告诉我,飞书通知还能这样玩

Jianmu

自动化 建木CI 飞书通知 定时

能源行业的数字化“新”运维

博睿数据

AIOPS 智能运维 博睿数据 能源行业

【Unity UGUI】ScrollRect 动态缩放格子大小,自动定位到中间的格子

萧然🐳

游戏开发 Unity ScrollView 7月月更 UGUI

被忽视的问题:测试环境配置管理

老张

软件测试 测试环境治理

图像检索(image retrieval)

Geek_e369a5

图像搜索 图像检索

华为云ModelArts的使用教程(附详细图解)

逝缘~

华为 华为云 7月月更

一加10 Pro和iPhone 13怎么选?

Geek_8a195c

OPPO 小布预训练大模型揭秘:可大规模工业化应用的十亿级模型

OPPO小布助手

AI 智能助手 预训练模型 预训练

你可能不知道,我是如何将一个老系统的kafka消费者服务的性能提升近百倍的

Java全栈架构师

Java kafka 程序员 面试 架构设计

DeFi生态NFT流动性挖矿系统开发搭建

薇電13242772558

NFT DeFi流动性挖矿

2022年国内云管平台厂商哪家好?为什么?

行云管家

云计算 云管平台 云管平台厂商

uni-app与uviewUI实现仿小米商城app(附源码)

优秀的李

小程序 uniapp 7月月更 uviewui

输入的查询SQL语句,是如何执行的?

华为云开发者联盟

MySQL sql 开发 语句

NBA赛事直播超清画质背后:阿里云视频云「窄带高清2.0」技术深度解读

阿里云CloudImagine

音视频 直播 视频编码

Nebula Importer 数据导入实践

NebulaGraph

图数据库 数据导入 Nebula Graph

LeetCode-168. Excel表列名称(java)

bug菌

LeetCode 7月月更

LeaRun.Java快速开发平台 高效代码自动化生成

力软低代码开发平台

字节跳动Dev Better技术沙龙成功举办,携手华泰分享Web研发效能提升经验

字节跳动终端技术

字节跳动 前端

英特尔集成光电研究最新进展推动共封装光学和光互连技术进步

科技之家

有赞开源项目最佳实践_文化 & 方法_chen_InfoQ精选文章