【LAMMPS学习】八、基础知识(6.2)LAMMPS GitHub 教程

 8. 基础知识

此部分描述了如何使用 LAMMPS 为用户和开发人员执行各种任务。术语表页面还列出了 MD 术语，以及相应 LAMMPS 手册页的链接。 LAMMPS 源代码分发的 examples 目录中包含的示例输入脚本以及示例脚本页面上突出显示的示例输入脚本还展示了如何设置和运行各种模拟。

8.1.通用基础知识

8.2. 设置入门

8.3. 分析入门

8.4. 力场入门

8.5. 软件包入门

8.6.操作教程

8.6.1.将 CMake 与 LAMMPS 结合使用

8.6.2. LAMMPS GitHub 教程

作者:Stefan Paquay

---

本文档描述了如何使用 GitHub 将您对 LAMMPS 所做的更改或添加集成到官方 LAMMPS 发行版中的过程。它使用更新本教程的过程作为示例来描述各个步骤和选项。您需要熟悉 git，并且您可能需要查看 git 书籍来熟悉下面使用的一些更高级的 git 功能。
截至 2016 年秋季，通过 GitHub 上的拉取请求向 LAMMPS 提交贡献是将贡献的功能或改进集成到 LAMMPS 的首选选项，因为它显着减少了 LAMMPS 开发人员所需的工作量。因此，创建拉取请求将增加您的贡献被包含在内的机会，并减少集成完成之前的时间。有关将代码包含到 LAMMPS 中的要求的更多信息，请参阅此页面。

---

Making an account 开设账户

First of all, you need a GitHub account. This is fairly simple, just go to GitHub and create an account by clicking the “Sign up for GitHub” button. Once your account is created, you can sign in by clicking the button in the top left and filling in your username or e-mail address and password.
首先，你需要一个 GitHub 帐户。这非常简单，只需转到 GitHub 并单击“注册 GitHub”按钮创建一个帐户即可。创建帐户后，您可以通过单击左上角的按钮并填写您的用户名或电子邮件地址和密码来登录。

---

Forking 存储库
要对 LAMMPS 进行更改，您需要首先在 GitHub 上fork lammps/lammps 存储库。在撰写本文时，develop 是首选目标分支。因此，转到 GitHub 上的 LAMMPS 并确保分支设置为“develop”，如下图所示。

如果不是，请使用 按钮将其更改为开发。一旦完成，请使用fork按钮创建分支。

这将在您自己的 GitHub 帐户下创建 LAMMPS 存储库的一个分支（本质上是一个副本，但使用较少的资源）。您可以在此分叉和稍后的文件拉取请求中进行更改，以允许上游存储库将您自己的分叉中的更改合并到我们刚刚分叉的分叉（或从同一存储库分叉的其他分叉）中。同时，您可以进行设置，以便将上游的更改包含到您的存储库中，从而使其与正在进行的 LAMMPS 开发保持同步。

---

将更改添加到您自己的分支中

LAMMPS 上游版本的添加是使用功能分支来处理的。对于每一个新功能，都会创建一个所谓的功能分支，其中仅包含与一个特定功能相关的修改。例如，添加单个修复将包括创建一个仅包含修复头和源文件而没有其他内容的分支。这里有更详细的解释： feature branch workflow。

特色分支

首先，通过 HTTPS 在本地计算机上创建 GitHub 上版本的克隆：

git clone https://github.com/<your user name>/lammps.git <some name>

或者，如果您已设置 GitHub 帐户以使用 SSH 密钥，则通过 SSH：

git clone [e-mail]:<your user name>/lammps.git

您可以通过单击“克隆或下载”按钮找到正确的 URL：

上面的命令将 git 存储库复制（“克隆”）到本地计算机上具有您选择的名称的目录。如果没有给出，它将默认为“lammps”。典型的名称是“mylammps”或类似的名称。

您可以使用此本地克隆进行更改并测试它们，而不会干扰 GitHub 上的存储库。

