docs: 完善 README.md 以及 CONTRIBUTING 相关文档，解决 eslint 问题

- 完善开源共享引导文档：README 以及 CONTRIBUTING - 项目根目录运行 pnpm run lint:ts，解决项目中 eslint 错误及 warning
didi · Jun 13, 2024 · ef92a41 · ef92a41
1 parent 07cfa0d
commit ef92a41
Show file tree

Hide file tree

Showing 13 changed files with 877 additions and 1,272 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,65 +1,145 @@
-# Contribution Guideline
+# 代码贡献规范
 
-## Pull Requests
+如果您有任何疑问，欢迎提交[issue](https://github.com/didi/LogicFlow/issues) 或 [PR](https://github.com/didi/LogicFlow/pulls)!
 
-LogicFlow对外持开放态度，不论是只修改文档的标点符号还是对LogicFlow的整体功能有大的重构我们都欢迎。对于您的每一个PR我们都会认真查看、回复、合并。
+## 提交 issues
 
-### Start
+ - 确定 issue 的类型
+ - 避免提交重复的 issue，在提交之前搜索现有的 issue
+ - 在标签、标题或内容中描述明确的意图
 
-我们选用 fork 仓库，然后提交 PR 的形式进行开发。具体方式可以参考: [我是如何在 GitHub 上提交 PR 的](https://juejin.cn/post/6844904103294795789).
+LogicFlow 维护同学会确认 issue 意图，更新合适的标签，关联 milestone，指派开发者。
 
-### 安装项目依赖
+## 提交代码
 
-> 需要提前安装 yarn
+### 发起 Pull Request
+
+如果您有意向参与贡献代码，您可以 fork 本仓库，修改代码后提交 PR，我们 LogicFlow 开发团队会 review 代码并合并到主干。
 
 ```shell
-npm run bootstrap
-```
+# 先创建开发分支开发，分支名应该有含义，避免使用 update、tmp 之类的
+$ git checkout -b branch-name
 
-### 运行文档
+# 开发某个包时，利用 build:watch 监听变化实时打包更新
+$ cd packages/core # or other packages, such as packages/extensions
+$ pnpm run build:watch
 
-```shell
-npm run docs:dev
+# 在新的 Shell 中启动 examples 以开发 demo 并验证功能
+$ cd examples/feature-examples
+$ pnpm start
+
+# 开发完成后跑下测试是否通过，必要时需要新增或修改测试用例
+pnpm run test
+
+# 测试通过后，提交代码，message 见下面的规范
+$ git add . # git add -u 删除文件
+$ git commit -m "fix(role): role.use must xxx"
+$ git push origin branch-name
 ```
 
-### 构建 types 并打包
+提交后就可以在 [LogicFlow](https://github.com/didi/LogicFlow/pulls) 发起 PR 了 (*❦ω❦)
 
-LF 使用 monorepo 的形式进行管理，各个 package 之间存在依赖关系，所以需要先构建一次类型和源码才能进行开发。
+由于谁也无法保证过了多久之后还记得多少，为了后期回溯历史的方便，请在提交 PR 时确保提供了以下信息
 
-```shell
-npm run build:types
+1. 需求点（一般关联 issue 或者注释都算）
+2. 升级原因（不同于 issue，可以简要描述下为什么要处理）
+3. 框架测试点（可以关联到测试文件，不用详细描述，关键点即可）
+4. 关注点（针对用户而言，可以没有，一般是不兼容更新等，需要额外提示）
+
+### 代码风格
+
+你的代码风格必须通过 eslint，你可以运行 `$ pnpm run lint:ts` 本地测试
+
+### Commit 提交规范
 
-npm run build
+根据 [angular 规范](https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md#commit-message-format)提交 commit，这样 history 看起来更加清晰，还可以自动生成 changelog
+
+```
+<type>(<scope>): <subject>
+<BLANK LINE>
+<body>
+<BLANK LINE>
+<footer>
 ```
 
-### 启动本地开发
+（1）type
 
-开发 core 包
+提交 commit 的类型，包括以下几种
 
-```shell
-cd packages/core
-npm run dev
+ - feat: 新功能
+ - fix: 修复问题
+ - docs: 修改文档
+ - style: 修改代码格式，不影响代码逻辑
+ - refactor: 重构代码，理论上不影响现有功能
+ - perf: 提升性能
+ - test: 增加修改测试用例
+ - chore: 修改工具相关（包括但不限于文档、代码生成等）
+ - deps: 升级依赖
+
+（2）scope
+
+修改文件的范围
+
+（3）subject
+
+用一句话清楚的描述这次提交做了什么
+
+（4）body
+
+补充 subject，适当增加原因、目的等相关因素，也可不写
+
+（5）footer
+
+ - **当有非兼容修改(Breaking Change)时必须在这里描述清楚**
+ - 关联相关 issue，如 `Closes #1, Closes #2, #3`
+
+示例
 
-# 或跳过以上“构建部分”直接运行
-npm run dev:core
 ```
+fix($compile): [BREAKING_CHANGE] couple of unit tests for IE9
 
-开发 extension
+Older IEs serialize html uppercased, but IE9 does not...
+Would be better to expect case insensitive, unfortunately jasmine does
+not allow to user regexps for throw expectations.
 
-```shell
-cd packages/extension
-npm run dev
+Document change on @logicflow/core#12
 
-# 或跳过以上“构建部分”直接运行
-npm run dev:extension
+Closes #392
+
+BREAKING CHANGE:
+
+  Breaks foo.bar api, foo.baz should be used instead
 ```
 
-## Issues
+查看具体[文档](https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/edit)
+
+## 发布管理
+
+LogicFlow 基于 [semver](http://semver.org/lang/zh-CN/) 语义化版本号进行发布
+
+### 分支策略
+
+`master` 分支为当前稳定发布的版本。
+
+ - 直接从 `master` 切出分支进行开发
+ - 所有 API 的废弃都需要在当前的稳定版本上 `deprecated` 提示，并保证在当前的稳定版本上一直兼容到新版本的发布
+
+### 发布策略
+
+在每个大版本发布中，都会有一个负责人，他在发布的不同阶段负有以下职责：
+
+#### 准备工作
+
+ - 建立 milestone, 确认需求关联 milestone, 指派和更新 issues
+
+#### 发布前
 
-如果您使用LogicFlow过程中遇到问题或者有任何想法，欢迎点击LogicFlow [issues](https://github.com/didi/LogicFlow/issues)给我们提issue和我们交流。
+ - 确认当前 Milestone 所有的 issue 都已关闭或可延期，完成性能测试
+ - 发起一个新的 [Release Proposal MR](https://github.com/nodejs/node/pull/4181)，按照 [node CHANGELOG](https://github.com/nodejs/node/blob/master/CHANGELOG.md) 进行 `History` 的编写，修正文档中与版本相关的内容
+ - 指定下一个大版本的负责人
 
-一般来说通过文字和截图的描述我们可能无法定位到问题，为了帮助我们快速定位问题并修复，请按照以下指南编写并上传最简复现demo：
+#### 发布时
 
-1. 在任意在线编码平台，编写示例如[codesanbox](https://codesandbox.io/s/logicflow-step3-mhge5)。将其保存到自己空间，然后贴上链接。
-2. 在自己github中创建一个最简单的示例，然后贴上github链接。
-3. 删除项目中的node_modules部分，打包项目，并拖拽到issue输入框中上传（或提供远程可下载地址）
+ - 将老的稳定版本（master）备份到以当前大版本为名字的分支上（例如 `1.x`），并设置 tag 为 {v}.x（ v 为当前版本，例如 `1.x`）
+ - 发布新的稳定版本到 [npm](http://npmjs.com)，并通知上层框架进行更新
+ - `npm publish` 之前，请先阅读[『我是如何发布一个 npm 包的』](https://fengmk2.com/blog/2016/how-i-publish-a-npm-package)
diff --git a/CONTRUBUTING.en-US.md b/CONTRUBUTING.en-US.md
@@ -0,0 +1,146 @@
+# Contribution Guide
+
+If you have any comment or advice, please report your [issue](https://github.com/didi/LogicFlow/issues) or make any change as you wish and submit a [PR](https://github.com/didi/LogicFlow/pulls)!
+
+## Report New Issues
+
+- Please specify what kind of issue it is.
+- Before you report an issue, please search for related issues. Make sure you are not going to open a duplicate issue.
+- Explain your purpose clearly in labels, title, or content.
+
+
+LogicFlow group members will confirm the purpose of the issue, replace more accurate labels for it, identify related milestone, and assign developers working on it.
+
+## Contributing Code
+
+### Pull Requests
+
+If you want to contribute improvements or new features we are happy to review your PR :)
+
+```shell
+$ pnpm install
+
+$ cd packages/core # or other packages, such as packages/extensions
+$ pnpm run build:watch
+
+# create a new shell
+$ cd examples/feature-examples
+$ pnpm start
+
+# Create a new branch for development. The name of branch should be semantic, avoiding words like 'update' or 'tmp'. We suggest to use feature/xxx, if the modification is about to implement a new feature.
+$ git checkout -b branch-name
+
+# Run the test after you finish your modification. Add new test cases or change old ones if you feel necessary
+$ pnpm run test
+
+# If your modification pass the tests, congratulations it's time to push your work back to us. Notice that the commit message should be wirtten in the following format.
+$ git add . # git add -u to delete files
+$ git commit -m "fix(role): role.use must xxx"
+$ git push origin branch-name
+```
+
+Then you can create a Pull Request at [LogicFlow](https://github.com/didi/LogicFlow/pulls) ✿✿ヽ(°▽°)ノ✿
+
+No one can guarantee how much will be remembered about certain PR after some time. To make sure we can easily recap what happened previously, please provide the following information in your PR.
+
+1. Need: What function you want to achieve (Generally, please point out which issue is related).
+2. Updating Reason: Different with issue. Briefly describe your reason and logic about why you need to make such modification.
+3. Related Testing: Briefly describe what part of testing is relevant to your modification.
+4. User Tips: Notice for LogicFlow users. You can skip this part, if the PR is not about update in API or potential compatibility problem.
+
+### Style Guide
+
+eslint can help to identify styling issues that may exist in your code. Your code is required to pass the test from eslint. Run the test locally by `$ pnpm run lint:ts`.
+
+### Commit Message Format
+
+You are encouraged to use [angular commit-message-format](https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md#commit-message-format) to write commit message. In this way, we could have a more trackable history and an automatically generated changelog.
+
+```
+<type>(<scope>): <subject>
+<BLANK LINE>
+<body>
+<BLANK LINE>
+<footer>
+```
+
+（1）type
+
+Must be one of the following:
+
+- feat: A new feature
+- fix: A bug fix
+- docs: Documentation-only changes
+- style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
+- refactor: A code change that neither fixes a bug nor adds a feature
+- perf: A code change that improves performance
+- test: Adding missing tests
+- chore: Changes to the build process or auxiliary tools and libraries such as documentation generation
+- deps: Updates about dependencies
+
+（2）scope
+
+The scope could be anything specifying place of the commit change.
+
+（3）subject
+
+Use succinct words to describe what did you do in the commit change.
+
+（4）body
+
+Feel free to add more content in the body, if you think subject is not self-explanatory enough, such as what it is the purpose or reasons of you commit.
+
+（5）footer
+
+- **If the commit is a Breaking Change, please note it clearly in this part.**
+- related issues, like `Closes #1, Closes #2, #3`
+
+e.g.
+
+```
+fix($compile): [BREAKING_CHANGE] couple of unit tests for IE9
+
+Older IEs serialize html uppercased, but IE9 does not...
+Would be better to expect case insensitive, unfortunately jasmine does
+not allow to user regexps for throw expectations.
+
+Document change on @logicflow/core#12
+
+Closes #392
+
+BREAKING CHANGE:
+
+  Breaks foo.bar api, foo.baz should be used instead
+```
+
+Look at [these files](https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/edit) for more details.
+
+## Release
+
+LogicFlow uses semantic versioning in release process based on [semver](https://semver.org/).
+
+### Branch Strategy
+`master` branch is the latest stable version.
+
+- 直接从 `master` 切出分支进行开发
+- 所有 API 的废弃都需要在当前的稳定版本上 `deprecated` 提示，并保证在当前的稳定版本上一直兼容到新版本的发布
+
+### Release Strategy
+
+In the release of every stable version, there will be a PM who has the following responsibilities in different stages of the release.
+
+#### Preparation
+
+- Set up milestone. Confirm that request is related to milestone.
+
+#### Before Release
+
+- Confirm that performance test is passed and all issues in current Milestone are either closed or can be delayed to later versions.
+- Open a new [Release Proposal MR](https://github.com/nodejs/node/pull/4181), and write `History` as [node CHANGELOG](https://github.com/nodejs/node/blob/master/CHANGELOG.md). Don't forget to correct content in documentation which is related to the releasing version.
+- Nominate PM for next stable version.
+
+#### Releasing
+
+- Backup the old stable version (master) to a branch named after the current major version (e.g. `1.x`) and set the tag to {v}.x (v is the current version, e.g. `1.x`)
+- Release a new stable version to [npm](http://npmjs.com) and notify upper level frameworks of the update
+- Before `npm publish`, read ['How I publish an npm package'](https://fengmk2.com/blog/2016/how-i-publish-a-npm-package)