Skip to content

Commit

Permalink
chore: update readme and package.json (antvis#3839)
Browse files Browse the repository at this point in the history
* docs: add Readme, Contributing...

* chore: update meta info in package.json

* docs: update features
  • Loading branch information
hustcc committed Mar 30, 2022
1 parent e9d0c79 commit b563dbf
Show file tree
Hide file tree
Showing 7 changed files with 585 additions and 15 deletions.
20 changes: 20 additions & 0 deletions .github/ISSUE_TEMPLATE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
<!--
Thank you for your pull request. Please review below requirements.
Bug fixes and new features should include tests and possibly benchmarks.
Contributors guide: https://github.com/antvis/g2/blob/master/CONTRIBUTING.md
感谢您贡献代码。请确认下列 checklist 的完成情况。
Bug 修复和新功能必须包含测试,必要时请附上性能测试。
Contributors guide: https://github.com/antvis/g2/blob/master/CONTRIBUTING.md
-->

##### Checklist
<!-- Remove items that do not apply. For completed items, change [ ] to [x]. -->

- [ ] `npm test` passes
- [ ] benchmarks are included
- [ ] commit message follows commit guidelines
- [ ] documents are updated

##### Description of change
<!-- Provide a description of the change below this comment. -->
24 changes: 24 additions & 0 deletions .github/PULL_REQUEST_TEMPLATE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
<!--
Thank you for reporting an issue.
1. It's RECOMMENDED to submit PR for typo or tiny bug fix.
2. If this's a FEATURE request, please provide: details, pseudo codes if necessary.
3. If this's a BUG, please provide: course repetition, error log and configuration. Fill in as much of the template below as you're able.
4. It will be nice to use to provide a CodePen Link which can reproduce the issue, we provide a CodePen template [g2-github-issue](https://codepen.io/leungwensen/pen/WXJgox).
感谢您向我们反馈问题。
1. 提交问题前,请先阅读 README 中的贡献帮助文档。
2. 我们推荐如果是小问题(错别字修改,小的 bug fix)直接提交 PR。
3. 如果是一个新需求,请提供:详细需求描述,最好是有伪代码实现。
4. 如果是一个 BUG,请提供:复现步骤,错误日志以及相关配置,并尽量填写下面的模板中的条目。
5. 如果可以,请提供尽可能精简的 CodePen 链接,可使用 CodePen 模板 https://codepen.io/leungwensen/pen/WXJgox,方便我们排查问题。
6. 扩展阅读:[如何向开源项目提交无法解答的问题](https://zhuanlan.zhihu.com/p/25795393)
-->

* **G2 Version**:
* **Platform**:
* **Mini Showcase(like screenshots)**:
* **CodePen Link**:

<!-- Enter your issue details below this comment. -->
139 changes: 139 additions & 0 deletions CONTRIBUTING.en-US.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,139 @@
# Contribution Guide

If you have any comment or advice, please report your [issue](https://github.com/antvis/g2/issues),
or make any change as you wish and submit an [PR](https://github.com/antvis/g2/pulls).

## Reporting 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 tags(see **Useful Tags**), title, or content.

AntV group members will confirm the purpose of the issue, replace more accurate tags for it, identify related milestone, and assign developers working on it.

## Submitting Code

### Pull Request Guide

If you are developer of AntV repo and you are willing to contribute, feel free to create a new branch, finish your modification and submit a PR. AntV group will review your work and merge it to master branch.

```bash
# 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
$ npm 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 written 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 [G2](https://github.com/antvis/g2/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 scale 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 `$ npm run lint`.

### 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.

```xml
<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

(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 reason 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.

```plain
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 antvis/g2#123
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

G2 uses semantic versioning in release process based on [semver].

### Branch Strategy

`master` branch is the latest stable version.

- just checkout develop branch from `master`
- All new features will be added into `master` or `next` branch as well as all bug-fix except security issues. In such way, we can motivate developers to update to the latest stable version.

### 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], and write `History` as [node CHANGELOG]. Don't forget to correct content in documentation which is related to the releasing version. Commits can be generated automatically.
```bash
$ npm run commits
```
- Nominate PM for next stable version.

[semver]: http://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
[『我是如何发布一个 npm 包的』]: https://fengmk2.com/blog/2016/how-i-publish-a-npm-package
147 changes: 147 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,147 @@
# 代码贡献规范

有任何疑问,欢迎提交 [issue](https://github.com/antvis/g2/issues)
或者直接修改提交 [PR](https://github.com/antvis/g2/pulls)!

## 提交 issue

- 请确定 issue 的类型。
- 请避免提交重复的 issue,在提交之前搜索现有的 issue。
- 在标签(分类参考**标签分类**), 标题 或者内容中体现明确的意图。

随后 AntV 负责人会确认 issue 意图,更新合适的标签,关联 milestone,指派开发者。

## 提交代码

### 提交 Pull Request

如果你有仓库的开发者权限,而且希望贡献代码,那么你可以创建分支修改代码提交 PR,AntV 开发团队会 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
```

提交后就可以在 [G2](https://github.com/antvis/g2/pulls) 创建 Pull Request 了。

由于谁也无法保证过了多久之后还记得多少,为了后期回溯历史的方便,请在提交 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

修改文件的范围

(3)subject

用一句话清楚的描述这次提交做了什么

(4)body

补充 subject,适当增加原因、目的等相关因素,也可不写。

(5)footer

- **当有非兼容修改(Breaking Change)时必须在这里描述清楚**
- 关联相关 issue,如 `Closes #1, Closes #2, #3`

示例

```plain
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 antvis/g2#12
Closes #392
BREAKING CHANGE:
Breaks foo.bar api, foo.baz should be used instead
```

查看具体[文档](https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/edit)

## 发布管理

G2 基于 [semver] 语义化版本号进行发布。

`master` 分支为当前稳定发布的版本。

- 直接从 `master` 切出开发分支
- 所有 API 的废弃都需要在当前的稳定版本上 `deprecate` 提示,并保证在当前的稳定版本上一直兼容到新版本的发布。

### 发布策略

每个大版本都有一个发布经理管理(PM),他/她要做的事情

#### 准备工作

- 建立 milestone,确认需求关联 milestone,指派和更新 issues。

#### 发布前

- 确认当前 Milestone 所有的 issue 都已关闭或可延期,完成性能测试。
- 发起一个新的 [Release Proposal MR],按照 [node CHANGELOG] 进行 `History` 的编写,修正文档中与版本相关的内容,commits 可以自动生成。
```bash
$ npm run commits
```
- 指定下一个大版本的 PM。

#### 发布时

- 将老的稳定版本(master)备份到以当前大版本为名字的分支上(例如 `1.x`),并设置 tag 为 {v}.x`( v 为当前版本,例如`1.x`)。
- 发布新的稳定版本到 [npm],并通知上层框架进行更新。
- `npm publish` 之前,请先阅读[『我是如何发布一个 npm 包的』]

[semver]: http://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
[npm]: http://npmjs.com/
[『我是如何发布一个 npm 包的』]: https://fengmk2.com/blog/2016/how-i-publish-a-npm-package
Loading

0 comments on commit b563dbf

Please sign in to comment.