From 40bda38fe5ebaaf2a53e6961cf02037aed378204 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?w=C5=AB=20y=C4=81ng?= Date: Mon, 4 Dec 2023 15:08:23 +0800 Subject: [PATCH] chore: update CONTRIBUTING.md --- CONTRIBUTING.md | 131 +++++++++++++++++++++++++----------------------- 1 file changed, 68 insertions(+), 63 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8a30f5a2c2..85f4764cae 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,26 +1,32 @@ # CONTRIBUTING -`tdesign-react` 包含 `react` 代码和一个子仓库，子仓库指向 `tdesign-common`仓库 +`tdesign-react` 包含 `react` 代码和一个子仓库，子仓库指向 `tdesign-common` 仓库 ## 开发 -建议使用 `node 18` 版本进行开发 +建议使用 node 18 版本进行开发 -### 安装依赖 +### 1.初始化子仓库 + +```bash +git submodule init && git submodule update +``` + +### 2.安装依赖 ```bash npm i ``` -### 本地开发 +### 3.本地开发 ```bash npm run start ``` -浏览器访问 +完成以上 3 个步骤，浏览器访问 即可调该框架的任何内容 -### 目录结构 +## 目录结构 ```text ├── script // 构建代码 @@ -35,7 +41,7 @@ npm run start ### 组件页路由配置 -每一个组件页，都是一个 md 文件，参考 `/site/site.config.mjs` 已有定义，直接按照模板添加即可 +每一个组件都有自己的路由，页面配置都是一个 markdown 文件，如`button.md`，具体路径可参考 `/site/site.config.mjs`。如果有新增组件，直接按照模板添加即可 ```js { @@ -45,21 +51,21 @@ npm run start { title: 'Button 按钮', name: 'button', - component: () => import(`@/examples/components/button/button.md`), + component: () => import(`tdesign-react/button/button.md`), }, { title: 'Icon 图标', name: 'icon', - component: () => import(`@/examples/components/icon/icon.md`), + component: () => import(`tdesign-react/icon/icon.md`), }, ... ], }, ``` -### Markdown 文件 demo 引用 +### Markdown 文件的 demo 引用 -文档 demo 排列与 common 仓库中的 UI demo 展示一致 +文档 demo 排列与 common 子仓库中的 UI demo 展示一致，如 button 组件页面的展示顺序，由子仓库的 docs/web/api/button.md 内的顺序决定。 ```markdown {{ base }} @@ -68,60 +74,31 @@ npm run start ### Demo 调试 -当一个 md 文件插入了很多个 demo 之后，一些组件生命周期方法调试起来会变得困难，若想对某个 demo 单独调试，可以访问路由：/demos/组件名/demo 名， - -例如： - -### 单元测试 & e2e 测试文档 - -[组件测试文档](./test/README.md) - -## git - -### 分支 - -主仓库遵循使用 `git flow` 规范，新组件分支从 `develop checkout`：[https://nvie.com/posts/a-successful-git-branching-model/](https://nvie.com/posts/a-successful-git-branching-model/) - -如果是贡献组件，则从 `develop checkout` 分支如：`feature/button`，记得如果同时要在子仓库开发 UI，子仓库也要 `checkout` 同名分支 - -#### 关于 fork - -以下内容处理 `fork` 仓库后，远端仓库的更新如何同步到 `fork` 仓库 +我们可以通过打开组件的路由页进行开发调试， -```bash -# 建立 upstream remote -git remote add upstream git@github.com:Tencent/tdesign-react.git +如 button，则打开 进行开发调试； -# 更新 upstream -git fetch upstream develop +但当组件的 markdown 文件插入了很多个 demo 之后，一些组件生命周期方法调试起来会变得困难，若想对某个 demo 单独调试，可以访问路由：/demos/组件名/demo 名， -# 合并 upstream develop 到本地 -git checkout develop +如： -git merge upstream/develop -``` - -## 提交说明 - -项目使用基于 angular 提交规范：[https://github.com/conventional-changelog/commitlint/tree/master/@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/@commitlint/config-conventional) - -每次提交会自动触发提交验证 +### 单元测试 & e2e 测试文档 -- 使用工具 commitizen 协助规范 git commit 信息 -- fix & feat 的提交会被用来生成 changelog -- 提交会触发 git pre-commit 检查，修复提示的 eslint 错误， +[组件测试文档](./test/README.md) -## 公共子仓库 tdesign-common +## 子仓库 tdesign-common -本项目以子仓库的形式引入 `tdesign-common` 公共仓库，对应 `src/\_common` 文件夹 +TDesign 的项目都会以子仓库的形式引入 `tdesign-common` 公共仓库，对应 `src/\_common` 文件夹， 公共仓库中包含 -- 一些公共的工具函数 -- 组件库 `UI` 开发内容，既 `html` 结构和 `css` 样式（React/Vue 共用） +- 部分组件的一些框架无关的公共的工具函数 +- `组件库UI`，既 `html` 结构和 `css` 样式（多框架共用） + +大部分的功能和改动都只需要调整主仓库的代码即可，但涉及部分公共函数、样式或者部分文档的调整，需要改动子仓库的代码。 ### 初始化子仓库 -- 初次克隆代码后需要初始化子仓库： `git submodule init && git submodule update` +- 如开发部分提到的，初次克隆代码后需要初始化子仓库： `git submodule init && git submodule update` - git submodule update 之后子仓库不指向任何分支，只是一个指向某一个提交的游离状态 ### 子仓库开发 @@ -131,9 +108,10 @@ git merge upstream/develop - 先进入 `src/\_common` 文件夹，正常将样式修改添加提交 - 回到主仓库，此时应该会看到 `src/\_common` 文件夹是修改状态，按照正常步骤添加提交即可 -## 关于组件库 UI +### 组件库 UI -UI 开发（HTML & CSS）是多个框架共用的，比如 React-web/Vue-web/react web。各个框架组件实现应该要复用 UI 开发的 html 结构，引用其组件 CSS 与 Demo CSS（本仓库已在入口处引用了），UI 开发一般可由单独的 UI 开发同学认领完成或各框架组件开发同学的其中一名同学完成 +UI 是多个框架共用的，比如 PC 端的 react/vue/vue-next 都是复用子仓库的 UI 代码。 +各个框架组件实现应该要复用 UI 开发的 html 结构，引用其组件 CSS 与 Demo CSS（本仓库已在入口处引用了），UI 开发一般可由单独的 UI 开发同学认领完成或各框架组件开发同学的其中一名同学完成 - 如果开发前已有某个组件的 UI 开发内容，直接在主仓库使用即可 - 如果没有，且你也负责 UI 开发：参考 UI 开发规范完成 UI 开发内容、然后再开发主仓库组件 @@ -153,24 +131,51 @@ UI 开发（HTML & CSS）是多个框架共用的，比如 React-web/Vue-web/rea import './button.less'; ``` -## 开发规范 +## 分支规范 -UI 开发规范参考子仓库 README [子仓库 README](https://github.com/Tencent/tdesign-common/blob/main/style/web/README.md) +### 分支 + +遵循使用 `git flow` 规范，新组件分支从 `develop checkout`：[https://nvie.com/posts/a-successful-git-branching-model/](https://nvie.com/posts/a-successful-git-branching-model/) + +如果是贡献组件，则从 `develop checkout` 分支如：`feature/button`，记得如果同时要在子仓库开发 UI，子仓库也要 `checkout` 同名分支 -### 新建组件 +> 关于 fork -```shell -npm run generate:component +以下内容处理 `fork` 仓库后，远端仓库的更新如何同步到 `fork` 仓库 + +```bash +# 建立 upstream remote +git remote add upstream git@github.com:Tencent/tdesign-react.git + +# 更新 upstream +git fetch upstream develop + +# 合并 upstream develop 到本地 +git checkout develop + +git merge upstream/develop ``` +### 提交说明 + +项目使用基于 angular 提交规范：[https://github.com/conventional-changelog/commitlint/tree/master/@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/@commitlint/config-conventional) + +每次提交会自动触发提交验证 + +- 使用工具 commitizen 协助规范 git commit 信息 +- fix & feat 的提交会被用来生成 changelog +- 提交会触发 git pre-commit 检查，修复提示的 eslint 错误， + +## 开发规范 + ### API 规范 -API 由 API 平台统一管理生成 https://github.com/TDesignOteam/tdesign-api +API 由 API 平台统一管理生成，如果涉及组件文档的改动（如`src/button/type.ts`的内容），都需要同时在 API 平台提交 PR，进行统一维护管理 https://github.com/tdesignoteam/tdesign-api -### 前缀 +### 前缀规范 组件和 `CSS` 前缀以 `t-` 开头，无论 `js` 还是 `css` 都使用变量定义前缀，方便后续替换 -### CSS +### CSS 规范 组件样式在 `common` 子仓库开发，遵循 [tdesign-common 仓库 UI 开发规范](https://github.com/Tencent/tdesign-common/blob/main/style/web/README.md)