Ant Design 开源项目经验分享,你想知道的都在这儿了-阿里云开发者社区

开发者社区> 温柔的养猫人> 正文

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

简介: 如何成功的运作一个开源项目?来自Ant Design灵魂人物偏右的全干货分享。
+关注继续查看

作者:偏右

image.png

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

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

image.png
image.png

项目文档

README

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

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

image.png

上手文档

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

关键点:手把手(Steps by Steps)

FAQ

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

关键点:保持更新!

Badges

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

image.png
image.png
image.png

可以使用 shieldsbadgen 这两个 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% 以上的英文文档是社区贡献的

image.png
image.png

文档演示和 playground

组件演示要友好,且可以实时反馈:

image.png

易于阅读和搜索

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

image.png

代码规范和风格

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

image.png
image.png

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

代码提交

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

  • husky + lint-staged
  • pretty-quick ⚡️

640.gif

commit 规范

git commit -a
<type>(<scope>): <subject>
// 空一行
<body>
// 空一行
<footer>

单元测试

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

image.png
image.png
image.png

Watch 模式

配合 fit,TDD 神器。

点击查看视频

Snapshot

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

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

image.png
image.png

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

Coverage

npm test -- --coverage

image.png
image.png

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

CI 服务

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

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

image.png
image.png
image.png
image.png
image.png
image.png

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

发布规范

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

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

image.png

Issue 和 PR 模板

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

image.png
image.png

合并分支

  • Creat a merge commit

    • 最安全普适,但是多一个合并 commit
  • Squash and Merge

    • 会丢失细节,不适合巨大的 PR,大的分支之间合并不能用这个
  • Rebase and Merge

    • 需要保证每个 commit 的质量

image.png

一些 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 语法。

image.png
image.png

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.面向用户写人话

image.png

大版本升级

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

bot🤖

  • ant-bot

    • 自动关闭不规范的 issue(用服务体验换服务效率,不是万不得已不推荐)
    • help wanted Need Reproduce Help wanted Usage
    • 随机分配处理人
    • 自动回复镜像站点
    • 发布时同步钉钉群
  • GitHub Actions

    • CI 测试用例
    • 发布新版本时自动部署网站
    • 同步 gitee
  • probot

image.png

收集反馈

image.png

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

image.png

贡献指南

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

开源项目运营

运营渠道

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

运营技巧

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

image.png

周边

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

开源是服务行业

服务的定义:

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 微信公众号回复 必读手册 立即获取下载链接。

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


版权声明:本文内容由阿里云实名注册用户自发贡献,版权归原作者所有,阿里云开发者社区不拥有其著作权,亦不承担相应法律责任。具体规则请查看《阿里云开发者社区用户服务协议》和《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容,填写侵权投诉表单进行举报,一经查实,本社区将立刻删除涉嫌侵权内容。

相关文章
一不小心,它成为了 GitHub Alibaba Group 下 Star 最多的开源项目
随着微服务的流行,应用更加轻量和高效,但是带来的困境是线上问题排查越来越复杂困难。传统的 Java 排查问题,需要重启应用再进行调试,但是重启应用之后现场会丢失,问题难以复现。
847 0
持续集成之道:在你的开源项目中使用Travis CI
自从接触并践行了敏捷的一些实践之后,便深深的喜欢上了敏捷。尤其是测试自动化和持续集成这两个实践,可以显著的提高软件的质量和集成效率,实时检测项目健康度,使团队成员对项目保持充足的信心。 但是对于个人项目而言,虽然测试自动化好实现,但是要实现持续集成还是稍有难度。
1417 0
【前台】【单页跳转】整个项目实现单页面跳转,抛弃iframe
即如下: 【想做到点击nav侧边栏,仅替换右边div中的内容,而不是跳转到新的页面,这样的话,其实整个项目中就只有一个完整的页面,其他的页面均只写内的部分即可,或者仅仅写要替换的内的部分即可!!】 index.
1164 0
android git上开源的项目收藏
<p style="font-size:14px; margin-top:0px; margin-bottom:0px; padding-top:0px; padding-bottom:0px; border:0px; outline:0px; vertical-align:baseline; orphans:4; color:rgb(68,68,68); font-family:'Tim
1949 0
2014年值得关注的10个开源项目(上)
2014年值得关注的10个开源项目(上) 一、Appium 官网:http://appium.io/ Appium是一个开源的自动化测试框架,它主要用于原生移动应用或混合移动应用。
857 0
91%的商业App包含过时或废弃开源组件
Synopsys 公司发布了 2020 年开源安全和风险分析(OSSRA)报告,该报告由 Synopsys 网络安全研究中心(CyRC)制作,研究了由黑鸭审计服务团队进行的 1,250 多次商业代码库审计的结果。
603 0
1172
文章
2
问答
来源圈子
更多
+ 订阅
文章排行榜
最热
最新
相关电子书
更多
《2021云上架构与运维峰会演讲合集》
立即下载
《零基础CSS入门教程》
立即下载
《零基础HTML入门教程》
立即下载