Ant Design 开源项目经验分享，你想知道的都在这儿了

2022-04-14 21:57:18

作者：偏右

Ant Design 在 2015 年 5 月 7 日第一次提交代码，全部提交和讨论都在 GitHub 进行，无内网版本，是一个完全开源的前端项目。

本文基于 Ant Design 多年来的项目运作，与大家交流开源项目的运作经验，主要内容围绕项目文档、网站、代码规范和风格、单元测试、发布规范、开源项目运营等几大方面，为大家提供实用的指引。

项目文档

README

项目的 README 应该包含对项目的核心描述，内容应包括：

一句话描述：解决什么问题？
Badges：这个项目靠不靠谱？
特性：有什么？有什么不一样？
使用方式：看一眼是什么
必要截图：看一眼是什么
开发指引：如何本地开发？
参考项目：
- standard-readme
- ice
- f2

上手文档

为了给程序员提供愉快的开发体验，手把手（Steps by Steps）的快速上手使用文档非常重要。

README
快速上手：手把手的文档，让用户有第一印象
在 create-react-app 中使用：和社区对齐
在 TypeScript 中使用：和社区对齐
项目实战：面向高级用户，推广 Umi

关键点：手把手（Steps by Steps）

FAQ

为一些常见的问题整理官方回复，可以省去很多答疑成本。内容可以包括：

关键点：保持更新！

Badges

使用 Badges 可以通过一些核心的指标去了解项目的概况。参考：

CI 服务
覆盖率
npm
npm download
依赖版本
Gitter
协议安全

可以使用 shields、badgen 这两个 Badges 服务去装饰你精心写的项目。

网站

网站体验是用户的第一次体验，也可能是最后一次。

一个基本网站应该具备的特性：

⚛ Prerendered static site
???? Internationalization
???? Markdown-based documentation
???? Examples with live playground
???? Pretty Theme and Layout
???? Mobile friendly
???? API docs of easy to read and search

静态网站构建

网站可以使用 bisheng搭建，基于 React SSR 的 static site generator：

静态化
部署方案：一开始使用 gh-pages，为了国内访问速度切换到 netlify 上，后来由于无力承担 netlify 费用再次回到 gh-pages，并配合使用 cloudflare dns 提速服务
中文镜像：使用 gitee 提供的免费 pages 服务

国际化

文档、注释、反馈、git message、issue 适当考虑国外用户
网址中英文独立地址方便 SEO
社区招募和引导，Ant Design 70% 以上的英文文档是社区贡献的

文档演示和 playground

组件演示要友好，且可以实时反馈：

易于阅读和搜索

可以使用 algolia 实现网站的搜索功能：

代码规范和风格

代码规范非常重要，但是不要在这上面花太多时间，靠工具 ????

eslint-config-airbnb
tslint => @typescript-eslint/parser
Prettier

代码提交

借助如下两个工具，让代码提交快速且规范：

husky + lint-staged
pretty-quick ⚡️

commit 规范

git commit -a

<type>(<scope>): <subject>
// 空一行
<body>
// 空一行
<footer>

Commit message 和 Change log 编写指南
commitlint 自动检查，G2Plot 的例子参考

单元测试

目前比较主流的两个单元测试框架：JEST、enzyme。Ant Design 主要使用 JEST ：

Watch 模式

配合 fit，TDD 神器。

点击查看视频

Snapshot

底层依赖变动如何感知？结构细节变化如何感知？写用例细节多麻烦？可以借助 snapshot 来解决:

const wrapper = mount(<Breadcrumb />);
expect(wrapper).toMatchSnapshot();

npm test -- -u // 更新 snapshot 并提交

Coverage

npm test -- --coverage

整体覆盖率不达标，CI 会挂
改动的这部分代码的覆盖率没有达到整体覆盖率，CI 会挂

CI 服务

CI 可以帮助我们知晓一个 PR 的状态如何，是否这个 PR 合进来会引入其他的问题。而对于 PR 的贡献者，也可以通过这个长长的列表知晓自己有什么地方做错了需要改进。推荐的 CI 服务有：

netlify 网站预览服务
surge 网站预览服务
bundlesize 文件体积
WIP PR 正在进行中
Circle CI 测试用例
Codecov 测试覆盖率
codesandbox ci 演示调试预览

更多参考：Ant Design 4.0 的一些杂事儿 - CI 篇

发布规范

Ant Design 轮值规则和版本发布流程，其核心主要有：

每周发布 patch 版本
每月发布 minor 版本
由轮值同学进行发布操作，依靠这个机制，Ant Design 近五年来每周都发版本，风雨无阻

Issue 和 PR 模板

前置校验，帮助用户更高效地反馈问题，降低解决问题的成本。

合并分支

Creat a merge commit
- 最安全普适，但是多一个合并 commit
Squash and Merge
- 会丢失细节，不适合巨大的 PR，大的分支之间合并不能用这个
Rebase and Merge
- 需要保证每个 commit 的质量

一些 Git & GitHub 技巧

获取源码地址时，务必按 y 键来固定源码地址（切莫刻舟求剑）。
始终用 git commit message 里的 close #123 fix #23456 等字符来关闭 issue，可以在对应 issue 里留下有效痕迹。
禁止用 git commit -m，使用 git commit -a。（可以在 body 里补充更多信息）。
git pull --rebase（不加 --rebase 的区别是？）和 git cherry-pick。
markdown diff 语法。

