mirror of https://github.com/open-mmlab/mmpose
208 lines
8.0 KiB
Markdown
208 lines
8.0 KiB
Markdown
# 如何给 MMPose 贡献代码
|
||
|
||
欢迎加入 MMPose 社区，我们致力于打造最前沿的计算机视觉基础库，我们欢迎任何形式的贡献，包括但不限于：
|
||
|
||
- **修复错误**
|
||
1. 如果提交的代码改动较大，我们鼓励你先开一个 issue 并正确描述现象、原因和复现方式，讨论后确认修复方案。
|
||
2. 修复错误并补充相应的单元测试，提交 PR 。
|
||
- **新增功能或组件**
|
||
1. 如果新功能或模块涉及较大的代码改动，我们建议先提交 issue，与我们确认功能的必要性。
|
||
2. 实现新增功能并添加单元测试，提交 PR 。
|
||
- **文档补充或翻译**
|
||
- 如果发现文档有错误或不完善的地方，欢迎直接提交 PR 。
|
||
|
||
```{note}
|
||
- 如果你希望向 MMPose 1.0 贡献代码，请从 dev-1.x 上创建新分支，并提交 PR 到 dev-1.x 分支上。
|
||
- 如果你是论文作者，并希望将你的方法加入到 MMPose 中，欢迎联系我们，我们将非常感谢你的贡献。
|
||
- 如果你希望尽快将你的项目分享到 MMPose 开源社区，欢迎将 PR 提到 Projects 目录下，该目录下的项目将简化 Review 流程并尽快合入。
|
||
- 如果你希望加入 MMPose 的维护者，欢迎联系我们，我们将邀请你加入 MMPose 的维护者群。
|
||
```
|
||
|
||
## 准备工作
|
||
|
||
PR 操作所使用的命令都是用 Git 去实现的，该章节将介绍如何进行 Git 配置与 GitHub 绑定。
|
||
|
||
### Git 配置
|
||
|
||
首先，你需要在本地安装 Git，然后配置你的 Git 用户名和邮箱：
|
||
|
||
```Shell
|
||
# 在命令提示符（cmd）或终端（terminal）中输入以下命令，查看 Git 版本
|
||
git --version
|
||
```
|
||
|
||
然后，你需要检查自己的 Git Config 是否正确配置，如果 `user.name` 和 `user.email` 为空，你需要配置你的 Git 用户名和邮箱：
|
||
|
||
```Shell
|
||
# 在命令提示符（cmd）或终端（terminal）中输入以下命令，查看 Git 配置
|
||
git config --global --list
|
||
# 设置 Git 用户名和邮箱
|
||
git config --global user.name "这里填入你的用户名"
|
||
git config --global user.email "这里填入你的邮箱"
|
||
```
|
||
|
||
## PR 流程
|
||
|
||
如果你对 PR 流程不熟悉，接下来将会从零开始，一步一步地教你如何提交 PR。如果你想深入了解 PR 开发模式，可以参考 [GitHub 官方文档](https://docs.github.com/cn/github/collaborating-with-issues-and-pull-requests/about-pull-requests)。
|
||
|
||
### 1. Fork 项目
|
||
|
||
当你第一次提交 PR 时，需要先 Fork 项目到自己的 GitHub 账号下。点击项目右上角的 Fork 按钮，将项目 Fork 到自己的 GitHub 账号下。
|
||
|
||
|
||
|
||
接着，你需要将你的 Fork 仓库 Clone 到本地，然后添加官方仓库作为远程仓库：
|
||
|
||
```Shell
|
||
|
||
# Clone 你的 Fork 仓库到本地
|
||
git clone https://github.com/username/mmpose.git
|
||
|
||
# 添加官方仓库作为远程仓库
|
||
cd mmpose
|
||
git remote add upstream https://github.com/open-mmlab/mmpose.git
|
||
```
|
||
|
||
在终端中输入以下命令，查看远程仓库是否成功添加：
|
||
|
||
```Shell
|
||
git remote -v
|
||
```
|
||
|
||
如果出现以下信息，说明你已经成功添加了远程仓库：
|
||
|
||
```Shell
|
||
origin https://github.com/{username}/mmpose.git (fetch)
|
||
origin https://github.com/{username}/mmpose.git (push)
|
||
upstream https://github.com/open-mmlab/mmpose.git (fetch)
|
||
upstream https://github.com/open-mmlab/mmpose.git (push)
|
||
```
|
||
|
||
```{note}
|
||
这里对 origin 和 upstream 进行一个简单的介绍，当我们使用 git clone 来克隆代码时，会默认创建一个 origin 的 remote，它指向我们克隆的代码库地址，而 upstream 则是我们自己添加的，用来指向原始代码库地址。当然如果你不喜欢他叫 upstream，也可以自己修改，比如叫 open-mmlab。我们通常向 origin 提交代码（即 fork 下来的远程仓库），然后向 upstream 提交一个 pull request。如果提交的代码和最新的代码发生冲突，再从 upstream 拉取最新的代码，和本地分支解决冲突，再提交到 origin。
|
||
```
|
||
|
||
### 2. 配置 pre-commit
|
||
|
||
在本地开发环境中，我们使用 pre-commit 来检查代码风格，以确保代码风格的统一。在提交代码前，你需要先安装 pre-commit：
|
||
|
||
```Shell
|
||
pip install -U pre-commit
|
||
|
||
# 在 mmpose 根目录下安装 pre-commit
|
||
pre-commit install
|
||
```
|
||
|
||
检查 pre-commit 是否配置成功，并安装 `.pre-commit-config.yaml` 中的钩子：
|
||
|
||
```Shell
|
||
pre-commit run --all-files
|
||
```
|
||
|
||
|
||
|
||
```{note}
|
||
如果你是中国大陆用户，由于网络原因，可能会出现 pre-commit 安装失败的情况。
|
||
|
||
这时你可以使用清华源来安装 pre-commit：
|
||
pip install -U pre-commit -i https://pypi.tuna.tsinghua.edu.cn/simple
|
||
|
||
或者使用国内镜像来安装 pre-commit：
|
||
pip install -U pre-commit -i https://pypi.mirrors.ustc.edu.cn/simple
|
||
```
|
||
|
||
如果安装过程被中断，可以重复执行上述命令，直到安装成功。
|
||
|
||
如果你提交的代码中有不符合规范的地方，pre-commit 会发出警告，并自动修复部分错误。
|
||
|
||
|
||
|
||
### 3. 创建开发分支
|
||
|
||
安装完 pre-commit 之后，我们需要基于 dev 分支创建一个新的开发分支，建议以 `username/pr_name` 的形式命名，例如：
|
||
|
||
```Shell
|
||
git checkout -b username/refactor_contributing_doc
|
||
```
|
||
|
||
在后续的开发中，如果本地仓库的 dev 分支落后于官方仓库的 dev 分支，需要先拉取 upstream 的 dev 分支，然后 rebase 到本地的开发分支上：
|
||
|
||
```Shell
|
||
git checkout username/refactor_contributing_doc
|
||
git fetch upstream
|
||
git rebase upstream/dev-1.x
|
||
```
|
||
|
||
在 rebase 时，如果出现冲突，需要手动解决冲突，然后执行 `git add` 命令，再执行 `git rebase --continue` 命令，直到 rebase 完成。
|
||
|
||
### 4. 提交代码并在本地通过单元测试
|
||
|
||
在本地开发完成后，我们需要在本地通过单元测试，然后提交代码。
|
||
|
||
```shell
|
||
# 运行单元测试
|
||
pytest tests/
|
||
|
||
# 提交代码
|
||
git add .
|
||
git commit -m "commit message"
|
||
```
|
||
|
||
### 5. 推送代码到远程仓库
|
||
|
||
在本地开发完成后，我们需要将代码推送到远程仓库。
|
||
|
||
```Shell
|
||
git push origin username/refactor_contributing_doc
|
||
```
|
||
|
||
### 6. 提交 Pull Request (PR)
|
||
|
||
#### (1) 在 GitHub 上创建 PR
|
||
|
||
|
||
|
||
#### (2) 在 PR 中根据指引修改描述，添加必要的信息
|
||
|
||
|
||
|
||
```{note}
|
||
- 在 PR branch 左侧选择 `dev` 分支，否则 PR 会被拒绝。
|
||
- 如果你是第一次向 OpenMMLab 提交 PR，需要签署 CLA。
|
||
```
|
||
|
||
|
||
|
||
## 代码风格
|
||
|
||
### Python
|
||
|
||
我们采用[PEP8](https://www.python.org/dev/peps/pep-0008/)作为代码风格。
|
||
|
||
使用下面的工具来对代码进行整理和格式化：
|
||
|
||
- [flake8](http://flake8.pycqa.org/en/latest/)：代码提示
|
||
- [isort](https://github.com/timothycrosley/isort)：import 排序
|
||
- [yapf](https://github.com/google/yapf)：格式化工具
|
||
- [codespell](https://github.com/codespell-project/codespell)： 单词拼写检查
|
||
- [mdformat](https://github.com/executablebooks/mdformat): markdown 文件格式化工具
|
||
- [docformatter](https://github.com/myint/docformatter): docstring 格式化工具
|
||
|
||
`yapf`和`isort`的样式配置可以在[setup.cfg](/setup.cfg)中找到。
|
||
|
||
我们使用[pre-commit hook](https://pre-commit.com/)来：
|
||
|
||
- 检查和格式化 `flake8`、`yapf`、`isort`、`trailing whitespaces`
|
||
- 修复 `end-of-files`
|
||
- 在每次提交时自动排序 `requirments.txt`
|
||
|
||
`pre-commit`的配置存储在[.pre-commit-config](/.pre-commit-config.yaml)中。
|
||
|
||
```{note}
|
||
在你创建PR之前，请确保你的代码格式符合规范，且经过了 yapf 格式化。
|
||
```
|
||
|
||
### C++与CUDA
|
||
|
||
遵循[Google C++风格指南](https://google.github.io/styleguide/cppguide.html)
|