要将更改从上游拉取到此副本中，您可以转到该目录并使用 git pull：

cd mylammps
git checkout develop
git pull https://github.com/lammps/lammps develop

您还可以将此 URL 添加为远程：

git remote add upstream https://www.github.com/lammps/lammps

从那时起，您可以使用以下命令更新上游分支：

git fetch upstream

然后使用upstream/develop或upstream/release等引用上游存储库分支。

此时，您通常会从更新的分支中为您想要使用的功能创建一个功能分支。本教程包含更新本教程的工作流程，因此我们将分支称为“github-tutorial-update”：

git fetch upstream
git checkout -b github-tutorial-update upstream/develop

现在我们已经更改了分支，我们可以对本地存储库进行更改。请记住，如果您想开始研究另一个不相关的功能，您应该切换分支！

注：强烈建议不要对开发、发布或稳定分支进行更改。虽然一开始可能很方便，但从长远来看，它会带来更多的工作。有关使用 git 的各种文本和教程有效地讨论了使用功能分支的动机。

进行更改后

一切完成后，将文件添加到分支并提交：

git add doc/src/Howto_github.txt
git add doc/src/JPG/tutorial*.png

警告：不要使用 git commit -a （或 git add -A）。 -a 标志（或 -A 标志）将自动包含所有修改过的文件和新文件，但这很少是您想要的行为。它很容易导致意外地将不相关和不需要的更改添加到存储库中。相反，最好分别显式使用 git add、git rm、git mv 来添加、删除、重命名单个文件，然后使用 git commit 来完成提交。在提交之前，请使用 git status 仔细检查所有待处理的更改。如果您发现在命令行上执行此操作太乏味，请考虑使用 GUI，例如用 Tk 编写的 git 发行版中包含的 GUI，即使用 git gui（在某些 Linux 发行版上可能需要安装额外的软件包才能使用它）。

添加所有文件后，可以提交更改集并附带一些解释更改的有用消息。

git commit -m 'Finally updated the GitHub tutorial'

提交后，可以将更改推送到 GitHub 上的同一分支：

git push

如果您尚未配置任何内容，Git 会询问您在 GitHub 上的用户名和密码。如果您的本地分支尚未出现在 GitHub 上，它会要求您通过运行来添加它

git push --set-upstream origin github-tutorial-update

如果您正确输入用户名和密码，则功能分支应添加到 GitHub 上的分支中。

如果您想真正确保推送到正确的存储库（这是很好的做法），您可以明确提供它：

git push origin

或使用明确的 URL：

git push [e-mail]:Pakketeretet2/lammps.git

---

提交拉取请求

到目前为止，本教程中的所有更改均针对您的 LAMMPS 克隆。然而，最终您希望将此功能包含到官方 LAMMPS 版本中。为此，您需要通过单击“新拉取请求”按钮来提交拉取请求：

确保当前分支设置为正确的分支，在本例中为“github-tutorial-update”。如果操作正确，您将看到的唯一更改是在此分支上所做的更改。

这将打开一个新窗口，其中列出对存储库所做的更改。如果您只是添加新文件，则无需执行太多操作，但我认为如果现有文件发生更改，则应在此处解决合并冲突。如果所有更改都可以自动合并，顶部的绿色文本会说明这一点，您可以单击“创建拉取请求”按钮，请参阅图片。

在创建拉取请求之前，请确保短标题准确，并添加包含有关拉取请求的详细信息的评论。您可以在此处写下您的修改的作用以及为什么应将它们合并到上游。

请注意“允许维护者编辑”复选框。默认情况下，此复选框处于选中状态（尽管在我的 Firefox 版本中，只有复选标记可见）：

如果选中，维护人员可以立即将自己的编辑添加到拉取请求中。这有助于显着地包含您的分支，因为 LAMMPS 维护者可以将简单/琐碎的更改直接添加到您的拉取请求分支中。另一种选择是他们对自己的分支版本进行更改并向您提交反向拉取请求。除非您有充分的理由不这样做，否则只需选中此框即可。

