mirror of https://github.com/open-mmlab/mmocr.git
[Docs] Add contribution guides (#1442)
* temp * en contribution ready * finalize * fix * updatepull/1454/head
Tong Gao
gaotongxiao
parent
ec395c5c68
commit
f619c697a5
|
|
@ -1,203 +1 @@
|
|||
# Contributing to MMOCR
|
||||
|
||||
All kinds of contributions are welcome, including but not limited to the following.
|
||||
|
||||
- Fixes (typo, bugs)
|
||||
- New features and components
|
||||
|
||||
Contents
|
||||
|
||||
- [Contributing to MMOCR](#contributing-to-mmocr)
|
||||
- [Workflow](#workflow)
|
||||
- [Main Steps](#main-steps)
|
||||
- [Detailed Steps](#detailed-steps)
|
||||
- [Step 1: Create a Fork](#step-1-create-a-fork)
|
||||
- [Step 2: Develop a new feature](#step-2-develop-a-new-feature)
|
||||
- [Step 2.1: Keep your fork up to date](#step-21-keep-your-fork-up-to-date)
|
||||
- [Step 2.2: Create a feature branch](#step-22-create-a-feature-branch)
|
||||
- [Step 3: Commit your changes](#step-3-commit-your-changes)
|
||||
- [Step 4: Prepare to Pull Request](#step-4-prepare-to-pull-request)
|
||||
- [Step 4.1: Merge official repo updates to your fork](#step-41-merge-official-repo-updates-to-your-fork)
|
||||
- [Step 4.2: Push \<your_feature_branch> branch to your remote forked repo,](#step-42-push-your_feature_branch-branch-to-your-remote-forked-repo)
|
||||
- [Step 4.3: Create a Pull Request](#step-43-create-a-pull-request)
|
||||
- [Step 4.4: Review code](#step-44-review-code)
|
||||
- [Step 4.5: Revise \<your_feature_branch> (optional)](#step-45-revise-your_feature_branch--optional)
|
||||
- [Step 4.6: Delete \<your_feature_branch> branch if your PR is accepted.](#step-46-delete-your_feature_branch-branch-if-your-pr-is-accepted)
|
||||
- [Code style](#code-style)
|
||||
- [Python](#python)
|
||||
- [Installing pre-commit hooks](#installing-pre-commit-hooks)
|
||||
- [C++ and CUDA](#c-and-cuda)
|
||||
|
||||
## Workflow
|
||||
|
||||
### Main Steps
|
||||
|
||||
1. Fork and pull the latest MMOCR
|
||||
2. Checkout a new branch (do not use main branch for PRs)
|
||||
3. Commit your changes
|
||||
4. Create a PR
|
||||
|
||||
**Note**
|
||||
|
||||
- If you plan to add some new features that involve large changes, it is encouraged to open an issue for discussion first.
|
||||
- If you are the author of some papers and would like to include your method to MMOCR, please let us know (open an issue or contact the maintainers). We will much appreciate your contribution.
|
||||
- For new features and new modules, unit tests are required to improve the code's robustness.
|
||||
|
||||
### Detailed Steps
|
||||
|
||||
The official public [repository](https://github.com/open-mmlab/mmocr) holds only one branch with an infinite lifetime: *main*
|
||||
|
||||
The *main* branch is the main branch where the source code of **HEAD** always reflects a state with the latest development changes for the next release.
|
||||
|
||||
Feature branches are used to develop new features for the upcoming or a distant future release.
|
||||
|
||||
All new developers to **MMOCR** need to follow the following steps:
|
||||
|
||||
#### Step 1: Create a Fork
|
||||
|
||||
1. Fork the repo on GitHub or GitLab to your personal account. Click the `Fork` button on the [project page](https://github.com/open-mmlab/mmocr).
|
||||
|
||||
2. Clone your new forked repo to your computer.
|
||||
|
||||
```
|
||||
git clone https://github.com/<your name>/mmocr.git
|
||||
```
|
||||
|
||||
3. Add the official repo as an upstream:
|
||||
|
||||
```
|
||||
git remote add upstream https://github.com/open-mmlab/mmocr.git
|
||||
```
|
||||
|
||||
#### Step 2: Develop a new feature
|
||||
|
||||
##### Step 2.1: Keep your fork up to date
|
||||
|
||||
Whenever you want to update your fork with the latest upstream changes, you need to fetch the upstream repo's branches and latest commits to bring them into your repository:
|
||||
|
||||
```
|
||||
# Fetch from upstream remote
|
||||
git fetch upstream
|
||||
|
||||
# Update your main branch
|
||||
git checkout main
|
||||
git rebase upstream/main
|
||||
git push origin main
|
||||
```
|
||||
|
||||
##### Step 2.2: Create a feature branch
|
||||
|
||||
- Create an issue on [github](https://github.com/open-mmlab/mmocr)
|
||||
|
||||
- Create a feature branch
|
||||
|
||||
```bash
|
||||
git checkout -b feature/iss_<index> main
|
||||
# index is the issue index on github above
|
||||
```
|
||||
|
||||
#### Step 3: Commit your changes
|
||||
|
||||
Develop your new feature and test it to make sure it works well, then commit.
|
||||
|
||||
If you have not configured pre-commit hooks for MMOCR, please [install pre-commit hooks](#installing-pre-commit-hooks) before your first commit.
|
||||
|
||||
The commit message is suggested to be clear. Here is an example:
|
||||
|
||||
```bash
|
||||
git commit -m "fix #<issue_index>: <commit_message>"
|
||||
```
|
||||
|
||||
#### Step 4: Prepare to Pull Request
|
||||
|
||||
- Before creating an PR, please run
|
||||
|
||||
```bash
|
||||
pre-commit run --all-files
|
||||
pytest tests
|
||||
```
|
||||
|
||||
and fix all failures.
|
||||
|
||||
- Make sure to link your pull request to the related issue. Please refer to the [instructon](https://docs.github.com/en/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue)
|
||||
|
||||
##### Step 4.1: Merge official repo updates to your fork
|
||||
|
||||
```
|
||||
# fetch from upstream remote. i.e., the official repo
|
||||
git fetch upstream
|
||||
|
||||
# update the main branch of your fork
|
||||
git checkout main
|
||||
git rebase upstream/main
|
||||
git push origin main
|
||||
|
||||
# update the <your_feature_branch> branch
|
||||
git checkout <your_feature_branch>
|
||||
git rebase main
|
||||
# solve conflicts if any and Test
|
||||
```
|
||||
|
||||
##### Step 4.2: Push \<your_feature_branch> branch to your remote forked repo,
|
||||
|
||||
```
|
||||
git checkout <your_feature_branch>
|
||||
git push origin <your_feature_branch>
|
||||
```
|
||||
|
||||
##### Step 4.3: Create a Pull Request
|
||||
|
||||
Go to the page for your fork on GitHub, select your new feature branch, and click the pull request button to integrate your feature branch into the upstream remote’s develop branch.
|
||||
|
||||
##### Step 4.4: Review code
|
||||
|
||||
##### Step 4.5: Revise \<your_feature_branch> (optional)
|
||||
|
||||
If PR is not accepted, pls follow steps above till your PR is accepted.
|
||||
|
||||
##### Step 4.6: Delete \<your_feature_branch> branch if your PR is accepted.
|
||||
|
||||
```
|
||||
git branch -d <your_feature_branch>
|
||||
git push origin :<your_feature_branch>
|
||||
```
|
||||
|
||||
## Code style
|
||||
|
||||
### Python
|
||||
|
||||
We adopt [PEP8](https://www.python.org/dev/peps/pep-0008/) as the preferred code style.
|
||||
|
||||
We use the following tools for linting and formatting:
|
||||
|
||||
- [flake8](http://flake8.pycqa.org/en/latest/): linter
|
||||
- [yapf](https://github.com/google/yapf): formatter
|
||||
- [isort](https://github.com/timothycrosley/isort): sort imports
|
||||
|
||||
Style configurations of yapf and isort can be found in [setup.cfg](../setup.cfg).
|
||||
|
||||
We use [pre-commit hook](https://pre-commit.com/) that checks and formats for `flake8`, `yapf`, `isort`, `trailing whitespaces`,
|
||||
fixes `end-of-files`, sorts `requirments.txt` automatically on every commit.
|
||||
The config for a pre-commit hook is stored in [.pre-commit-config](../.pre-commit-config.yaml).
|
||||
|
||||
#### Installing pre-commit hooks
|
||||
|
||||
After you clone the repository, you will need to install and initialize pre-commit hook.
|
||||
|
||||
```shell
|
||||
pip install -U pre-commit
|
||||
```
|
||||
|
||||
From the repository folder
|
||||
|
||||
```shell
|
||||
pre-commit install
|
||||
```
|
||||
|
||||
After this on every commit check code linters and formatter will be enforced.
|
||||
|
||||
> Before you create a PR, make sure that your code lints and is formatted by yapf.
|
||||
|
||||
### C++ and CUDA
|
||||
|
||||
We follow the [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html).
|
||||
We appreciate all contributions to improve MMOCR. Please read [Contribution Guide](/docs/en/notes/contribution_guide.md) for step-by-step instructions to make a contribution to MMOCR, and [CONTRIBUTING.md](https://github.com/open-mmlab/mmcv/blob/master/CONTRIBUTING.md) in MMCV for more details about the contributing guideline.
|
||||
|
|
|
|||
|
|
@ -1 +1,134 @@
|
|||
# Contribution Guide
|
||||
|
||||
OpenMMLab welcomes everyone who is interested in contributing to our projects and accepts contribution in the form of PR.
|
||||
|
||||
## What is PR
|
||||
|
||||
`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 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
|
||||
|
||||
1. Get the most recent codebase
|
||||
2. Checkout a new branch from `main` or `dev-1.x` branch, depending on the version of the codebase you want to contribute to (see [Maintenance Plan](../migration/overview.md) for more details)
|
||||
3. Commit your changes ([Don't forget to use pre-commit hooks!](#3-commit-your-changes))
|
||||
4. Push your changes and create a PR
|
||||
5. Discuss and review your code
|
||||
6. Merge your branch to `main` or `dev-1.x` branch
|
||||
|
||||
## 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
|
||||
|
||||
|
||||
Clone forked repository to local
|
||||
|
||||
```bash
|
||||
git clone git@github.com:XXX/mmocr.git
|
||||
```
|
||||
|
||||
Add source repository to upstream
|
||||
|
||||
```bash
|
||||
git remote add upstream git@github.com:open-mmlab/mmocr
|
||||
```
|
||||
|
||||
- After your first PR
|
||||
|
||||
Checkout the latest branch of the local repository and pull the latest branch of the source repository. Here we assume that you are working on the `dev-1.x` branch.
|
||||
|
||||
```bash
|
||||
git checkout dev-1.x
|
||||
git pull upstream dev-1.x
|
||||
```
|
||||
|
||||
### 2. Checkout a new branch from the `main` branch or `dev-1.x` branch
|
||||
|
||||
```bash
|
||||
git checkout -b branchname
|
||||
```
|
||||
|
||||
```{tip}
|
||||
To make commit history clear, we strongly recommend you checkout the `main` or `dev-1.x` branch before creating a new branch.
|
||||
```
|
||||
|
||||
### 3. Commit your changes
|
||||
|
||||
- If you are a first-time contributor, please install and initialize pre-commit hooks from the repository root directory first.
|
||||
|
||||
```bash
|
||||
pip install -U pre-commit
|
||||
pre-commit install
|
||||
```
|
||||
|
||||
- Commit your changes as usual. Pre-commit hooks will be triggered to stylize your code before each commit.
|
||||
|
||||
```bash
|
||||
# coding
|
||||
git add [files]
|
||||
git commit -m 'messages'
|
||||
```
|
||||
|
||||
```{note}
|
||||
Sometimes your code may be changed by pre-commit hooks. In this case, please remember to re-stage the modified files and commit again.
|
||||
```
|
||||
|
||||
### 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
|
||||
|
||||
|
||||
- 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)).
|
||||
|
||||
- Specifically, if you are contributing to `dev-1.x`, you will have to change the base branch of the PR to `dev-1.x` in the PR page, since the default base branch is `main`.
|
||||
|
||||
|
||||
|
||||
- You can also ask a specific person to review the changes you've proposed.
|
||||
|
||||
### 5. Discuss and review your code
|
||||
|
||||
- Modify your codes according to reviewers' suggestions and then push your changes.
|
||||
|
||||
### 6. Merge your branch to the `main` / `dev-1.x` branch and delete the branch
|
||||
|
||||
- After the PR is merged by the maintainer, you can delete the branch you created in your forked repository.
|
||||
|
||||
```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
|
||||
|
||||
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
|
||||
|
|
|
|||
|
|
@ -1 +1,134 @@
|
|||
# 贡献指南
|
||||
|
||||
OpenMMLab 欢迎所有人参与我们项目的共建。本文档将指导您如何通过拉取请求为 OpenMMLab 项目作出贡献。
|
||||
|
||||
## 什么是拉取请求？
|
||||
|
||||
`拉取请求` (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. 根据你打算贡献的版本，从最新的 `main` 或 `dev-1.x` 分支创建分支进行开发（可以阅读我们的[维护计划](../migration/overview.md)以获知详情）
|
||||
3. 提交修改 ([不要忘记使用 pre-commit hooks!](#))
|
||||
4. 推送你的修改并创建一个 `拉取请求`
|
||||
5. 讨论、审核代码
|
||||
6. 将开发分支合并到 `main` 或 `dev-1.x` 分支
|
||||
|
||||
## 具体步骤
|
||||
|
||||
### 1. 获取最新的代码库
|
||||
|
||||
- 当你第一次提 PR 时
|
||||
|
||||
复刻 OpenMMLab 原代码库，点击 GitHub 页面右上角的 **Fork** 按钮即可
|
||||
|
||||
|
||||
克隆复刻的代码库到本地
|
||||
|
||||
```bash
|
||||
git clone git@github.com:XXX/mmocr.git
|
||||
```
|
||||
|
||||
添加原代码库为上游代码库
|
||||
|
||||
```bash
|
||||
git remote add upstream git@github.com:open-mmlab/mmocr
|
||||
```
|
||||
|
||||
- 从第二个 PR 起
|
||||
|
||||
检出本地代码库的主分支，然后从最新的原代码库的主分支拉取更新。这里假设你正基于 `dev-1.x` 开发。
|
||||
|
||||
```bash
|
||||
git checkout dev-1.x
|
||||
git pull upstream dev-1.x
|
||||
```
|
||||
|
||||
### 2. 从 `main` 或 `dev-1.x` 分支创建一个新的开发分支
|
||||
|
||||
```bash
|
||||
git checkout -b branchname
|
||||
```
|
||||
|
||||
```{tip}
|
||||
为了保证提交历史清晰可读，我们强烈推荐您先切换到 `main` 或 `dev-1.x` 分支，再创建新的分支。
|
||||
```
|
||||
|
||||
### 3. 提交你的修改
|
||||
|
||||
- 如果你是第一次尝试贡献，请在 MMOCR 的目录下安装并初始化 pre-commit hooks。
|
||||
|
||||
```bash
|
||||
pip install -U pre-commit
|
||||
pre-commit install
|
||||
```
|
||||
|
||||
- 提交修改。在每次提交前，pre-commit hooks 都会被触发并规范化你的代码格式。
|
||||
|
||||
```bash
|
||||
# coding
|
||||
git add [files]
|
||||
git commit -m 'messages'
|
||||
```
|
||||
|
||||
```{note}
|
||||
有时你的文件可能会在提交时被 pre-commit hooks 自动修改。这时请重新添加并提交修改后的文件。
|
||||
```
|
||||
|
||||
### 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)）。
|
||||
|
||||
- 另外，如果你正在往 `dev-1.x` 分支提交代码，你还需要在创建 PR 的界面中将基础分支改为 \`\`dev-1.x`，因为现在默认的基础分支是 `main\`。
|
||||
|
||||
|
||||
|
||||
- 你同样可以把 PR 关联给相关人员进行评审。
|
||||
|
||||
### 5. 讨论并评审你的代码
|
||||
|
||||
- 根据评审人员的意见修改代码，并推送修改
|
||||
|
||||
### 6. `拉取请求`合并之后删除该分支
|
||||
|
||||
- 在 PR 合并之后，你就可以删除该分支了。
|
||||
|
||||
```bash
|
||||
git branch -d branchname # 删除本地分支
|
||||
git push origin --delete branchname # 删除远程分支
|
||||
```
|
||||
|
||||
## PR 规范
|
||||
|
||||
1. 使用 [pre-commit hook](https://pre-commit.com)，尽量减少代码风格相关问题
|
||||
|
||||
2. 一个 PR 对应一个短期分支
|
||||
|
||||
3. 粒度要细，一个PR只做一件事情，避免超大的PR
|
||||
|
||||
- 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) 和其他`拉取请求`
|
||||
|
|
|
|||
Loading…
Reference in New Issue