JS-SDK 文档以及库

• 项目地址: [email protected]:10022/suplink-frontend/js-sdk.git
• 项目参与者: @huangxinxiao

项目说明

包含封装 JS-SDK 以及文档

prepare: 组件库前期开发准备工作。eslint/commit lint/typescript 等等； dev: 使用 docz 进行开发调试以及文档编写 https://www.docz.site/docs/component-shadowing； build: umd/cjs/esm、types、polyfill 以及按需加载；

项目结构说明

├── doc-comps    // 文档使用的组件
├── .docz // 本地开发编译缓存
├── src
    ├── components // js-sdk库源码
        ├── API  // API方法
        ├── components // 组件
        ├── config //  版本信息
        ├── events // 自定义事件
        ├── start // 开始
        ├── utils
        ├── bridge.ts // js-bridge
        ├── build.js // webpack 打包入口
        ├── index.js
    ├── gatsby-theme-docz  //  文档渲染内容
        ├──components  // 重写的一些文档渲染内容
├── doczrc.js
├── gatsby-node.js // 自定义docz webpack config
├── gatsby-config // gatsby 一些主题插件设置
├── gulpfile.js  // gulpfile 打包
├── webpack.config.js // 打包jssdk为一个js文件

项目环境

• node.js > v10

项目脚本 - npm scripts

    - npm run build:lib  //  打包封装的sdk库
    - npm start // 本地起文档服务
    - npm build // 打包整个文档

开发模式

• 本地服务端口: 3000

npm run start

- 组件开发原则, 结构
├── suplink
    ├── menu
        ├── group
            ├── name
                ├── index.mdx //文档
                ├── interface.ts // type 文件
                ├── index.ts(tsx) // 源代码文件
                ├── demo //  示例用法
    ...

文档编写,类似这种

---
name: EventChannel
route: /events/EventChannel
menu: Events
group: EventChannel
method: EventChannel
---

import { Box, Table } from "doc-comps/index";
import BasicDemoCode from "!raw-loader!./demo/basic.tsx";
import BasicDemo from "./demo/basic.tsx";

#### 方法

#### EventChannel.emit(string eventName, any args)

<span style={{ fontSize: 14 }}>触发一个事件</span>

#### EventChannel.on(string eventName, EventCallback fn)

<span style={{ fontSize: 14 }}>持续监听一个事件</span>

#### EventChannel.once(string eventName, EventCallback fn)

<span style={{ fontSize: 14 }}>监听一个事件一次，触发后失效</span>

#### EventChannel.off(string eventName, EventCallback fn)

<span style={{ fontSize: 14 }}>取消监听一个事件。给出第二个参数时，只取消给出的监听函数，否则取消所有监听函数</span>

###### 代码演示

<Box code={BasicDemoCode} title="基本用法" desc="页面间事件通信通道">
  <BasicDemo />
</Box>

生产模式

• 导出文件地址: dist/

npm run build

Git 工作流

不论是Feature-新功能还是Bugfix-问题修复，建议每天提交一次版本，尽可能的避免一次性提交大量文件

Feature-新功能

feature-x为自定义的分支名称，可自行替换

1. 基于origin/develop新建功能分支feature-x；

git checkout -b feature-x origin/develop

2. 开发完成后，通过git rebase同步origin/develop在此时间段内的变动，防止 merge request 时有冲突；

# 同步`origin/develop`在此时间段内的变动
git rebase origin/develop
# 解决冲突后push到origin
git push --set-upstream origin feature-x

3. 在 Gitlab 上发起 Merge Requests 后进行 Code Review，通过后由管理员合并入origin/develop分支；

Bugfix-问题修复

bugfix-x为自定义的分支名称，可自行替换

1. 基于 tag 新建分支bugfix-x；

git checkout -b bugfix-x v1.0.0

2. 问题修复后，提交至 origin；

# push到origin
git push --set-upstream origin bugfix-x

3. 由管理员进行 Code Review，通过后合并入origin/master，同时增加新的 tag 号v1.0.1-alpha，并提交至测试组进行预发测试；

# 管理员切换master，通过git merge合并代码
git checkout master
# 合并bugfix-x，使用squash模式可以将commit压缩
git merge --squash origin/bugfix-x
# 重新提交commit的信息
git add .
git commit -m "fix: 修复了XXX的问题"
# 增加预发测试的tag
git tag -a v1.0.1-alpha -m "修复问题的简易描述"
# 提交至origin
git push origin v1.0.1-alpha

4. 测试通过后去除 tag 的延伸段，例如-alpha，重新提交；

# 基于原有tag创建新的tag
git tag v1.0.1 v1.0.1-alpha
# 删除本地的原有tag
git tag -d v1.0.1-alpha
# 删除origin的原有tag
git push origin :refs/tags/v1.0.1-alpha
# 推送新的tag至origin
git push origin v1.0.1

5. 使用git cherry-pick合并代码入origin/develop；

# 获取v0.9.1的log，取最新的<commit id>，即合并至master的那份
git log v1.0.1
# 切换至develop分支
git checkout develop
# 通过cherry-pick将修改的内容合并至develop
git cherry-pick <commit id>
# 推送至origin
git push

Tag-新功能/问题修复发布

版本格式为：主版本号.次版本号.修订号，版本号递增需要遵守一下规则：

• 主版本号：重构、大调整；
• 次版本号：功能性新增；
• 修订号：问题修正；

先行版本号及版本编译信息可以加到“主版本号.次版本号.修订号”的后面，作为延伸，例如v1.01.06为线上版本，v1.00.06-alpha为预发版本，v1.00.06-beta为测试版本；

在beta和alpha测试通过后，由develop分支 merge 入 master，同时根据 semver 的规范升级次版本号，更新对应的 tag；