现在只需写一些好的评论，然后单击“创建拉取请求”。

---

提交拉取请求后

注：当您第一次提交拉取请求（或请求拉取请求）时，您将收到成为 LAMMPS 项目合作者的邀请。请接受此邀请，因为成为协作者将简化某些管理任务，并且可能还会加快您的功能的合并速度。

您会注意到，提交拉取请求后，会自动执行一些检查：

如果一切顺利，您将看到以下内容：

如果任何检查失败，您的拉取请求将不会被处理，因为您的更改可能会破坏某些配置的编译或者可能无法干净地合并。您有责任消除测试失败的原因。如果您需要这方面的帮助，请通过添加注释来联系 LAMMPS 开发人员，解释您在解决失败测试时遇到的问题。

在拉取请求被包含之前，可能会发生一些更有趣的事情。

额外的变化

首先，您推送到存储库分支中的任何其他更改都将自动成为拉取请求的一部分：

这意味着您可以在提交拉取请求后添加应该成为该功能一部分的更改，这在您忘记它们的情况下很有用，或者如果开发人员要求在该功能被官方接受之前需要更改某些内容LAMMPS 版本。每次推送后，都会再次运行自动检查。

标签
LAMMPS 开发人员可能会向您的拉取请求添加标签，以将其分配到类别（主要用于簿记目的），但其中一些很重要：needs_work、work_in_progress、run_tests、test_for_regression 和ready_for_merge。前两个表明您的拉取请求不被认为是完整的。对于“needs_work”，负担完全由您承担；而“work_in_progress”也可能意味着 LAMMPS 开发人员可能想要添加更改。请注意拉取请求的评论。两个“测试”标签用于在合并代码之前触发扩展测试。如果 LAMMPS 开发人员怀疑您的更改可能会产生一些微妙的副作用，有时会这样做。默认情况下不会这样做，因为这些测试非常耗时。当分配给拉取请求的 LAMMPS 开发人员认为该请求已完成并触发最终的完整测试评估时，通常会附加 ready_for_merge 标签。

审查

截至 2021 年秋季，拉取请求需要通过所有自动测试以及至少 1 次来自具有存储库写入权限的 LAMMPS 开发人员的批准审查，然后才有资格进行合并。如果您的更改涉及与某些开发人员相关的代码，GitHub 软件会自动请求这些更改。这些关联是在文件 .github/CODEOWNERS 中设置的，因此，如果您希望在任何人更改文件或包时自动通知您进行审查，您已为 LAMMPS 做出了贡献，您可以向该文件添加合适的模式，或者 LAMMPS 开发人员可以添加你。

Otherwise, you can also manually request reviews from specific developers, or LAMMPS developers - in their assessment of your pull request - may determine who else should be reviewing your contribution and add that person. Through reviews, LAMMPS developers also may request specific changes from you. If those are not addressed, your pull requests cannot be merged.
否则，您还可以手动请求特定开发人员或 LAMMPS 开发人员的审核 - 在评估您的拉取请求时 - 可能会确定还有谁应该审核您的贡献并添加该人员。通过审核，LAMMPS 开发人员还可能要求您进行特定更改。如果这些问题没有得到解决，您的拉取请求将无法合并。

受让人

拉取请求有一个受让人属性。如果请求尚未经过任何开发人员审核，则不会将其分配给任何人。修订后，开发人员可以选择将其分配给 a) 您、b) LAMMPS 开发人员（包括他/她自己）或 c) Axel Kohlmeyer (akohlmey)。

• 如果您需要进行更改，则会出现情况 a)

• 情况 b) 意味着目前 LAMMPS 开发人员正在对其进行测试和审查，预计需要进行一些更改。审核后，开发人员可以选择直接实施更改或建议您实施更改。