const a = () => {
- const a = 1;
+ const a = '1';
}

Changelog

关于 Changelog 的一些核心原则：

如果是发布 minor 版本，先新建一个 pr 将 feature 分支合并到 master，所有发布操作需要在 master 分支上进行。注意！不要使用 squash merge！防止提交信息丢失！
从 master 新建一个 release 分支用来做发布的修改（例如：git checkout -b release-3.6.0）。
在 CHANGELOG.en-US.md 和 CHANGELOG.zh-CN.md 和里添加发布日志，可以用 compare 功能找到当前和之前版本的区别，将有价值的改动如实反馈给用户。
对用户使用上无感知的改动建议（文档修补、微小的样式优化、代码风格重构等等）不要提及，保持 CHANGELOG 的内容有效性。
用面向开发者的角度和叙述方式撰写 CHANGELOG，不描述修复细节，描述问题和对开发者的影响。格式可以参考以往的 changelog。
新增属性时，建议用易于理解的语言描述用户可以感知的变化。（例如，新增 onCellClick 属性，可以定义单元格点击事件）
尽量给出原始的 PR 链接，社区提交的 PR 改动加上提交者的链接。
底层模块升级中间版本要去 rc-component 里找到改动，给出变动说明。
如果不确定改动的真实目的，可以向提交者进行咨询。
参考之前版本的日志写法，添加必要的截图帮助说清楚新功能。
每一个改动前加一个 emoji 增加文档的可读性和生动性，可选的 emoji 参考这里
push release 分支并发起 CHANGELOG 的 PR 请其他同学 review。
PR 的主楼内容里直接复制上 CHANGELOG 的改动内容，好处是版本 CHANGELOG 的 PR 会关联在各个 issue 中，很容易知道 issue 在哪个版本被改了。
changelog PR 可以参考。

这其中有两个要点：
1.描述用户第一现场的问题，而非你的解决方式

❌ 修复组件 Typography 的 dom 结构问题。
✅ 重构并简化了 List Item 的 dom 结构，并且修复了 Item 中内容空格丢失的问题。

❌ 修复 lib 下样式文件路径问题。
✅ 修复部分组件样式丢失的问题。

2.面向用户写人话

大版本升级

目标是帮助用户无脑升级。

升级手册
旧版本文档
控制台废弃提示
升级工具

bot????

ant-bot
- 自动关闭不规范的 issue（用服务体验换服务效率，不是万不得已不推荐）
- help wanted Need Reproduce Help wanted Usage
- 随机分配处理人
- 自动回复镜像站点
- 发布时同步钉钉群
GitHub Actions
- CI 测试用例
- 发布新版本时自动部署网站
- 同步 gitee
probot

收集反馈

Hotjar 提供了问卷调查，反馈渠道，热区统计等实用的功能，免费版基本能满足需求了。

贡献指南

本地调试降低贡献难度
提交 PR 的指南如何修复 CI
吸引社区协作者 Collaborators，目前官方团队中的外部协作者已经有 12 位，已经是维护的中坚力量
捐助渠道可以根据收入购买一些好用的开源付费服务用于项目

开源项目运营

运营渠道

知乎 ???? 国内最专业，有社交转播能力
掘金 & 开源中国 ???? 入门级用户比较多
Hacknews ???? 科技界 top 榜单
Reddit：???? 美国贴吧，技术风向标
Dev.to ???? 国外版掘金

运营技巧

做好 SEO（搜索引擎的流量不用钱，细水长流）
各类推广文章（适当保持曝光度）
Awesome List（哪里有要有你）
蹭竞品（有竞品是很幸福的一件事）

周边

你的用户在哪，你就到哪。

脚手架
create-react-app-antd
Next.js
react-boilerplate
react-starter-kit
parcel-antd
主题/色彩/图标
Sketch & Axure
其他技术栈（angular/vue）
非主流构建工具

开源是服务行业

服务的定义：

A service is something that the public needs.....which is provided in a planned and organized way

服务行业的企业文化，通俗地说，就是以服务为导向、包括服务标准、服务理念、服务宗旨和服务效果等方面。『百度百科』

不是回答用户问题了就是服务，要有 planned and organized 的服务机制。

总结

拥抱社区，保持互动
- 客户第一，用口碑提升团队影响力
- 紧跟技术潮流
- 透明开放的流程
充分利用开源社区的各种服务和工具
- 提高代码和工程质量
- 降低维护的成本
Single Source of Truth
- 内外网一视同仁
- GitHub 比 LinkE 体验好太多
业务为王（这是最重要的一条，上面都可以忘记，这条不能忘）
- 俗话说：业务脱节死得快
- 开源项目死掉不是因为开源没做好，而是因为内部不再依赖这个开源版本了
- 用开源的软件交付流程来服务内部业务

福利来了！
重磅下载！《2020 前端工程师必读手册》

阿里巴巴前端委员会推荐！覆盖语言框架、前端智能化、微前端、Serverless及工程化 5 大热点前端技术方向、10+ 核心实战的前端手册，解锁前端新方式，挖掘前端新思路，尽在此刻，赶紧来先睹为快！关注 alibabaf2e 微信公众号回复必读手册立即获取下载链接。

关注「Alibaba F2E」
把握阿里巴巴前端新动向

码农公寓