mirror of https://github.com/open-mmlab/mmcv.git
[Docs] Improve the style of pr.md (#1567)
* [Docs] Improve the style of pr.md * fix symlink * improve style * fix formatpull/1547/head
Zaida Zhou
GitHub
parent
c60a17b603
commit
53c1b2fe91
|
|
@ -1 +1 @@
|
|||
../../CONTRIBUTING.md
|
||||
../../CONTRIBUTING.md
|
||||
|
|
@ -4,7 +4,9 @@
|
|||
|
||||
`PR` is the abbreviation of `Pull Request`. Here's the definition of `PR` in the [official document](https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) of Github.
|
||||
|
||||
> Pull requests let you tell others about changes you've pushed to a branch in a repository on GitHub. Once a pull request is opened, you can discuss and review the potential changes with collaborators and add follow-up commits before your changes are merged into the base branch.
|
||||
```
|
||||
Pull requests let you tell others about changes you have pushed to a branch in a repository on GitHub. Once a pull request is opened, you can discuss and review the potential changes with collaborators and add follow-up commits before your changes are merged into the base branch.
|
||||
```
|
||||
|
||||
### Basic Workflow
|
||||
|
||||
|
|
@ -17,78 +19,96 @@
|
|||
|
||||
### Procedures in detail
|
||||
|
||||
1. Get the most recent codebase
|
||||
+ When you work on your first PR
|
||||
- Fork the OpenMMLab repository: click the **fork** button at the top right corner of Github page
|
||||
|
||||
#### 1. Get the most recent codebase
|
||||
|
||||
- Clone forked repository to local
|
||||
```bash
|
||||
git clone git@github.com:XXX/mmcv.git
|
||||
```
|
||||
+ When you work on your first PR
|
||||
|
||||
- Add source repository to upstream
|
||||
```bash
|
||||
git remote add upstream git@github.com:open-mmlab/mmcv
|
||||
```
|
||||
Fork the OpenMMLab repository: click the **fork** button at the top right corner of Github page
|
||||
|
||||
|
||||
+ After your first PR
|
||||
- Checkout master branch of the local repository and pull the latest master branch of the source repository
|
||||
```bash
|
||||
git checkout master
|
||||
git pull upstream master
|
||||
```
|
||||
Clone forked repository to local
|
||||
|
||||
```bash
|
||||
git clone git@github.com:XXX/mmcv.git
|
||||
```
|
||||
|
||||
Add source repository to upstream
|
||||
|
||||
```bash
|
||||
git remote add upstream git@github.com:open-mmlab/mmcv
|
||||
```
|
||||
|
||||
+ After your first PR
|
||||
|
||||
Checkout master branch of the local repository and pull the latest master branch of the source repository
|
||||
|
||||
2. Checkout a new branch from the master branch
|
||||
```bash
|
||||
git checkout -b branchname
|
||||
git checkout master
|
||||
git pull upstream master
|
||||
```
|
||||
|
||||
#### 2. Checkout a new branch from the master branch
|
||||
|
||||
```bash
|
||||
git checkout -b branchname
|
||||
```
|
||||
|
||||
```{tip}
|
||||
To make commit history clear, we strongly recommend you checkout the master branch before create a new branch.
|
||||
```
|
||||
|
||||
3. Commit your changes
|
||||
#### 3. Commit your changes
|
||||
|
||||
```bash
|
||||
# coding
|
||||
git add [files]
|
||||
git commit -m 'messages'
|
||||
```
|
||||
|
||||
#### 4. Push your changes to the forked repository and create a PR
|
||||
|
||||
+ Push the branch to your forked remote repository
|
||||
|
||||
```bash
|
||||
# coding
|
||||
git add [files]
|
||||
git commit -m 'messages'
|
||||
git push origin branchname
|
||||
```
|
||||
|
||||
4. Push your changes to the forked repository and create a PR
|
||||
+ Push the branch to your forked remote repository
|
||||
```bash
|
||||
git push origin branchname
|
||||
```
|
||||
+ Create a PR
|
||||
|
||||
|
||||
+ Create a PR
|
||||
|
||||
+ Revise PR message template to describe your motivation and modifications made in this PR. You can also link the related issue to the PR manually in the PR message (For more information, checkout the [official guidance](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue)).
|
||||
|
||||
+ Revise PR message template to describe your motivation and modifications made in this PR. You can also link the related issue to the PR manually in the PR message (For more information, checkout the [official guidance](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue)).
|
||||
#### 5. Discuss and review your code
|
||||
|
||||
5. Discuss and review your code
|
||||
+ After creating a pull request, you can ask a specific person to review the changes you've proposed
|
||||
|
||||
+ After creating a pull request, you can ask a specific person to review the changes you've proposed
|
||||
|
||||
|
||||
+ Modify your codes according to reviewers' suggestions and then push your changes
|
||||
+ Modify your codes according to reviewers' suggestions and then push your changes
|
||||
|
||||
6. Merge your branch to the master branch and delete the branch
|
||||
```bash
|
||||
git branch -d branchname # delete local branch
|
||||
git push origin --delete branchname # delete remote branch
|
||||
```
|
||||
#### 6. Merge your branch to the master branch and delete the branch
|
||||
|
||||
```bash
|
||||
git branch -d branchname # delete local branch
|
||||
git push origin --delete branchname # delete remote branch
|
||||
```
|
||||
|
||||
### PR Specs
|
||||
|
||||
1. Use [pre-commit](https://pre-commit.com) hook to avoid issues of code style
|
||||
|
||||
2. One short-time branch should be matched with only one PR
|
||||
|
||||
3. Accomplish a detailed change in one PR. Avoid large PR
|
||||
>- Bad: Support Faster R-CNN
|
||||
>- Acceptable: Add a box head to Faster R-CNN
|
||||
>- Good: Add a parameter to box head to support custom conv-layer number
|
||||
|
||||
+ Bad: Support Faster R-CNN
|
||||
+ Acceptable: Add a box head to Faster R-CNN
|
||||
+ Good: Add a parameter to box head to support custom conv-layer number
|
||||
|
||||
4. Provide clear and significant commit message
|
||||
|
||||
5. Provide clear and meaningful PR description
|
||||
>- Task name should be clarified in title. The general format is: [Prefix] Short description of the PR (Suffix)
|
||||
>- Prefix: add new feature [Feature], fix bug [Fix], related to documents [Docs], in developing [WIP] (which will not be reviewed temporarily)
|
||||
>- Introduce main changes, results and influences on other modules in short description
|
||||
>- Associate related issues and pull requests with a milestone
|
||||
|
||||
+ Task name should be clarified in title. The general format is: [Prefix] Short description of the PR (Suffix)
|
||||
+ Prefix: add new feature [Feature], fix bug [Fix], related to documents [Docs], in developing [WIP] (which will not be reviewed temporarily)
|
||||
+ Introduce main changes, results and influences on other modules in short description
|
||||
+ Associate related issues and pull requests with a milestone
|
||||
|
|
|
|||
|
|
@ -4,71 +4,88 @@
|
|||
|
||||
`拉取请求` (Pull Request), [GitHub 官方文档](https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests)定义如下。
|
||||
|
||||
>拉取请求是一种通知机制。你修改了他人的代码，将你的修改通知原来作者，希望他合并你的修改。
|
||||
```
|
||||
拉取请求是一种通知机制。你修改了他人的代码，将你的修改通知原来作者，希望他合并你的修改。
|
||||
```
|
||||
|
||||
### 基本的工作流：
|
||||
|
||||
1. 获取最新的代码库
|
||||
2. 从主分支创建最新的分支进行开发
|
||||
3. 提交修改
|
||||
4. 推送你的修改并创建一个`拉取请求`
|
||||
4. 推送你的修改并创建一个 `拉取请求`
|
||||
5. 讨论、审核代码
|
||||
6. 将开发分支合并到主分支
|
||||
|
||||
### 具体步骤
|
||||
|
||||
1. 获取最新的代码库
|
||||
+ 当你第一次提 PR 时
|
||||
- 复刻 OpenMMLab 原代码库，点击 GitHub 页面右上角的 **Fork** 按钮即可
|
||||
|
||||
#### 1. 获取最新的代码库
|
||||
|
||||
- 克隆复刻的代码库到本地
|
||||
```bash
|
||||
git clone git@github.com:XXX/mmcv.git
|
||||
```
|
||||
+ 当你第一次提 PR 时
|
||||
|
||||
- 添加原代码库为上游代码库
|
||||
```bash
|
||||
git remote add upstream git@github.com:open-mmlab/mmcv
|
||||
```
|
||||
+ 从第二个 PR 起
|
||||
- 检出本地代码库的主分支，然后从最新的原代码库的主分支拉取更新
|
||||
```bash
|
||||
git checkout master
|
||||
git pull upstream master
|
||||
```
|
||||
复刻 OpenMMLab 原代码库，点击 GitHub 页面右上角的 **Fork** 按钮即可
|
||||
|
||||
|
||||
克隆复刻的代码库到本地
|
||||
|
||||
```bash
|
||||
git clone git@github.com:XXX/mmcv.git
|
||||
```
|
||||
|
||||
添加原代码库为上游代码库
|
||||
|
||||
```bash
|
||||
git remote add upstream git@github.com:open-mmlab/mmcv
|
||||
```
|
||||
|
||||
+ 从第二个 PR 起
|
||||
|
||||
检出本地代码库的主分支，然后从最新的原代码库的主分支拉取更新
|
||||
|
||||
```bash
|
||||
git checkout master
|
||||
git pull upstream master
|
||||
```
|
||||
|
||||
#### 2. 从主分支创建一个新的开发分支
|
||||
|
||||
```bash
|
||||
git checkout -b branchname
|
||||
```
|
||||
|
||||
```{tip}
|
||||
为了保证提交历史清晰可读，我们强烈推荐您先检出主分支 (master)，再创建新的分支。
|
||||
```
|
||||
#### 3. 提交你的修改
|
||||
|
||||
```bash
|
||||
# coding
|
||||
git add [files]
|
||||
git commit -m 'messages'
|
||||
```
|
||||
|
||||
#### 4. 推送你的修改到复刻的代码库，并创建一个`拉取请求`
|
||||
|
||||
+ 推送当前分支到远端复刻的代码库
|
||||
|
||||
2. 从主分支创建一个新的开发分支
|
||||
```bash
|
||||
git checkout -b branchname
|
||||
```
|
||||
注意：为了保证提交历史清晰可读，我们强烈推荐您先检出主分支 (master)，再创建新的分支。
|
||||
|
||||
3. 提交你的修改
|
||||
```bash
|
||||
# coding
|
||||
git add [files]
|
||||
git commit -m 'messages'
|
||||
git push origin branchname
|
||||
```
|
||||
|
||||
4. 推送你的修改到复刻的代码库，并创建一个`拉取请求`
|
||||
+ 推送当前分支到远端复刻的代码库
|
||||
```bash
|
||||
git push origin branchname
|
||||
```
|
||||
+ 创建一个`拉取请求`
|
||||
|
||||
|
||||
+ 创建一个`拉取请求`
|
||||
|
||||
+ 修改`拉取请求`信息模板，描述修改原因和修改内容。还可以在 PR 描述中，手动关联到相关的`议题` (issue),（更多细节，请参考[官方文档](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue)）。
|
||||
|
||||
+ 修改`拉取请求`信息模板，描述修改原因和修改内容。还可以在 PR 描述中，手动关联到相关的`议题` (issue),（更多细节，请参考[官方文档](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue)）。
|
||||
#### 5. 讨论并评审你的代码
|
||||
|
||||
5. 讨论并评审你的代码
|
||||
+ 创建`拉取请求`时，可以关联给相关人员进行评审
|
||||
|
||||
+ 创建`拉取请求`时，可以关联给相关人员进行评审
|
||||
|
||||
|
||||
+ 根据评审人员的意见修改代码，并推送修改
|
||||
+ 根据评审人员的意见修改代码，并推送修改
|
||||
|
||||
#### 6. `拉取请求`合并之后删除该分支
|
||||
|
||||
6. `拉取请求`合并之后删除该分支
|
||||
```bash
|
||||
git branch -d branchname # delete local branch
|
||||
git push origin --delete branchname # delete remote branch
|
||||
|
|
@ -77,14 +94,20 @@ git push origin --delete branchname # delete remote branch
|
|||
### PR 规范
|
||||
|
||||
1. 使用 [pre-commit hook](https://pre-commit.com)，尽量减少代码风格相关问题
|
||||
2. 一个PR对应一个短期分支
|
||||
|
||||
2. 一个 PR 对应一个短期分支
|
||||
|
||||
3. 粒度要细，一个PR只做一件事情，避免超大的PR
|
||||
>- Bad:实现Faster R-CNN
|
||||
>- Acceptable:给 Faster R-CNN 添加一个 box head
|
||||
>- Good:给 box head 增加一个参数来支持自定义的 conv 层数
|
||||
|
||||
+ Bad：实现 Faster R-CNN
|
||||
+ Acceptable：给 Faster R-CNN 添加一个 box head
|
||||
+ Good：给 box head 增加一个参数来支持自定义的 conv 层数
|
||||
|
||||
4. 每次 Commit 时需要提供清晰且有意义 commit 信息
|
||||
|
||||
5. 提供清晰且有意义的`拉取请求`描述
|
||||
>- 标题写明白任务名称，一般格式:[Prefix] Short description of the pull request (Suffix)
|
||||
>- prefix: 新增功能 [Feature], 修 bug [Fix], 文档相关 [Docs], 开发中 [WIP] (暂时不会被review)
|
||||
>- 描述里介绍`拉取请求`的主要修改内容，结果，以及对其他部分的影响, 参考`拉取请求`模板
|
||||
>- 关联相关的`议题` (issue) 和其他`拉取请求`
|
||||
|
||||
+ 标题写明白任务名称，一般格式:[Prefix] Short description of the pull request (Suffix)
|
||||
+ prefix: 新增功能 [Feature], 修 bug [Fix], 文档相关 [Docs], 开发中 [WIP] (暂时不会被review)
|
||||
+ 描述里介绍`拉取请求`的主要修改内容，结果，以及对其他部分的影响, 参考`拉取请求`模板
|
||||
+ 关联相关的`议题` (issue) 和其他`拉取请求`
|
||||
|
|
|
|||
Loading…
Reference in New Issue