• 情况 c) 意味着拉取请求已分配给开发人员，负责监督拉取请求合并到开发分支中。

在本例中，Axel 将教程分配给了 Steve：

LAMMPS 维护者的编辑

如果您允许维护者进行编辑（默认），则任何 LAMMPS 维护者都可以向您的拉取请求添加更改。在这种情况下，Axel 和 Richard 都对教程进行了更改：

反向拉取请求

然而，有时，您可能会觉得让其他人将更改推送到您自己的分支中感到不舒服，或者维护者可能不确定他们的想法是否正确。在这种情况下，他们可以进行更改，将您重新分配为受让人，并提交“反向拉取请求”，即在您分叉的 GitHub 存储库中提交拉取请求，以包含您作为拉取请求提交的分支中的更改你自己。在这种情况下，您可以选择将他们的更改合并回您的分支，可能会进行其他更改或更正，然后从那里继续。它看起来像这样：

由于某种原因，突出显示的按钮在我的情况下不起作用，但我可以转到我自己的存储库并从那里合并拉取请求：

请务必通过单击选项卡按钮检查更改以查看您是否同意它们：

在本例中，大部分是标记的更改以及 Axel 对“git gui”和“git add”命令的解释的简短重写。

因为我们可以接受这些更改，所以我们将通过单击“合并拉取请求”来合并。合并后看起来像这样：

现在，由于同时我们的教程本地文本也发生了变化，我们需要将 Axel 的更改拉回到我们的分支中，并将它们合并：

git add Howto_github.txt
git add JPG/tutorial_reverse_pull_request*.png
git commit -m "Updated text and images on reverse pull requests"
git pull

在这种情况下，合并很轻松，因为 git 可以自动合并：

随着 Axel 的更改合并以及一些最终文本更新，我们的功能分支现在就我们而言是完美的，因此我们将再次提交并推送：

git add Howto_github.txt
git add JPG/tutorial_reverse_pull_request6.png
git commit -m "Merged Axel's suggestions and updated text"
git push [e-mail]:Pakketeretet2/lammps

此合并也显示在 lampmps GitHub 页面上：

---

合并后

当一切正常后，feature分支被合并到develop分支：

现在还有一个问题：如何处理合并到上游的功能分支？

原则上，从您自己的分叉中删除它们是安全的。这有助于保持它更加整洁。请注意，您首先必须切换到另一个分支！

git checkout develop
git pull https://github.com/lammps/lammps develop
git branch -d github-tutorial-update

如果你不先拉取，这并不是真正的问题，但 git 会在下一条语句中警告你，你正在删除一个尚未完全合并到 HEAD 的本地分支。这是因为 git 还不知道你的分支刚刚合并到 LAMMPS 上游。如果您先删除然后拉取，一切都应该没问题。您可以通过以下方式显示完全合并的所有分支：

最后，如果您在本地删除分支，您可能还想将其推送到远程：

git push origin :github-tutorial-update

工作流程的最新变化

本教程未包含最近对工作流程的一些更改。例如，除了所有新功能都要提交到的develop分支之外，还有release、stable和maintenance分支；发布分支作为“功能发布”的一部分从开发分支更新，而稳定（与发布）分支在“稳定版本”发布时从开发更新。在稳定版本之间，选定的错误修复和基础设施更新会从开发分支向后移植到维护分支，并且偶尔会作为更新版本合并到稳定版本。

此外，版本标签的命名现在遵循“patch_<日><月><年>”模式，以简化版本之间的比较。对于稳定版本，应用附加的“stable_<Day><Month><Year>”标签，更新版本标有“stable_<Day><Month><Year>_update<Number>”，最后，所有版本和提交均受约束自动测试和代码检查，以确保它们可以使用各种编译器和流行的操作系统进行编译。还应用了一些单元和回归测试。

LAMMPS 开发人员 GitHub 工作流程的详细讨论可以在文件 doc/github-development-workflow.md 中找到