OKKI UI 组件开发流程与规范

前言

OKKI UI 组件库设计之初是因为公司对于目前使用的 UI 组件库（amumu）设计风格不是很满意，希望能有一个更有质感并且视觉效果更加强烈的设计风格，并且前端团队有升级 Vue3 的计划。但是由于公司并没有能力设计出这样一个「Design System」，我们需要从市面上主流 UI 框架中挑选出符合 CRM 业务场景的组件库。

技术栈

UI 组件库

• JS 框架：Vue3
• UI 框架：Ant Design Vue 2.2.8
• JS 类型：TypeScript
• CSS 预处理：Less
• 打包构建：Vite
• 代码质量：ESLint + Prettier

组件文档

• JS 框架：Vue3
• UI 框架：Ant Design Vue 2.2.8 （后面会统一改为 OKKI UI）
• JS 类型：TypeScript
• CSS 预处理：Less
• 打包构建：Vite
• 代码质量：ESLint + Prettier

目录结构

.
├── build                       # 版本发布相关代码
├── components                  # 原Ant Design Vue 组件目录（后续会移除）
├── packages                    # 组件库核心代码
│   ├── components              # 组件目录
│   ├── hooks                   # 通用 hooks
│   ├── types           # 通用 types/interface
│   └── utils           # 通用工具类函数/方法
├── plugin              # 组件文档依赖的插件，例如：markdown转换
│   ├── docs
│   ├── md
│   └── shared.ts
├── scripts             # 脚本工具
├── site                # 组件库的文档站点
└── tests               # 组件测试
    └── unit            # 单元测试

开发规范

组件规范

目录结构

/packages/components/XXX
├── demo                # 文档中的示例代码
│   ├── aaaa.vue
│   ├── index.vue       # demo 的入口文件
│   ├── xxxx.vue
│   └── yyyy.vue
├── src                 # 当前组件的源码目录
│   ├── components      # 子组件目录
│   └── index.vue       # 组件源码入口文件
├── index.json          # 组件信息（自动生成）
├── index.ts            # 组件入口文件，包含全局注册组件
└── index.zh-CN.md      # 组件 API 文档

开发流程

• 从远处主仓库拉取功能开发分支（例如：feautre/Guide-20211105）

• 通过自动化创建新组件目录，执行命令：yarn new-okki-component

  $ yarn new-okki-component
  yarn run v1.17.3
  $ plop
  ? 请输入组件名？ Guide
  ? 请输入组件中文名称？ 步骤引导
  ? 请选择组件类型？ 导航
  ? 是否需要样式目录？(y/n) y
  ✔  ++ /packages/components/Guide/src/index.vue
  ✔  ++ /packages/components/Guide/index.ts
  ✔  ++ /packages/components/Guide/demo/index.vue
  ✔  ++ /packages/components/Guide/index.zh-CN.md
  ✔  ++ /packages/components/Guide/style/index.less
  ✨  Done in 28.20s.
  

• 执行命令 yarn dev，在本地实时预览组件开发效果

• 开发完成后按 Git 规范 提交代码，提 PR 到 dev 分支

单元测试

🚧 梳理中……

Git 规范

分支说明

分支命名

• feature 分支：feature/Guide-20211105
• Hotfix 分支：hotfix/Guide-20211111

• master 主分支，用于线上版本打包
• hotfix 热修复分支，用于修复线上版本的紧急 BUG
• dev 主开发分支，用于测试版本，包含确定即将发布的代码（严格意义上，回归测试应在 UAT 分支进行）
• feature 新功能分支，用于开发某一个新功能

提交规范

• 做到小幅度修改，多次数提交，但应保证提交的完整性。

• 必须使用公司邮箱提交代码

  EMAIL=$(git config user.email)
  if [[ ! $EMAIL =~ ^[.[:alnum:]][email protected]$ ]];
  then
    echo "Your git information is not valid";
    echo "Please run:"
    echo '   git config --local user.name "<Your name in OKKI>"'
    echo '   git config --local user.email "<Your alias>@xiaoman.cn"'
    exit 1;
  fi;

• 按规范提交信息

  ;[
    'feat', // 新功能
    'fix', // 打补丁
    'perf', // 性能优化
    'style', // 不影响程序逻辑的代码修改(修改空白字符，补全缺失的分号等)
    'docs', // 文档
    'test', // 增加测试
    'refactor', // 重构
    'build', // 构建优化
    'ci', // gitlab CI 配置
    'chore', // 构建过程或辅助工具的变动
    'revert', // 回滚代码
    'wip', // 正在进行中
    'workflow', // 工作流程
    'types', // 类型声明
    'release', // 版本发布
  ]

Issue 规范

提交规范

• Issue 列表以可读和可检索为目标。提交者有义务将标题总结的有意义和易于检索，并保持内容的正确和完整性；
• 请在经过充分的检索之后，确定无相关的已存在 Issue，再提交新的 Issue；
• Issue 类型划分为缺陷报告、新功能请求和问题，请在提交 Issue 时选择正确的模板并根据模板填写其内容；
• 由配置不确定等产生的问题，请将相关的可重现代码提交至 Github，以便于社区贡献者定位和确定问题；
• 请在 Issue 得到解决之后，回复该 Issue，形成闭环，为其他浏览此 Issue 的读者提供有效信息；
• 请及时关注已提交的 Issue，长时间无反馈的 Issue 将定期关闭；
• 为保证“问题”能得到解决，请提交者提供 最小、独立且可运行 的 demo，

处理规范

• 对于标题不明晰的 Issue，由管理员引导提交者将标题修改完善后再行处理；
• 对于内容缺失模板必要信息的 Issue，由管理员引导提交者将所需信息提供完善后再行处理；
• 涉及到缺陷修复、功能提升等与代码相关的 Issue，都将标记正确的标签以及完成此 Issue 的项目版本；
• 管理员将定期关闭长时间无反馈的 Issue；
• 无参考和检索价值的 Issue 将被标记为 status:invalid，读者无需关注。