狼叔
4 years ago
1 changed files with 205 additions and 0 deletions
@ -0,0 +1,205 @@ |
|||
# 代码贡献规范 |
|||
|
|||
有任何疑问,欢迎提交 [issue](https://github.com/imgcook/imove/issues), |
|||
或者直接修改提交 [PR](https://github.com/imgcook/imove/pulls)! |
|||
|
|||
## 提交 issue |
|||
|
|||
- 请确定 issue 的类型。 |
|||
- 请避免提交重复的 issue,在提交之前搜索现有的 issue。 |
|||
- 在标签(分类参考**标签分类**), 标题 或者内容中体现明确的意图。 |
|||
|
|||
随后 imove 负责人会确认 issue 意图,更新合适的标签,关联 milestone,指派开发者。 |
|||
|
|||
标签可分为两类,type 和 scope |
|||
|
|||
- type: issue 的类型,如 `feature`, `bug`, `documentation`, `performance`, `support` ... |
|||
- scope: 修改文件的范围,如 `core: xx`,`plugin: xx`,`deps: xx` |
|||
|
|||
### 常用标签说明 |
|||
|
|||
- `support`: issue 提出的问题需要开发者协作排查,咨询,调试等等日常技术支持。 |
|||
- `bug`: 一旦发现可能是 bug 的问题,请打上 `bug`,然后等待确认,一旦确认是 bug,此 issue 会被再打上 `confirmed`。 |
|||
- 此时 issue 会被非常高的优先级进行处理。 |
|||
- 如果此 bug 是正在影响线上应用正常运行,会再打上 `critical`,代表是最高优先级,需要马上立刻处理! |
|||
- bug 会在最低需要修复的版本进行修复,如是在 `0.9.x` 要修复的,而当前最新版本是 `1.1.x`, |
|||
那么此 issue 还会被打上 `0.9`,`0.10`,`1.0`,`1.1`,代表需要修复到这些版本。 |
|||
- `core: xx`: 代表 issue 跟 core 内核相关,如 `core: antx` 代表跟 `antx` 配置相关。 |
|||
- `plugin: xx`: 代表 issue 跟插件相关,如 `deps: session` 代表跟 `session` 插件相关。 |
|||
- `deps: xx`: 代表 issue 跟 `dependencies` 模块相关,如 `deps: egg-cors` 代表跟 `egg-cors` 模块相关。 |
|||
- `chore: documentation`: 代表发现了文档相关问题,需要修复文档说明。 |
|||
- `cbd`: 代表跟服务器部署相关 |
|||
|
|||
## 编写文档 |
|||
|
|||
所有功能点必须提交配套文档,文档须满足以下要求 |
|||
|
|||
- 必须说清楚问题的几个方面:what(是什么),why(为什么),how(怎么做),可根据问题的特性有所侧重。 |
|||
- how 部分必须包含详尽完整的操作步骤,必要时附上 **足够简单,可运行** 的范例代码, |
|||
所有范例代码放在 [imove/examples](https://github.com/imgcook/imove) 库中。 |
|||
- 提供必要的链接,如申请流程,术语解释和参考文档等。 |
|||
- 同步修改中英文文档,或者在 PR 里面说明。 |
|||
|
|||
## 提交代码 |
|||
|
|||
### 提交 Pull Request |
|||
|
|||
如果你有仓库的开发者权限,而且希望贡献代码,那么你可以创建分支修改代码提交 PR,ykfe 开发团队会 review 代码合并到主干。 |
|||
|
|||
```bash |
|||
# 先创建开发分支开发,分支名应该有含义,避免使用 update、tmp 之类的 |
|||
$ git checkout -b branch-name |
|||
|
|||
# 开发完成后跑下测试是否通过,必要时需要新增或修改测试用例 |
|||
$ npm test |
|||
|
|||
# 测试通过后,提交代码,message 见下面的规范 |
|||
|
|||
$ git add . # git add -u 删除文件 |
|||
$ git commit -m "fix(role): role.use must xxx" |
|||
$ git push origin branch-name |
|||
``` |
|||
|
|||
由于谁也无法保证过了多久之后还记得多少,为了后期回溯历史的方便,请在提交 MR 时确保提供了以下信息。 |
|||
|
|||
1. 需求点(一般关联 issue 或者注释都算) |
|||
2. 升级原因(不同于 issue,可以简要描述下为什么要处理) |
|||
3. 框架测试点(可以关联到测试文件,不用详细描述,关键点即可) |
|||
4. 关注点(针对用户而言,可以没有,一般是不兼容更新等,需要额外提示) |
|||
|
|||
### 代码风格 |
|||
|
|||
你的代码风格必须通过 eslint,你可以运行 `$ npm run lint` 本地测试。 |
|||
|
|||
### Commit 提交规范 |
|||
|
|||
根据 [angular 规范](https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md#commit-message-format)提交 commit, |
|||
这样 history 看起来更加清晰,还可以自动生成 changelog。 |
|||
|
|||
```xml |
|||
<type>(<scope>): <subject> |
|||
<BLANK LINE> |
|||
<body> |
|||
<BLANK LINE> |
|||
<footer> |
|||
``` |
|||
|
|||
(1)type |
|||
|
|||
提交 commit 的类型,包括以下几种 |
|||
|
|||
- feat: 新功能 |
|||
- fix: 修复问题 |
|||
- docs: 修改文档 |
|||
- style: 修改代码格式,不影响代码逻辑 |
|||
- refactor: 重构代码,理论上不影响现有功能 |
|||
- perf: 提升性能 |
|||
- test: 增加修改测试用例 |
|||
- chore: 修改工具相关(包括但不限于文档、代码生成等) |
|||
- deps: 升级依赖 |
|||
|
|||
(2)scope |
|||
|
|||
修改文件的范围(包括但不限于 doc, middleware, core, config, plugin) |
|||
|
|||
(3)subject |
|||
|
|||
用一句话清楚的描述这次提交做了什么 |
|||
|
|||
(4)body |
|||
|
|||
补充 subject,适当增加原因、目的等相关因素,也可不写。 |
|||
|
|||
(5)footer |
|||
|
|||
- **当有非兼容修改(Breaking Change)时必须在这里描述清楚** |
|||
- 关联相关 issue,如 `Closes #1, Closes #2, #3` |
|||
- 如果功能点有新增或修改的,还需要关联文档 `doc` 和 `egg-core` 的 PR,如 `eggjs/egg-core#123` |
|||
|
|||
示例 |
|||
|
|||
``` |
|||
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 eggjs/egg#123 |
|||
|
|||
Closes #392 |
|||
|
|||
BREAKING CHANGE: |
|||
|
|||
Breaks foo.bar api, foo.baz should be used instead |
|||
``` |
|||
|
|||
详情请查看具体[文档](https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/edit)。 |
|||
|
|||
### 英语翻译规范 |
|||
|
|||
英语正文按照一般英语语法规律书写即可,但标题比较特殊,应该按照以下规范进行书写: |
|||
|
|||
- 名词、动词、代词、形容词、副词等首字母大写,介词、冠词、连词、感叹词和助词首字母小写,*标题第一个单词、最后一个单词无论词性首字母应该大写*。 |
|||
- 专有名词(如直接引用某个变量,或者某个插件名称等),必须使用反单引号(键盘上 Esc 正下方)进行引用,并保持原来大小写。 |
|||
- 超过5个字母的介词首字母应该大写,否则一律小写。 |
|||
- 如果是重要提示性标题,或者是专有名称标题(例如 Http 请求方法:GET,POST,PUT,DELETE),可以全部字母都用大写(慎重考虑)。 |
|||
- 如果标题属于“动宾”性质的短语(如“配置管理”),尽量翻译成“宾+动词名词”的形式(Configuration Management),或者是“动名词+宾语”的形式(Managing Configuration)。 |
|||
- 如果标题被当做一个完整的英语句子,请按照英语句子的语法格式大小写(如:常见问题 FAQ 中每一个标题都是一个英语句子)。 |
|||
|
|||
有关详情,可以参考[英语标题大小写]。 |
|||
|
|||
## 发布管理 |
|||
|
|||
imove 基于 [semver] 语义化版本号进行发布。 |
|||
|
|||
### 分支策略 |
|||
|
|||
`master` 分支为当前稳定发布的版本,`next` 分支为下一个开发中的大版本。 |
|||
|
|||
- 只维护两个版本,除非有安全问题,否则修复只会 patch 到 `master` 和 `next` 分支,其他更新推动上层框架升级到稳定大版本的最新版本。 |
|||
- 所有 API 的废弃都需要在当前的稳定版本上 `deprecate` 提示,并保证在当前的稳定版本上一直兼容到新版本的发布。 |
|||
- `master` 分支不设置 publish tag,上层框架基于 semver 依赖稳定版本。 |
|||
- `next` 分支设置 tag 为 `next`,上层框架可以通过 `egg@next` 引用开发中的版本进行测试。 |
|||
- egg 持续维护的版本以 Milestone 为准,只要是开着的版本都会进行修复。 |
|||
|
|||
### 发布策略 |
|||
|
|||
每个大版本都有一个发布经理管理(PM),他/她要做的事情 |
|||
|
|||
#### 准备工作: |
|||
|
|||
- 建立 milestone,确认需求关联 milestone,指派和更新 issues,如 [1.x milestone]。 |
|||
- 从 `master` 分支新建 `next` 分支,并设置 tag 为 `next`。 |
|||
|
|||
#### 发布前: |
|||
|
|||
- 确认当前 Milestone 所有的 issue 都已关闭或可延期,完成性能测试。 |
|||
- 发起一个新的 [Release Proposal MR],按照 [node CHANGELOG] 进行 `History` 的编写,修正文档中与版本相关的内容,commits 可以自动生成。 |
|||
```bash |
|||
$ npm run commits |
|||
``` |
|||
- 指定下一个大版本的 PM。 |
|||
|
|||
#### 发布时: |
|||
|
|||
- 将老的稳定版本(master)备份到以当前大版本为名字的分支上(例如 `1.x`),并设置 tag 为 `release-{v}.x`( v 为当前版本,例如 `release-1.x`)。 |
|||
- 将 `next` 分支推送到 `master`,成为新的稳定版本分支,并去除 `next` tag,修改 README 中与分支相关的内容。 |
|||
- 发布新的稳定版本到 [npm],并通知上层框架进行更新。 |
|||
- `npm publish` 之前,请先阅读 [我是如何发布一个 npm 包的]。 |
|||
|
|||
上述描述中所有的设置 tag 都是指在 `package.json` 中设置 npm 的 tag。 |
|||
|
|||
```json |
|||
"publishConfig": { |
|||
"tag": "next" |
|||
} |
|||
``` |
|||
|
|||
[semver]: https://semver.org/lang/zh-CN/ |
|||
[Release Proposal MR]: https://github.com/nodejs/node/pull/4181 |
|||
[node CHANGELOG]: https://github.com/nodejs/node/blob/master/CHANGELOG.md |
|||
[1.x milestone]: https://github.com/eggjs/egg/milestone/1 |
|||
[npm]: http://npmjs.com/ |
|||
[我是如何发布一个 npm 包的]: https://fengmk2.com/blog/2016/how-i-publish-a-npm-package |
|||
[英语标题大小写]: https://headlinecapitalization.com/ |
Loading…
Reference in new issue