APlus-UI

APlus-UI 项目工作流 ​

APlus-UI项目是一个内部使用且多人协作的一个项目，其以工作流主要为服务多人协作下的组件开发，主要流程如下：

  1. 拉取此项目源码，完成依赖安装
  2. 启动文档网站（可用于开发调试&文档）
  3. 完成开发
  4. release&发布文档
  5. 飞书消息通知

开发前准备 ​

INFO

此项目是一个使用pnpm workspace组织的单仓多包仓库，在开发前请仔细阅读pnpm Workspace。

基于此项目是团队内部项目且各个板块较为独立，此项目并不采用一般开源项目的开发流程，从而减少沟通成本，提升效率，基于此，每位成员都可以在主分支上完成开发、release等。

拉取项目，完成依赖安装，就可以进入开发了。

提示

如果有新的内容，APlus-UI会在每个工作日的18:00发布版本，请务必在此之前完成组件开发、文档编写、测试用例编写等。

使用文档网站 ​

此项目原本有一个空的vue项目用作开发调试，但是在使用过程中容器产生代码冲突，开发者也容易忽视对于此项目的更新维护，最重要的是其一部分调试功能在编写文档示例的同时就可以完成。因此，在某个版本，我们删除了这个专门用于调试的项目，你必须使用文档网站为你的组件编写文档&调试。

文档网站site使用vitepress创建，所有子包的文档都可以在site/docs/下的同名目录中找到，而菜单配置则位于site/docs/.vitepress/config.js。

找到对应的包目录，为组件创建一个目录，一般情况下，此目录包含index.md入口以及demo用于存放示例的文件夹。

编写示例代码，并在.md文件中使用全局组件demo引入，例如<demo vue="./demo/xx.vue" title="xx" description="xx" />，然后你就可以看到一个展示示例和预览代码的区块了。

此demo组件使用vitepress插件vitepress-demo-plugin。

提交代码 ​

在下一步release的时候会详细说明使用release-it来做版本管理和发布，为配合发布流程正常工作，我们对提交代码做了一些限制，

  • 仅使用pnpm commit并根据交换式命令行完成代码提交
  • 一次提交只包含一种变更类型
  • 选择正确的变更类型，变更类型说明如下：
test -- 添加/修改测试用例
feat -- 新特性
fix -- 修复bug
chore -- 修改了构建流程以及辅助开发工具等变更，这些变更并不影响最终的
构建产物（例如修改了package.json添加了一个脚本）
docs -- 新增/修改对应的文档
refactor -- 代码重构
style -- 格式类型改动（比如使用了新的prettier配置格式化了代码、单引号改双引号等）
ci -- 持续集成配置（或者代码）相关的变动
pref -- 提升代码性能
  • 选择正确的变更范围，变更范围说明如下：
ci -- 持续集成的配置，对应根项目根目录的一下配置、scripts目录等
site -- 文档网站，对应目录为site
aplus-ui -- 组件库，对应目录packages/aplus-ui
charts -- 图表库，对应目录packages/charts
hooks -- 可组合函数库，对应目录packages/hooks
utils -- 工具集，对应目录packages/charts
other -- 其它，不知道选什么范围的时候使用
theme -- APlus-UI的样式目录packages/theme
plugin -- 按需加载插件，对应目录packages/unplugin-aplus-ui
  • 输入简洁易读的提交描述

上述步骤完成后，对于特定的文件会执行不同的格式化修复，配置如下：

json
{
  "lint-staged": {
    "*.{js,jsx,vue,ts,tsx}": [
      "eslint --fix",
      "prettier --write"
    ],
    "*.less": [
      "stylelint --fix"
    ]
  }
}

同时，如果检测到aplus-ui目录有变动，还会对aplus-ui做完整的ts校验。

发布 ​

此项目的所有包都使用release-it管理发布但版本还需要手动提升（因为使用release-it管理版本会导致版本提升过快的问题），包版本管理遵循Semantic Versioning，在实际过程中，需要我们判断需要提升的是hotfix版本、次要版本还是主要版本。

判断为主要版本的特殊处理方式

如果某一个变更是不兼容的，正常情况下你应该提升主版本，但此项目处于高速的迭代中，不兼容的变更很常见，如果直接提升主版本的话，版本提升就会非常的快，可能会导致后续版本维护困难，因此需要控制主版本的提升节奏。

具体的做法是，如果某一个变更是不兼容的，你需要将代码提交到next分支中，next分支将会视情况灵活发布。

在根目录执行pnpm release:包:提升版本类型，比如我们在工具集中添加了一个新的函数，此时需要运行pnpm release:utils:minor，表示发布一个工具集的次要版本。

运行这个命令后，会进入到交互式命令行中，此时只需要依次选择确定即可完成版本的发布。

在发布流程中还有一个很重要的步骤，那就是生成变更日志(changelog)，生成的变更日志将会使用到文档包更新日志以及推送到飞书群组里，因此第三步提交代码需要谨慎，不符合规范的提交生成的更新日志将影响每一个使用者。

在单仓多包的应用中，我们使用提交时选择的范围来筛选提交记录，例如aplus-ui生成的changelog只包含提交时选择了范围为aplus-ui的提交记录。

遵循代码提交规范一般情况下生成的变更记录都是可用的，特殊情况下我们也可以通过编辑生成的提交记录来修正它，这也是为什么发布文档和飞书消息通知并没有集成到包发布流程中的原因。提交记录在site/docs/guide/CHANGELOG.xx.md中，你可以编辑这些变更记录然后再发布文档&推送飞书消息通知。但请注意⚠️，应当尽可能避免使用此种方式，会在未来移除。

发布文档 ​

在一切准备工作做完后，发布文档只需要在根目录运行pnpm docs:deploy，就这么简单！

文档使用云效流水线完成构建和发布，因为我们本地也就是调用云效提供的API来执行流水线，是否发布成功需要在云效devopsaplus-ui主页查看。

调用API需要用到个人访问令牌，请按照官方文档获取个人访问令牌。

获取到令牌后，在site目录下新建.env文件，并添加以下内容YUNXIAO_TOKEN="your_own_token"。

完成后执行pnpm docs:deploy即可。

飞书消息推送 ​

当某个包发布完成后，我们需要通知到飞书相应的群组以让各个项目自行决定是否运用上这些更新，其会解析changelog最新一个版本作为内容，脚本实现见scripts/send-changelog.ts。

飞书消息推送只需要在根目录执行pnpm send:changelog -t=your_package，-t参数支持的值如下：

UI -- 组件库
charts -- 图标库
hooks -- 可组合函数(hooks)库
utils -- 工具集

请注意⚠️，多次运行发送变更日志的脚本会发送推送多次消息，即使包没有更新。

提示

如果是首次提交代码，飞书消息推送可能无法@到贡献者，请获取你的飞书用户id并填写到脚本中，下一次就可以正常@了。

以上就是APlus-UI项目的工作流程的简单介绍，参与贡献时请确保已经熟知此流程。任何疑问欢迎探讨！

Copyright© 2024-2025 APlus-FE Team.