轻松创建拉取请求

! [ -e /content ] && pip install -Uqq fastai  # 在Colab上升级fastai

向fastai提交您的第一个拉取请求

exit # 别不小心运行了！

为了为fastai（或任何fast.ai库…或实际上大多数开源软件）做出贡献，您需要提交一个拉取请求，也称为PR。这是一个示例拉取请求。在这种情况下，您可以从描述中看到，这是修复库中一些错别字的内容。如果您点击该页面上的“更改的文件”，可以查看所有做出的更改。我们会在拉取请求到达时收到通知，检查更改是否看起来正常后，我们会“合并”它（这意味着我们在GitHub上点击一个按钮，所有这些更改将自动添加到仓库中）。

第一次提交拉取请求可能会感到有些压倒，因此我整理了这个指南来帮助您入门。我们将使用GitHub的命令行工具gh，这比通过网站操作要更快更方便（至少在我看来是如此！）。要在Linux上安装gh，请按照这里给出的说明进行操作。要在Mac上安装gh，请键入：brew install github/gh/gh。

在本指南中，我假设您正在使用Linux，并且已经设置了Anaconda或Miniconda。这是所有fast.ai课程指南中的默认设置，强烈推荐。它在Mac上也应该能正常工作，尽管我没有进行过测试。在Windows上，使用WSL中的Ubuntu。

本文档是从Jupyter Notebook创建的。您可以通过这里获取该笔记本并自行运行。您需要安装Jupyter Bash内核。

一次性设置

设置访问权限和 gh

要开发fastai，您需要安装fastai和nbdev（这也会检查您是否已经安装了最新版本）：

conda install -y -c fastai -c pytorch -c anaconda anaconda fastai nbdev
Collecting package metadata (current_repodata.json): done

注意: 如果您使用的是miniconda而不是Anaconda，请从上述命令中删除 -c anaconda anaconda。

nbdev 是一个真正的文学编程框架；请参阅这篇文章来了解为什么您应该考虑在下一个项目中使用它（以及我们为什么在 fastai 中使用它）。

如果您还没有设置 ssh 访问 GitHub，请先进行设置。可以按照这些步骤进行操作。一旦创建了 ssh 密钥（通常通过运行 ssh-keygen），您可以复制 .~/ssh/id_rsa.pub 文件的内容，并通过点击此页面上的“新 SSH 密钥”将其粘贴到 GitHub。

一旦这项工作正常，我们需要获取一个个人访问令牌，以允许 gh 连接到 GitHub。为此，点击这里，在“备注”部分输入“gh”，并勾选 repo、read:discussion 和 read:org 复选框（请注意，gh 可以自动为您执行此操作，但如果您在本地机器上运行代码则最为便利；大多数 fastai 开发者可能在使用远程 GPU 服务器，例如 Paperspace、AWS 或 GCP，因此我们展示下面的方法，因为它对每个人都有效）。

Personal access token screen

然后点击屏幕底部的“生成令牌”，并复制令牌（显示的一长串字母和数字）。您可以通过点击令牌旁边的小剪贴板图标轻松完成此操作。

Copying your token

现在在你的命令行中运行此命令，将 jph01 替换为你的 GitHub 用户名，并将 TOKEN= 后面的字符串替换为你复制的令牌：

GH_USER=jph01
TOKEN=abae9e225efcf319f41c68f3f4d7c2d92f59403e

设置 gh 使用 ssh 连接到 GitHub，这样你就不必每次都输入用户名和密码：

gh config set git_protocol ssh

创建你的 GitHub 认证文件：

echo -e "github.com:\n  user: $GH_USER\n  oauth_token: $TOKEN\n" > ~/.config/gh/hosts.yml

设置 fastcore

现在我们准备克隆 fastcore 和 fastai 库。我们建议同时克隆这两个库，因为您可能需要对 fastai 使用的 fastcore 库进行更改或调试。首先，我们将克隆 fastcore：

gh repo clone fastai/fastcore
Cloning into 'fastcore'...
remote: Enumerating objects: 247, done.
remote: Counting objects: 100% (247/247), done.
remote: Compressing objects: 100% (164/164), done.
remote: Total 1618 (delta 162), reused 139 (delta 78), pack-reused 1371
Receiving objects: 100% (1618/1618), 3.18 MiB | 18.61 MiB/s, done.
Resolving deltas: 100% (1102/1102), done.

