§使用 Git

本指南旨在帮助新贡献者开始使用 Play。这里提到的某些内容是我们认为好的约定，可以使对 Play 的贡献更容易，但它们当然不是强制性的，您应该使用最适合您的方法。

§Git 远程仓库

我们建议将官方 Play 仓库的远程仓库命名为 origin，将您 fork 的远程仓库命名为您的用户名。这种约定在多个 fork 之间共享代码时非常有效，也是我们在本指南中所有剩余 git 命令中使用的约定。它也是与 GitHub 命令行工具开箱即用最有效的约定。

§分支

通常，所有工作都应该在分支中完成。如果您直接在 main 分支上工作，那么您一次只能提交一个 pull request，因为如果您尝试从 main 分支提交第二个 pull request，第二个 pull request 将包含您第一个和第二个 pull request 的提交。在分支中工作可以让您将 pull request 相互隔离。

您可以根据自己的喜好命名分支，有些人喜欢在分支名称中包含问题编号，有些人喜欢使用分层结构。

§压缩提交

我们更希望所有 pull request 都是单个提交。这样做有几个原因

将单个提交回移植到稳定分支比回移植一组提交更容易，也更不容易出错。如果更改只在一个提交中，那么就不会出现错误，要么整个更改被 cherry-pick，要么没有。
我们的目标是让我们的 main 分支始终可发布，不仅是现在，而且对于所有历史记录中的点也是如此。如果我们需要回滚某些内容，我们希望确信之前的提交是稳定的。
当更改在一个提交中自包含时，更容易了解历史记录中发生了什么。

当然，在某些情况下，压缩提交是不合适的，这将根据具体情况决定，但我们不会要求压缩提交的示例包括

当 pull request 包含多个人的提交时。在这种情况下，我们更希望，在有意义的情况下，压缩同一个人的连续提交。
当拉取请求来自一个在社区中共享的分支或 fork，并且重写历史记录会导致从该分支或 fork 中拉取更改的人员出现问题时。
当拉取请求包含大量工作，并且提交日志有助于理解该工作的演变过程时。

但是，对于一般情况，如果您的拉取请求包含多个提交，则需要将它们压缩。要执行此操作，或者如果您已经提交了拉取请求，而我们要求您压缩它，则应按照以下步骤操作

确保您的仓库中包含来自核心主分支的所有更改
```
git fetch origin
```
开始交互式变基
```
git rebase -i origin/main
```
这将在您的编辑器中打开一个屏幕，允许您指定对每个提交应该执行的操作。如果第一个提交的提交消息适合描述所有提交，则保留原样，否则，将它的命令从 pick 更改为 reword。
对于每个剩余的提交，将命令从 pick 更改为 fixup。这告诉 git 将该提交合并到上一个提交中，使用上一个提交的提交消息。
保存文件并退出编辑器。Git 现在将开始变基。如果您告诉它重新编写第一个提交，它将在一个新的编辑器中提示您输入该提交的措辞。如果一切顺利，您就完成了，但可能在将您的更改应用于最新的主分支时存在冲突。如果是这种情况，请解决冲突，暂存修复，然后运行
```
git rebase --continue
```
如果还有更多更改存在冲突，可能需要重复此操作。
现在您已经变基，可以推送您的更改。如果您之前已经推送过此分支（包括您已经创建了拉取请求），则需要执行强制推送。这可以通过以下方式完成
```
git push yourremote yourbranch --force
```

§响应审查/构建中断

如果您的拉取请求没有通过 CI 构建，如果我们审查它并要求您更新您的拉取请求，或者出于任何其他原因您想要更新您的拉取请求，那么与其创建新的提交，不如修改现有的提交。这可以通过在提交时提供 --amend 标志来完成

git commit --amend

完成修改后，您需要使用 --force 标志执行强制推送

git push yourremote yourbranch --force

§重新开始

有时人们会发现他们完全弄错了自己的拉取请求，并且想要重新开始。这很好，但是没有必要关闭原始的拉取请求并打开一个新的。您可以使用强制推送将一个全新的分支推送到拉取请求中。

要重新开始，请确保您拥有来自 Play core 的最新更改，并从该点创建一个新分支

git fetch origin
git checkout -b mynewbranch origin/main

现在进行您的更改，然后当您准备提交拉取请求时，假设您的旧分支名为 myoldbranch，将您的新分支推送到您仓库中的该旧分支

git push yourremote mynewbranch:myoldbranch --force

现在拉取请求应该用您的新分支更新。

§关于修改历史记录

您可能听说过，在发布 Git 历史记录后不应该修改它。使用 `rebase` 和 `commit --amend` 都会修改历史记录，而使用 `push --force` 会发布您修改后的历史记录。

在某些情况下，发布后确实不应该修改 Git 历史记录。主要是在其他人可能已经 fork 了您的仓库，或者从您的仓库拉取了更改的情况下。在这种情况下修改历史记录将使他们无法安全地将您的仓库中的更改合并到他们的仓库中。出于这个原因，我们从不在官方 Play Framework 仓库中修改历史记录。

但是，对于您个人 fork 的分支，特别是那些只用于 pull request 的分支，情况就不同了 - 工作流程的意图是您的更改在合并到主分支后才会被“发布”。在此之前，历史记录可以被视为正在进行的工作。

但是，如果您的分支是多人协作的结果，并且您认为其他人出于正当理由从您的分支拉取了代码，请告知我们，我们不会强制进行 squash commits，除非确实有必要。

下一步： 关于 Play

发现此文档中的错误？此页面源代码可在此处找到。阅读完文档指南后，请随时贡献 pull request。有疑问或建议要分享？请访问我们的社区论坛，与社区进行交流。