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

avatar
阿里巴巴 前端委员会智能化小组 @阿里巴巴
原文链接： mp.weixin.qq.com

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

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

项目文档

README

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

  • 一句话描述：解决什么问题？

  • Badges：这个项目靠不靠谱？

  • 特性：有什么？有什么不一样？

  • 使用方式：看一眼是什么

  • 必要截图：看一眼是什么

  • 开发指引：如何本地开发？

  • 参考项目：

    • standard-readme（https://github.com/RichardLitt/standard-readme）

    • ice（https://github.com/alibaba/ice/）

    • f2（https://github.com/antvis/f2/）

上手文档

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

  • README

  • 快速上手：手把手的文档，让用户有第一印象（https://ant.design/docs/react/getting-started-cn ）

  • 在 create-react-app 中使用 ：和社区对齐（https://ant.design/docs/react/use-with-create-react-app-cn ）

  • 在 TypeScript 中使用 ：和社区对齐（https://ant.design/docs/react/use-in-typescript-cn ）

  • 项目实战：面向高级用户，推广 Umi（https://ant.design/docs/react/practical-projects-cn ）

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

FAQ

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

  • FAQ 文档（https://ant.design/docs/react/faq-cn）

  • 组件文档的 FAQ 部分（https://ant.design/components/form-cn/#FAQ）

  • Issue 标签（https://github.com/ant-design/ant-design/issues?q=is:issue+label:❓FAQ+is:closed ）

关键点：保持更新！

Badges

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

  • CI 服务 

  • 覆盖率

  • npm

  • npm download

  • 依赖版本（https://david-dm.org/ant-design/ant-design）

  • Gitter

  • 协议安全（https://fossa.com/）

可以使用 shields（ https://shields.io/ ）、badgen（https://badgen.net/ ） 这两个 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（https://github.com/benjycui/bisheng） 搭建，基于 React SSR 的 static site generator：

  • 静态化

  • 部署方案：一开始使用 gh-pages，为了国内访问速度切换到 netlify 上，后来由于无力承担 netlify 费用再次回到 gh-pages，并配合使用 cloudflare dns 提速服务

  • 中文镜像：使用 gitee 提供的免费 pages 服务（https://ant-design.gitee.io/index-cn  ）

国际化

  • 文档、注释、反馈、git message、issue 适当考虑国外用户

  • 网址中英文独立地址方便 SEO

  • 社区招募和引导 ，Ant Design 70% 以上的英文文档是社区贡献的（ https://github.com/ant-design/ant-design/issues/1471）

文档演示和 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 编写指南（https://www.ruanyifeng.com/blog/2016/01/commit_message_change_log.html ）

  • commitlint（https://github.com/conventional-changelog/commitlint#readme ） 自动检查，G2Plot 的例子参考（https://github.com/antvis/G2Plot/blob/da9a941b2921766b2f45e908d40e6ff73bc8d1db/package.json#L57 ）

单元测试

目前比较主流的两个单元测试框架：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

  1. 整体覆盖率不达标，CI 会挂

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

CI 服务

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

  • netlify 网站预览服务

  • surge 网站预览服务

  • bundlesize 文件体积

  • WIP PR 正在进行中

  • Circle CI 测试用例

  • Codecov 测试覆盖率

  • codesandbox ci 演示调试预览

更多参考：Ant Design 4.0 的一些杂事儿 - CI 篇（https://zhuanlan.zhihu.com/p/113537427 ）

发布规范

Ant Design 轮值规则和版本发布流程（https://github.com/ant-design/ant-design/wiki/轮值规则和版本发布流程 ），其核心主要有：

  • 每周发布  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 参考这里（https://github.com/ant-design/ant-design/wiki/轮值规则和版本发布流程#emoji-for-changelog ）。

  • push release 分支并发起 CHANGELOG 的 PR 请其他同学 review。

  • PR 的主楼内容里直接复制上 CHANGELOG 的改动内容，好处是版本 CHANGELOG 的 PR 会关联在各个 issue 中，很容易知道 issue 在哪个版本被改了（https://github.com/ant-design/ant-design/pull/15018 ）。

  • changelog PR 可以参考（ https://github.com/ant-design/ant-design/pull/12615 ）。

这其中有两个要点：

1.描述用户第一现场的问题，而非你的解决方式

  • ❌ 修复组件 Typography 的 dom 结构问题。

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

--------------

  • ❌ 修复 lib  下样式文件路径问题。

  • ✅ 修复部分组件样式丢失的问题。

2.面向用户写人话

大版本升级

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

  • 升级手册（https://ant.design/docs/react/migration-v4-cn ）

  • 旧版本文档

  • 控制台废弃提示

  • 升级工具

    • migration-helper(https://github.com/ant-design/antd-migration-helper )

    • codemod(https://github.com/ant-design/antd-codemod )

    • 兼容包(https://github.com/ant-design/antd-adapter )

bot🤖

  • ant-bot

    • 自动关闭不规范的 issue（用服务体验换服务效率，不是万不得已不推荐）

    • help wanted  Need Reproduce Help wanted  Usage

    • 随机分配处理人

    • 自动回复镜像站点

    • 发布时同步钉钉群

  • GitHub Actions

    • CI 测试用例

    • 发布新版本时自动部署网站

    • 同步 gitee

  • probot（https://probot.github.io/apps/ ）

收集反馈

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

贡献指南

  • 本地调试 降低贡献难度

  • 提交 PR 的指南 如何修复 CI

  • 吸引社区协作者 Collaborators，目前官方团队中的外部协作者已经有 12 位，已经是维护的中坚力量 ( https://github.com/ant-design/ant-design/wiki/Collaborators#how-to-apply-for-being-a-collaborator )

  • 捐助渠道（https://opencollective.com/ant-design） 可以根据收入购买一些好用的开源付费服务用于项目

开源项目运营

运营渠道

  • 知乎 🔥 国内最专业，有社交转播能力

  • 掘金 & 开源中国 🔥 入门级用户比较多

  • Hacknews 🔥 科技界 top 榜单

  • Reddit：🔥 美国贴吧，技术风向标

  • Dev.to  🔥 国外版掘金

运营技巧

  • 做好 SEO（搜索引擎的流量不用钱，细水长流）

  • 各类推广文章（适当保持曝光度）

  • Awesome List （哪里有要有你）

  • 蹭竞品（有竞品是很幸福的一件事）

周边

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

  • 脚手架

    • create-react-app-antd(https://github.com/ant-design/create-react-app-antd )

    • Next.js(https://github.com/zeit/next.js/tree/master/examples/with-ant-design )

    • react-boilerplate(https://github.com/ant-design/react-boilerplate)

    • react-starter-kit(https://github.com/ant-design/react-starter-kit )

    • parcel-antd(https://github.com/ant-design/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 前端开源领域技术展望

  福利来了 

重磅下载！

《2020 前端工程师必读手册》

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

关注「Alibaba F2E」

把握阿里巴巴前端新动向

avatar
文章
阅读
粉丝