我们将已安装的版本更新为使用可编辑模式。这意味着您在检出版本库中的代码所作的任何更改将自动在您计算机上使用该库的所有地方生效：

cd fastcore
pip install -qe .

我们更新了仓库以创建和使用一个 fork:

gh repo fork --remote
- Forking fastai/fastcore...
! jph01/fastcore already exists
✓ Renamed origin remote to upstream
✓ Added remote origin

因为所有fast.ai库都使用nbdev，我们需要在首次克隆仓库后运行nbdev_install_hooks；这确保了每当我们推送到GitHub时，我们的笔记本会自动被清理和信任：

nbdev_install_hooks 
Executing: git config --local include.path ../.gitconfig
Success: hooks are installed and repo's .gitconfig is now trusted

设置 fastai

现在我们将对 fastai 执行相同的步骤：

cd ..
gh repo clone fastai/fastai
cd fastai
Cloning into 'fastai'...
remote: Enumerating objects: 108, done.
remote: Counting objects: 100% (108/108), done.
remote: Compressing objects: 100% (79/79), done.
remote: Total 10206 (delta 41), reused 57 (delta 27), pack-reused 10098
Receiving objects: 100% (10206/10206), 536.85 MiB | 38.67 MiB/s, done.
Resolving deltas: 100% (8053/8053), done.
Already up to date.

我们也将对 fastai 进行可编辑安装：

pip install -qe .[dev]

…并为其分支并安装git钩子：

gh repo fork --remote
- Forking fastai/fastai...
! jph01/fastai already exists
✓ Renamed origin remote to upstream
✓ Added remote origin
nbdev_install_hooks 
Executing: git config --local include.path ../.gitconfig
Success: hooks are installed and repo's .gitconfig is now trusted

创建您的拉取请求

以上所有内容只需要执行一次。从这里开始是实际创建您的 PR 的命令。

通过运行以下命令创建一个新的 git 分支，将 test-pr 替换为您要给拉取请求起的名称（选择一个将来如果需要更新您的 PR 时容易记住的名称）：

git checkout -b test-pr
M   docs
Switched to a new branch 'test-pr'

在笔记本中进行任何您想要的更改，并记住在完成后运行 nbdev_build_lib 以确保库从您的笔记本更改中构建（除非您只更改了markdown，这种情况下不需要）。检查 git diff 的输出也是一个好主意，以确保您没有意外地进行了比预期更多的更改。

当您准备好时，commit 您的工作，在这里用您在提交中所做工作的清晰描述替换“仅仅测试”：

git commit -am "just testing"
[test-pr 3397cc9] just testing
 2 files changed, 2 insertions(+), 1 deletion(-)

第一次从你的 fork 推送时，你需要添加 -u origin HEAD，但在第一次之后，你只需使用 git push。

git push -u origin HEAD
Counting objects: 4, done.
Delta compression using up to 64 threads.
Compressing objects: 100% (4/4), done.
Writing objects: 100% (4/4), 383 bytes | 383.00 KiB/s, done.
Total 4 (delta 3), reused 0 (delta 0)
remote: Resolving deltas: 100% (3/3), completed with 3 local objects.
remote: 
remote: Create a pull request for 'test-pr' on GitHub by visiting:
remote:      https://github.com/jph01/fastai/pull/new/test-pr
remote: 
To github.com:jph01/fastai.git
 * [new branch]      HEAD -> test-pr
Branch 'test-pr' set up to track remote branch 'test-pr' from 'origin'.

现在您准备好创建您的 PR 了。要使用您的提交信息作为 PR 标题，请运行：

gh pr create -f
https://github.com/fastai/fastai/pull/2664

要交互式地提示您提供更多信息（包括打开您的编辑器以填写详细描述），只需运行 gh pr create 而不使用 -f 标志。如上所示，完成后，它将打印您新 PR 的 URL - 恭喜您，感谢您的贡献！

The completed pull request

PR后步骤

要保持您的分叉与主fastai仓库的更改同步，并将您的test-pr分支切换回主分支，请运行：

git pull upstream master
git checkout master
From github.com:fastai/fastai
 * branch            master     -> FETCH_HEAD
Already up to date.
M   docs
Switched to branch 'master'
Your branch is up to date with 'upstream/master'.

在未来，一旦您的PR被合并或拒绝，您可以删除您的分支，如果您不再需要它的话：

git branch -d test-pr
Deleted branch test-pr (was 514782a).
(base) 
: 1