From 6ad5420d8ee35f2e830d30799ba10fa82703db1c Mon Sep 17 00:00:00 2001 From: Kagol Date: Thu, 8 Feb 2024 10:04:55 +0800 Subject: [PATCH] docs: optimize contributing guide docs (#1382) --- CONTRIBUTING.md | 52 ++++++++++++++++++++++++++----------------- CONTRIBUTING.zh-CN.md | 48 ++++++++++++++++++++++++--------------- 2 files changed, 62 insertions(+), 38 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4efc4452e..7629e4196 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -38,36 +38,47 @@ The following information is required for the Issue of the new feature: Before submitting pull request, please make sure that your submission is in line with the overall plan of TinyVue. Generally, issues that marked as [bug](https://github.com/opentiny/tiny-vue/labels/bug) are encouraged to submit pull requests. If you are not sure, you can create a [Discussion](https://github.com/opentiny/tiny-vue/discussions) for discussion. -### Pull Request specification +### Pull Request Specification -- The commit message should be in the form of a `type(scope): description of the message`, e.g. `fix(vue-renderless): [scrollbar, action-menu] fix xxx bug`. +#### Commit Message - 1. type: must be one of build, chore, ci, docs, feat, fix, perf, refactor, revert, release, style, test, improvement. +The commit message should be in the form of a `type(scope): description of the message`, e.g. `fix(vue-renderless): [scrollbar, action-menu] fix xxx bug`. - 2. scope. +1. type: must be one of build, chore, ci, docs, feat, fix, perf, refactor, revert, release, style, test, improvement. - - Package names in the `packages` directory, e.g. `vue-design-aurora, vue-design-saas, react ......` - - Component name under the package name in the `packages` directory, e.g., `vue-design-aurora/alert, vue-design-saas/alert, react/alert ......` - - The name of the folder to use: e.g.: `gulp, internals/playwright-config, sites` - - The name of the component (lowercase, center dot): e.g.: `action-menu, alert ......` +2. scope. -- Pull Request title +- Package names in the `packages` directory, e.g. `vue-design-aurora, vue-design-saas, react ......` +- Component name under the package name in the `packages` directory, e.g., `vue-design-aurora/alert, vue-design-saas/alert, react/alert ......` +- The name of the folder to use: e.g.: `gulp, internals/playwright-config, sites` +- The name of the component (lowercase, center dot): e.g.: `action-menu, alert ......` - 1. The specification of the title is the same as the commit information, which is entered in the form of `type(scope): description information`. +#### Pull Request Title - 2. **e2e test** of trigger components: Adding '[componentName1, componentName2]' to the Pull Request title will execute test cases for componentName1, componentName2, and declare this structure when changes to code affect components. +1. The specification of the title is the same as the commit information, which is entered in the form of `type(scope): description information`. - - Note: The `github action` in this project identifies test e2e use cases to be executed by matching the component names declared by `[componentName1, componentName2]` with the path names in the `examples/sites/demos` directory. (Because running the full test case is too time consuming) +2. **e2e test** of trigger components: Adding '[componentName1, componentName2]' to the Pull Request title will execute test cases for componentName1, componentName2, and declare this structure when changes to code affect components. - - When modifying a sub-component of a component, such as the `col` component, which has no corresponding examples and test cases, the `layout` component should be tested, because the `col` component is a sub-component of the `layout` component. The PR title can be: `fix(col): [layout] xxxxxxxxxxxxxx` + - Note: The `github action` in this project identifies test e2e use cases to be executed by matching the component names declared by `[componentName1, componentName2]` with the path names in the `examples/sites/demos` directory. (Because running the full test case is too time consuming) - 3. Example title: + - When modifying a sub-component of a component, such as the `col` component, which has no corresponding examples and test cases, the `layout` component should be tested, because the `col` component is a sub-component of the `layout` component. The PR title can be: `fix(col): [layout] xxxxxxxxxxxxxx` - - Supplement alert component document: `docs(alert): [alert] xxxxxxxxxxxxxxx`, `docs(site): [alert] xxxxxxxxxxxxxxx` - - Supplement alet component test case: `test(alert): [alert] xxxxxxxxxxxxxx` - - Fixed bug in alet component @opentiny/vue-renderless: `fix(vue-renderless/alert): [alert] xxxxxxxxxxxxxx` +3. Example title: -Local startup steps: +- Supplement alert component document: `docs(alert): [alert] xxxxxxxxxxxxxxx`, `docs(site): [alert] xxxxxxxxxxxxxxx` +- Supplement alet component test case: `test(alert): [alert] xxxxxxxxxxxxxx` +- Fixed bug in alet component @opentiny/vue-renderless: `fix(vue-renderless/alert): [alert] xxxxxxxxxxxxxx` + +#### Pull Request Description + +The PR description uses a template, and it is necessary to fill in the relevant information of the PR according to the template, mainly including: + +- PR Checklist: Whether the Commit information is compliant with the specifications, whether it supplements the E2E test cases, and whether it supplements the documentation +- PR Type: Bugfix / Feature / Code style update / Refactoring and so on +- Issue Number +- Does this PR introduce a breaking change? + +### Local Startup Steps - Click the Fork button in the upper right corner of the [TinyVue](https://github.com/opentiny/tiny-vue) code repository to Fork the upstream repository to the personal repository. - Clone personal repository to local. @@ -94,7 +105,7 @@ pnpm dev pnpm dev:vue2 ``` -To submit a PR: +### Submit a PR - Make sure that you have completed the steps in local startup and can visit [http://127.0.0.1:7130/](http://127.0.0.1:7130/) normally. - Synchronize upstream repository dev branch latest code: `git pull upstream dev`. @@ -103,13 +114,14 @@ To submit a PR: - Submit according to [Commit Message Format](https://www.conventionalcommits.org/zh-hans/v1.0.0/) specification. PR that do not conform to the submission specification will not be merged. - Submit to remote repository: `git push origin branchName`. - Open the [Pull requests](https://github.com/opentiny/tiny-vue/pulls) link of the TinyVue code repository and click the New pull request button to submit the PR. +- According to the PR template, please provide the following information: PR self-check items, PR type, related Issue ID, whether it is a destructive change. - Project Committer conducts Code Review and makes comments. - The PR author adjusts the code according to the opinion. Please note that when a branch initiates PR, the subsequent commit will be synchronized automatically, and there is no need to resubmit the PR. - Project administrator merges PR. The contribution process is over, thank you for your contribution! -## Join OpenTiny community +## Join OpenTiny Community If you are interested in our open source project, you are welcome to join our open source community in the following ways. diff --git a/CONTRIBUTING.zh-CN.md b/CONTRIBUTING.zh-CN.md index f26de793a..a8627d612 100644 --- a/CONTRIBUTING.zh-CN.md +++ b/CONTRIBUTING.zh-CN.md @@ -40,34 +40,45 @@ ### Pull Request 规范 -- commit 信息要以 `type(scope): 描述信息` 的形式填写，例如 `fix(vue-renderless): [scrollbar, action-menu] fix xxx bug`。 +#### Commit 信息 - 1. type: 必须是 build, chore, ci, docs, feat, fix, perf, refactor, revert, release, style, test, improvement 其中的一个。 +commit 信息要以 `type(scope): 描述信息` 的形式填写，例如 `fix(vue-renderless): [scrollbar, action-menu] fix xxx bug`。 - 2. scope: +1. type: 必须是 build, chore, ci, docs, feat, fix, perf, refactor, revert, release, style, test, improvement 其中的一个。 - - `packages`目录下的包名，比如：`vue-design-aurora, vue-design-saas, react ......` - - `packages`目录下的包名下的组件名，比如：`vue-design-aurora/alert, vue-design-saas/alert, react/alert ......` - - 用文件夹的名称: 比如: `gulp, internals/playwright-config, sites` - - 组件的名称(小写，中划线): 比如: `action-menu, alert ......` +2. scope: -- Pull Request 的标题 +- `packages`目录下的包名，比如：`vue-design-aurora, vue-design-saas, react ......` +- `packages`目录下的包名下的组件名，比如：`vue-design-aurora/alert, vue-design-saas/alert, react/alert ......` +- 用文件夹的名称: 比如: `gulp, internals/playwright-config, sites` +- 组件的名称(小写，中划线): 比如: `action-menu, alert ......` - 1. 标题的规范与 commit 信息一样，以`type(scope): 描述信息` 的形式填写。 +#### Pull Request 的标题 - 2. 触发组件的 **e2e 测试**: 在 Pull Request 标题里添加 `[componentName1, componentName2]`，将会执行 componentName1，componentName2 的测试用例，当改动的代码会影响组件时，需要声明这个结构。 +1. 标题的规范与 commit 信息一样，以`type(scope): 描述信息` 的形式填写。 - - 注：本项目下的 `github action` 会用`[componentName1, componentName2]`声明的组件名匹配 `examples/sites/demos` 目录下的路径名称，识别要执行的测试e2e用例。（因为全量跑测试用例太耗费时间） +2. 触发组件的 **e2e 测试**: 在 Pull Request 标题里添加 `[componentName1, componentName2]`，将会执行 componentName1，componentName2 的测试用例，当改动的代码会影响组件时，需要声明这个结构。 - - 当修改了某个组件的子组件，比如`col`组件，它本身没有对应的示例以及测试用例，这时应该要测试的是`layout`组件，因为`col`组件是`layout`组件的子组件，PR 标题可以这样： `fix(col): [layout] xxxxxxxxxxxxxx` + - 注：本项目下的 `github action` 会用`[componentName1, componentName2]`声明的组件名匹配 `examples/sites/demos` 目录下的路径名称，识别要执行的测试e2e用例。（因为全量跑测试用例太耗费时间） - 3. 标题示例: + - 当修改了某个组件的子组件，比如`col`组件，它本身没有对应的示例以及测试用例，这时应该要测试的是`layout`组件，因为`col`组件是`layout`组件的子组件，PR 标题可以这样： `fix(col): [layout] xxxxxxxxxxxxxx` - - 补充 alert 组件文档： `docs(alert): [alert] xxxxxxxxxxxxxxx`, `docs(site): [alert] xxxxxxxxxxxxxxx` - - 补充 alet 组件测试用例: `test(alert): [alert] xxxxxxxxxxxxxx` - - 修复 alet 组件 @opentiny/vue-renderless 下的缺陷: `fix(vue-renderless/alert): [alert] xxxxxxxxxxxxxx` +3. 标题示例: -本地启动步骤： +- 补充 alert 组件文档： `docs(alert): [alert] xxxxxxxxxxxxxxx`, `docs(site): [alert] xxxxxxxxxxxxxxx` +- 补充 alet 组件测试用例: `test(alert): [alert] xxxxxxxxxxxxxx` +- 修复 alet 组件 @opentiny/vue-renderless 下的缺陷: `fix(vue-renderless/alert): [alert] xxxxxxxxxxxxxx` + +#### Pull Request 的描述 + +PR 描述使用了模板，需要按照模板填写 PR 相关信息，主要包括： + +- PR 自检项：Commit 信息是够符合规范、是否补充了 E2E 测试用例、是否补充了文档 +- PR 类型：缺陷修复、新特性、代码格式调整、重构等 +- 关联的 Issue 编号 +- 是否包含破坏性变更 + +### 本地启动步骤 - 点击 [TinyVue](https://github.com/opentiny/tiny-vue) 代码仓库右上角的 Fork 按钮，将上游仓库 Fork 到个人仓库 - Clone 个人仓库到本地 @@ -94,7 +105,7 @@ pnpm dev pnpm dev:vue2 ``` -提交 PR 的步骤： +### 提交 PR 的步骤 - 请确保你已经完成本地启动中的步骤，并能正常访问：[http://127.0.0.1:7130/](http://127.0.0.1:7130/) - 同步上游仓库 dev 分支最新代码：git pull upstream dev @@ -103,6 +114,7 @@ pnpm dev:vue2 - 遵循 [Commit Message Format](https://www.conventionalcommits.org/zh-hans/v1.0.0/) 规范进行提交，不符合提交规范的 PR 将不会被合并 - 提交到远程仓库：git push origin branchName - 打开 TinyVue 代码仓库的 [Pull requests](https://github.com/opentiny/tiny-vue/pulls) 链接，点击 New pull request 按钮提交 PR +- 按照 PR 模板补充相关信息，包括 PR 自检项、PR 类型、关联的 Issue 编号、是否是破坏性变更 - 项目 Committer 进行 Code Review，并提出意见 - PR 作者根据意见调整代码，请注意一个分支发起了 PR 后，后续的 commit 会自动同步，无需重新提交 PR - 项目管理员合并 PR