如何提交

第一步是 Fork LabEx 的仓库到自己的账号下（创建副本），原因是你对 LabEx 的仓库没有直接的编辑权限。

然后克隆你 Fork 后的仓库（不是 LabEx 的仓库）到本地计算机。

1. 打开终端；
2. 切换到仓库目录下；
3. 使用下面命令创建属于你自己的新分支:

git checkout -b <branch-name>

替换 <branch-name> 名称，例如:

git checkout -b add-lab-hello-world

分支名称尽量有意义一些，这样下次你再看的时候就知道这个分支是干什么的。养成良好的习惯，可以让你的工作更加高效。

在本地仓库中，你可以使用任何你喜欢的编辑器来编辑文件。我们推荐使用 Visual Studio Code。详见 工具推荐。

新增或修改完内容后，你就可以准备提交了。

1. 打开终端；
2. 切换到仓库目录下；
3. 使用下面命令添加你要提交的文件:

git add <file-name>

替换 <file-name> 为你要提交的文件名，例如:

git add python/add-lab-hello-world/step1.md

如果你想要提交所有文件，可以使用下面命令:

git add .

4. 使用下面命令提交你的更改:

git commit -m "<commit-message>"

替换 <commit-message> 为你的提交信息，例如:

git commit -m "Add lab-hello-world"

关于 <commit-message> 的编写规范，可以参考 Semantic Commit Messages

5. 使用下面命令把你的更改推送到 GitHub:

git push origin <branch-name>

替换 <branch-name> 为你的分支名称，例如:

git push origin add-lab-hello-world

在 GitHub 上打开你的仓库。点击 Contribute → Open pull requests。

重新命名 PR，名称取得有意义一些，养成良好习惯。

请注意，请仔细确认两个分支的对比，确保你的修改是正确的。其中：

• 前面的 base 分支是 LabEx 的仓库的 master 分支，不是你自己仓库的 master 分支。因为你要向 LabEx 的仓库提交修改，所以你需要把你的修改与 LabEx 的仓库的 master 分支进行对比。
• 后面的 compare 分支是你自己仓库的分支，例如刚刚创建的 add-lab-hello-world。

然后，点击 Create pull request，一个 PR 就创建好了。

当你创建好 PR 后，你需要阅读 PR 中的要求，按照要求补充必要的信息。后续等你熟悉流程之后，你也可以直接在上一步，创建过程中，补充完善这些必要的信息。

如果一切正常，我们的自动化工作流会自动捕获你的 PR，基于你提交内容的 index.json 配置文件生成一个临时的在线测试环境，并将链接以评论的形式添加到 PR 中。

请注意查看 PR 中的评论，点击链接，进入在线测试环境，测试你的修改是否正确。

如果你的内容存在格式错误（尤其是 index.json 配置错误），可能会导致同步失败，你会看到 Error in PR synchronization! 的提示。

请仔细阅读错误提示，根据提示修改你的内容。

例如上方的提示中能看出来，index.json 中的 description 字段是必填的，所以你需要在 index.json 中添加。

提交新的更改后，会自动触发重新同步。

然后，你需要严格按照 如何测试 的指引在 LabEx 的在线测试环境中测试你的提交是否正确。

测试完成之后，请按照 PR 中的要求，补充和完善必要的信息，并添加 Test Completed 的 Label，标记你的测试已经完成。

一般情况下，当你添加完 Test Completed 的 Label 后，我们的自动化工作流会对你的 PR 进行基础格式预检查。

1. 如果你的 PR 通过了预检查，你会收到相应的评论提醒。
2. 如果你的 PR 没有通过预检查，理论上也会收到相应的评论提醒，请按照评论中的要求，对内容进行修订和确认。

一条预检查的评论示例如上图所示。问题大致分为两类：

1. 建议修订的问题：这类问题大概率不符合本手册的要求，需要你按照评论中的提示，对内容进行修订提交。如果你确信没有问题，可以在评论中说明，我们会在人工 Review 中再次确认。
2. 需要确认的问题：这类问题可能是自动化工作流的一些限制，无法准确判断，需要你再次确认一下。如果你确认没有问题，可以忽略这类问题。

当你修订和确认完成后，请按照预检查消息中的提示，选择任意表情符号进行标记确认你已经处理了这些问题。同时，需要重新添加 Test Completed 的 Label，标记你的测试已经完成。

如果你的预检查仍然存在问题，会继续收到相应的评论提醒，请按照评论中的提示进行操作。如果有任何疑问，请联系我们。

当你的 PR 预检查通过后，我们的自动化工作流会给你的 PR 分配合适的 Reviewer，你会收到相应的评论提醒。示例如下：

请耐心等待 Reviewer 的 Review。

如果你的 PR 被 Reviewer 指出了问题，你需要按照 Reviewer 的要求，进行相应的修改，然后再次提交。

关于如何进行修订提交，详见 修订提交。

如果你的 PR 没有问题，我们会合并你的 PR 到 LabEx 的仓库中。一个 lab/challenge 就完成了。

下方的图片总结了整个流程：

完成一个 lab/challenge 后，你可以继续提交下一个 lab/challenge。

首先，请点击自己仓库的 Sync Fork 来同步我们的仓库的最新内容，这样可以保证你的仓库是最新的，避免后续潜在的冲突。

然后基于同步后的仓库，回到步骤 2，创建新分支，然后继续编辑内容，提交更改，创建 PR，等待 Review。开始新的循环。