贡献 GluonCV¶

GluonCV 社区非常欢迎大家的贡献！最新文档可在 GluonCV 网站上找到。

有很多机会可以成为我们的贡献者

在 GitHub issues 上提问或回答问题。
在 GitHub issues 上提出想法或评审设计提案。
改进文档。
在 GitHub issues 上贡献 bug 报告。
编写新脚本来复现当前最优 (state-of-the-art) 结果。
编写新教程。
编写新的公共数据集接口。
提交新的计算机视觉算法。
最重要的是，如果你有贡献的想法，那就去做吧！

有关开放的入门任务列表，请查看 good first issues。

操作指南¶

进行更改
贡献脚本
贡献教程
贡献文档
贡献新的计算机视觉算法
贡献新的 API
Git 工作流操作指南

进行更改¶

我们的软件包使用持续集成和代码覆盖率工具来验证 pull request。在提交之前，贡献者应该进行以下检查

代码风格 (Lint) 检查.
Py2 和 Py3 测试。

贡献脚本¶

GluonCV 中的脚本通常用于复现当前最优 (SOTA) 结果，或用于简单有趣的应用程序。它们面向熟悉这些库、希望进行调整和修改的实践者。对于 SOTA 脚本，我们通常要求将训练脚本上传到这里，然后链接到示例文档中。

查看现有示例。

贡献教程¶

我们的网站教程面向对计算机视觉 (CV) 感兴趣并希望更好地了解 CV 各个部分的人。为了让人们更容易理解内容，代码需要清晰易读，并配有高质量的写作。

查看可用的现有示例。

贡献新的 API¶

API 有几种不同的类型，例如 *模型定义 API、公共数据集 API 和构建块 API*。

模型定义 API 便于共享预训练模型。如果你想贡献带有预训练权重的模型，可以先开一个 issue 并 ping 提交者，在我们帮助托管模型权重时，你可以提交补丁。

公共数据集 API 便于共享公共数据集。与模型定义 API 类似，如果你想贡献新的公共数据集，可以开一个 issue 并 ping 提交者，然后评审数据集需求。如果你不确定，也请随意开一个 issue。

最后，我们的 *数据和模型构建块 API* 源自示例中的重复模式。它们具有最高的质量标准，并且应始终从良好的设计开始。如果你有提出新 API 的想法，我们鼓励你先起草一份设计提案，以便社区可以帮助迭代。一旦设计最终确定，所有有兴趣实现它的人都可以通过提交补丁来提供帮助。对于需要更大范围的设计，我们可以帮助建立 GitHub 项目，以便其他人更容易加入。

贡献文档¶

文档与代码同等重要。好的文档清晰简洁地传达正确的信息。如果你在现有文档中发现任何问题，非常欢迎提交补丁来修复！要定位负责该文档的代码，你可以使用右上角的“查看页面源代码”或每个 API 后面的“[source]”链接。此外，如果存在唯一的字符串，“[git grep]”也很好用。

贡献新的计算机视觉算法¶

GluonCV 官方支持的算法包含以下五个组件

模型定义。模型使用 mxnet.gluon.HybridBlock 或 mxnet.gluon.Block 编写。你可以从实现著名的 `resnet <https://github.com/dmlc/gluon-cv/blob/estimator/gluoncv/model_zoo/resnetv1b.py`_ 模型开始获得更好的想法。除了基本的 ResNetV1b 类定义之外，我们也鼓励使用名称定义单个网络，以便轻松使用特定的模型变体。例如：def resnet18_v1b
配套的数据集、预处理函数、数据增强、评估指标、损失函数。只有在现有库中找不到合适的时，你才需要实现它们。
- 数据集定义
- 数据转换
- 特定算法的数据转换预设
- 可重用的神经网络组件
- utils：你觉得不适合放在其他主要组件中的任何东西
Python 脚本。scripts 文件夹包含训练/评估/演示 Python 脚本，人们可以试用和修改。你也可以在开发中使用这些脚本来训练/评估模型。
预训练权重：通过哈希码组织，预训练权重托管在 S3 存储桶上，供所有用户直接使用模型。显然，不要丢弃你训练和评估过的最佳 params 文件，在 PR 中与我们分享，组织者可以帮助上传权重，让新算法更容易被接受！
文档。通过将分数添加到模型库网站的表格中，让更多人了解你的新算法。贡献关于推理/训练的教程肯定能降低用户采用新模型的学习曲线。

关于 GluonCV 中的混合/非混合模型¶

GluonCV 建议 GluonCV 内置算法使用网络的混合版本（混合网络的上下文）。全混合网络的优点是可以在 Python 生态系统之外轻松部署。全混合网络的主要限制是在网络内部访问张量形状的使用受限。shape_array 操作符在许多情况下使用，尽管它不能与普通的 .shape 属性完全互换。别担心，我们正在解决这个问题，对于全混合网络不适用的情况，请随时与现有贡献者和提交者讨论。

Git 工作流操作指南¶

如何提交 pull request¶

提交之前，请将你的代码 rebase 到 master 的最新版本，你可以通过以下方式完成

git remote add upstream https://github.com/dmlc/gluon-cv
git fetch upstream
git rebase upstream/master

如果你有多个小的 commit，最好将它们合并（使用 git rebase 然后 squash）成更有意义的组。
发送 pull request！- 修复自动检查报告的问题 - 如果你贡献了新模块或新函数，请添加测试。

如何解决与 master 分支的冲突¶

首先 rebase 到最新的 master 分支

# The first two steps can be skipped after you do it once.
git remote add upstream https://github.com/dmlc/gluon-cv
git fetch upstream
git rebase upstream/master

git 可能会显示一些无法合并的冲突，例如 conflicted.py。
- 手动修改文件以解决冲突。
- 解决冲突后，通过以下方式将其标记为已解决
```
git add conflicted.py
```
然后你可以继续 rebase
```
git rebase --continue
```
最后推送到你的 fork，这里可能需要强制推送 (force push)。
```
git push --force
```

如何将多个 commit 合并为一个¶

有时我们想合并多个 commit，特别是当后续 commit 只是对之前 commit 的修复时，以便创建一个包含一组有意义 commit 的 PR。你可以按照以下步骤进行。- 在此之前，如果尚未配置过 git 的默认编辑器，请先进行配置。

git config core.editor the-editor-you-like

假设我们要合并最后 3 个 commit，输入以下命令
```
git rebase -i HEAD~3
```
它将弹出一个文本编辑器。将第一个 commit 设置为 pick，并将后面的 commit 更改为 squash。
保存文件后，会弹出另一个文本编辑器，要求你修改合并后的 commit 消息。
将更改推送到你的 fork，你需要强制推送 (force push)。
```
git push --force
```

重置到最新的 master 分支¶

你随时可以使用 git reset 将你的版本重置到最新的 master 分支。请注意，你所有的 *本地更改都将丢失*。因此，仅在你没有本地更改或你的 pull request 刚被合并时才这样做。

git reset --hard [hash tag of master]
git push --force

强制推送 (force push) 的后果是什么¶

前两个技巧需要强制推送，这是因为我们改变了 commit 的路径。强制推送到你自己的 fork 是可以的，只要更改的 commit 只属于你。