LAMMPS GitHub 贡献指南:从 Fork 到 Pull Request 的完整协作流程

原创2026-10-13 13:10:171,828 阅读
文章标签:科学计算高性能计算科研

LAMMPS GitHub 贡献指南:从 Fork 到 Pull Request 的完整协作流程

LAMMPS 的公开开发托管在 GitHub 上,所有新增功能与缺陷修复都必须以 pull request(PR)的形式提交,并经过自动化测试与 LAMMPS 开发者评审后才能进入官方发布版。本文基于 doc/src/Howto_github.rst 编写,面向对 git 和 GitHub 几乎没有经验的新手,完整讲解从注册账号、配置 SSH、Fork 仓库、本地分支开发,到提交 PR、应对自动化检查与评审、合并后清理的每一步;同时结合仓库中的贡献要求文档、PR 模板与 GitHub Actions 工作流,说明 LAMMPS 团队在幕后如何测试与审核你的代码。读完本文,你将掌握一套可直接照做、可复现的 LAMMPS 贡献工作流。

为什么通过 GitHub 提交贡献

LAMMPS 的源代码用 git 管理,公开开发托管在 GitHub 上。贡献者对自己做出的改动以 pull request 的形式提交,提交后由自动化系统测试、由 LAMMPS 开发者审核,通过后才会被合入官方仓库。

在动手之前,建议先阅读下面几份文档,它们定义了"什么样的代码能进 LAMMPS":

  • Modify_contribute.rst:提交新功能的总体流程与沟通方式(何时联系开发者、预期投入时间、外部贡献方式);
  • Modify_requirements.rst:贡献的严格/偏好要求清单,包括许可、集成测试、文档、编程语言标准、构建系统、命名规范等;
  • Modify_style.rst:LAMMPS 统一的编程风格与命名约定。

需要特别强调的是,所有对 LAMMPS 代码和文档的改动,无论多么微小,都必须通过 pull request 提交——这条规则同样适用于 LAMMPS 自己的开发者。仓库中的 doc/github-development-workflow.md 明确写道,对 "develop" 分支的一切修改只能通过合并 pull request 完成。这意味着即使你只想修一个拼写错误,也要走完本文的整个流程。

如果你不打算通过 GitHub 提交,也可以把修改打成 gzip 压缩的补丁文件(推荐 diff -u 或 diff -c 格式)直接发给 LAMMPS 开发者,由他们代为提交 PR,但这种方式的合入周期通常更长。

准备工作

创建 GitHub 账号

首先需要一个 GitHub 账号。访问 GitHub 官网,点击 "Sign up" 按钮注册即可。注册成功后,后续所有网页端操作(Fork、提交 PR、查看检查状态)都在你的账号下进行。

安装并配置 git

本地机器需要安装 git 命令行程序。在 Linux 和 macOS 上通常已经自带;如果没有,可以用包管理器安装,例如 Debian 和 Ubuntu 上的:

sudo apt install git

在 Windows 上,官方推荐使用 Windows Subsystem for Linux(WSL)中的 git,这样可以在与 Linux 一致的环境中编译和运行 LAMMPS,避免原生 Windows 工具链的兼容性问题。

首次使用 git 前,先设置你的名字和邮箱——它们会被记录到每一个提交(commit)中,也是 GitHub 上关联你身份的依据:

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

用 SSH 密钥配置 GitHub 访问

要把本地改动上传(push)到 GitHub,git 必须验证你的身份。GitHub 不接受直接用账号密码来执行 push,最简单的做法是使用 SSH 密钥。生成密钥:

ssh-keygen -t ed25519 -C "you@example.com"

生成过程中直接回车接受默认文件位置即可(也可以为私钥设置口令保护)。然后查看公钥内容:

cat ~/.ssh/id_ed25519.pub

复制输出内容,在 GitHub 网页上点击右上角头像 → "Settings" → "SSH and GPG keys" → "New SSH key",粘贴公钥并确认。之后所有 git 操作都会自动通过 SSH 完成身份验证。

替代方案:如果你安装了 GitHub 官方命令行工具 gh,可以运行 gh auth login 一次性完成登录并配置 git 对 GitHub 的认证,后续步骤见文末"用 GitHub CLI 操作"一节。

Fork 官方仓库

你不能直接把改动上传到官方 LAMMPS 仓库。正确做法是先在自己的 GitHub 账号下创建官方仓库的一份拷贝,即 fork。

进入 LAMMPS 官方 GitHub 仓库页面,点击右上角的 "Fork" 按钮:

LAMMPS GitHub 页面上的 Fork 按钮

在接下来的页面中保持默认设置,点击 "Create fork" 创建。其中 "Copy the develop branch only"(仅复制 develop 分支)选项务必保持选中——因为所有对 LAMMPS 的贡献都必须基于 develop 分支:

创建 LAMMPS 仓库的 fork

创建完成后,你的账号下就有了 https://github.com/<你的用户名>/lammps 这个 fork 仓库。你可以在其中任意修改,然后通过 pull request 请求 LAMMPS 开发者把你的改动合入官方仓库。

在本地操作你的 fork

克隆你的 fork

在 GitHub 网页上打开你的 fork,点击 "Code" 按钮,选择 "SSH" 方式,复制仓库 URL:

复制 fork 仓库的 URL

然后在终端中克隆并进入目录:

git clone git@github.com:<你的用户名>/lammps.git
cd lammps

为了今后能同步官方仓库的最新改动,把官方仓库添加为另一个 remote,命名为 "upstream":

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

运行 git remote -v 应该能看到两个 remote:"origin"(你的 fork)和 "upstream"(官方仓库)。

创建功能分支

每一个功能或缺陷修复,都应当放在一个独立的功能分支(feature branch)里,该分支只包含与这个功能相关的修改(例如新增一个 fix 时,只包含它的源文件、头文件和文档)。每次开发新功能,都从官方仓库 develop 分支的最新版本创建新分支。以分支名 "my-new-feature" 为例:

git fetch upstream
git switch --no-track -c my-new-feature upstream/develop

这里的 --no-track 标志非常重要:如果不加,git 会把官方仓库的 develop 分支记为你新分支的"上游对应分支",之后执行 git push 时可能根据你的 git 设置,把改动推到 fork 的 develop 分支而不是新分支。

注意事项:不要在 fork 的 develop 分支上做任何修改,也不要让同一个分支承载不相关的改动。这样能让你的各份改动彼此独立,也更容易被合入 LAMMPS。

做出修改并提交

现在开始写代码:做出修改、编译并测试 LAMMPS,同时确保改动符合 Modify_requirements.rst 的贡献要求和 Modify_style.rst 的编程风格。

用 git status 查看哪些文件被修改或新增,用 git diff 查看改动细节。确认无误后,把修改的和新增的文件加入下一次提交,并用简短信息记录提交:

git add src/EXTRA-FIX/fix_my_new_feature.cpp src/EXTRA-FIX/fix_my_new_feature.h
git add doc/src/fix_my_new_feature.rst
git commit -m "add fix my/new/feature"

警告:不要使用 git commit -a 或 git add -A。这两个命令会自动包含所有被修改和新增的文件,这很少是你想要的行为,很容易把无关的改动误提交进仓库。正确做法是显式地用 git add(添加)、git rm(删除)、git mv(重命名)逐个处理文件,再用 git commit 完成提交。提交前务必用 git status 仔细核对所有待提交改动。如果觉得命令行操作繁琐,也可以考虑 GUI 工具,例如 git gui(部分 Linux 发行版需要额外安装包)。

一个分支上可以提交任意多个 commit。

上传你的改动到 GitHub

首次将分支推送到 fork 时,使用:

git push -u origin my-new-feature

之后对这个分支再执行普通的 git push 即可上传后续的新增提交。

提交 Pull Request

到目前为止,所有改动都只存在于你自己的 LAMMPS 副本中。要请求官方合入,需要提交 pull request。推送分支后,GitHub 会在你的 fork 页面(以及官方 LAMMPS 仓库页面)显示一条横幅,上面有 "Compare & pull request" 按钮,点击进入新建 PR 的表单:

发起一个新的 pull request

请仔细检查并填写以下内容:

  • 目标与来源分支:PR 必须是从你 fork 中的功能分支指向官方 LAMMPS 仓库的 develop 分支;
  • 标题:用一句简短的话描述这个改动;
  • 描述:描述字段预填了模板,请逐节填写并替换注释占位内容。特别地,模板中的 "Artificial Intelligence (AI) Tools Usage"(AI 工具使用)一节要求你声明是否以及如何使用 AI 工具生成了本次改动;而 "Licensing"(许可)声明不得改动或删除;
  • "Allow edits by maintainers"(允许维护者编辑)复选框保持选中:这样 LAMMPS 开发者可以直接在你的分支上做小修改或修正,能显著加快 PR 被合入的进度;
  • 最后点击 "Create pull request" 提交。如果改动尚未完成,但你希望先给 LAMMPS 开发者展示、或先看看自动化测试结果,可以从下拉菜单中选择 "Create draft pull request"(创建草稿 PR),之后随时可以标记为 "Ready for review"(可评审)。

仓库根目录下的 .github/PULL_REQUEST_TEMPLATE.md 就是这份预填模板的原文。可以看到它包含:改动摘要(Summary)、关联 issue(Related Issue,支持 fixes #xxx / closes #xxx 语法让合入时自动关闭对应 issue)、作者信息(Author(s))、Licensing、AI 工具使用声明、向后兼容性说明(Backward Compatibility)、实现说明(Implementation Notes),以及一份"提交后核对清单"(Post Submission Checklist),涉及文档、两种构建系统验证、单元测试、示例输入等条目,是评估自己 PR 完整性时非常实用的参考。

提交 PR 之后

自动化检查

PR 提交后,GitHub 会自动启动多组检查,包括:在多个平台和不同配置下能否编译通过、能否通过单元测试、是否符合 LAMMPS 的部分格式化约定。检查状态显示在 PR "Conversation"(对话)页签的底部:

PR 的自动化检查状态

这些检查由仓库中的 .github/workflows 目录下的 GitHub Actions 工作流定义,包括:

如果任何一项检查失败,你的 PR 不会被合并。点击失败的检查项(或打开 "Checks" 页签)查看具体失败原因。修复失败原因是你自己的责任;如果需要帮助,可以在 PR 下留言说明问题。

这与 Modify_requirements.rst 中"集成测试(严格)"要求一致:贡献代码必须通过 GitHub 上的自动化测试才能合入,测试包括多种环境与配置下的编译、随附单元测试,以及 HTML/PDF 文档构建检查。文档要求还强调,新代码除了默认的 -DLAMMPS_SMALLBIG 配置,还必须能在 -DLAMMPS_BIGBIG 下编译并正确工作,串行与 MPI 并行均须正常。

更新 pull request

你推送到功能分支的任何新提交都会自动成为 PR 的一部分,并且每次推送后自动化检查都会重新运行。因此,你可以随时补充遗漏的改动,或实现 LAMMPS 开发者提出的修改要求。

LAMMPS 开发者也可能(在你允许的情况下)直接向你的分支推送修改。因此,在继续开发之前,务必先用 git pull 更新本地副本。

如果在此期间 develop 分支发生了变化并与你的改动产生冲突,你需要把那些改动合并进自己的分支、解决冲突并推送结果:

git fetch upstream
git merge upstream/develop
git push

注意:对已提交 PR 的分支,不要使用 git rebase 和 git push --force。这会重写分支历史,给已经基于该分支工作的其他人造成麻烦。

评审、标签与指派

每个 PR 都会由 LAMMPS 开发者评审。部分评审者会被自动指派——他们与改动的文件相关联,这种关联定义在仓库的 .github/CODEOWNERS 文件中(该文件用文件路径模式将各源码包、目录与对应的维护者 GitHub 账号绑定,例如 /src/GPU/ 对应 @ndtrung81、/src/KOKKOS/ 对应 @stanmoore1)。评审者和开发者可能会对你的改动发表评论或要求修改,请务必回应;如果被要求的修改无人处理,PR 无法合并。

合并条件:PR 必须通过全部自动化测试,并且获得至少两位对仓库有写权限的 LAMMPS 开发者的批准(合入 PR 本身计为一次批准)。

PR 页面的右侧会显示评审者(Reviewers)、被指派的开发者(Assignee)、标签(Labels)和里程碑(Milestone):

PR 的评审者、指派者、标签与里程碑

LAMMPS 开发者可能会把 PR 指派给某位"照看"它的人,由其决定合入前还需要做什么。里程碑(milestone)标明该 PR 计划纳入哪个版本。标签大多用于内部记账,但有少数很重要:

  • needs_work:PR 尚未完成,需要你继续修改;
  • work_in_progress:仍在改动中(由你或 LAMMPS 开发者进行);
  • ready_for_merge:PR 被视为已完成、可以合并。

有时 LAMMPS 开发者不会直接改动你的分支,而是在你的 fork 中提交一个 PR(称为 "reverse pull request")供你审阅。如果你同意这些改动,可以在那个 PR 的 GitHub 页面上直接合并,然后用 git pull 更新本地副本。

另外,新软件包或其他重要贡献的贡献者,可能会被邀请成为具有 Triage 权限的 LAMMPS 项目协作者,参与 PR 评审和一些管理性工作;但他们的批准仅具参考意义,不构成合并所需的正式批准。

关于 LAMMPS 开发者处理 PR 的更多细节,可以阅读 doc/github-development-workflow.md。该文档还记录了评审规则细节(如 CODEOWNERS 触发的自动评审、合并人的唯一指定、closes #xxx 自动关闭 issue 的约定)以及发布规划(feature release 每 4~8 周一次、stable release 约每年一次等)。

PR 合入之后

一切顺利的话,LAMMPS 开发者会把你的 PR 合并进 develop 分支,此时 PR 页面会出现 "Delete branch"(删除分支)按钮。点击它,从 GitHub 上的 fork 中删除已经完成使命的功能分支:

已合并的 pull request

然后在本机更新 develop 分支并删除本地功能分支:

git switch develop
git pull upstream develop
git branch -d my-new-feature

如果想同步保持 fork 在 GitHub 上的 develop 分支最新,可以点击 fork 页面上的 "Sync fork" 按钮,或直接推送更新后的本地分支:git push origin develop。

用 GitHub CLI 操作

上述网页端操作大多可以用 GitHub 官方命令行工具 gh 完成。先用 gh auth login 登录(它也能同时配置 git 对 GitHub 的认证),然后:

gh repo fork lammps/lammps --clone   # 创建 fork 并克隆
gh pr create --draft                 # 为当前分支提交(草稿)pull request
gh pr checks                         # 查看自动化检查状态
gh pr view --web                     # 在浏览器中打开 pull request

gh repo fork 一步完成"fork + clone",gh pr create 直接为当前所在分支创建 PR,gh pr checks 让你不必打开网页就能跟踪检查状态。

LAMMPS 的分支与发布

理解 LAMMPS 的分支结构有助于把握贡献的落点。所有新功能和缺陷修复都提交到 develop 分支;此外仓库中还有几个分支:

  • release:在每次"功能发布(feature release)"时从 develop 更新而来;
  • stable:在"稳定发布(stable release)"时与 release 一起从 develop 更新;
  • maintenance:在两次稳定发布之间,从 develop 反向移植选定的缺陷修复与基础设施更新,偶尔合入 stable 作为"更新发布(update release)"。

版本标签遵循如下规律:

  • 功能发布:patch_<日><月><年>,例如 patch_10Sep2025;
  • 稳定发布:额外的 stable_<日><月><年> 标签;
  • 更新发布:stable_<日><月><年>_update<序号>。

这也再次印证了为什么要基于 develop 分支开发:只有 develop 汇集了全部最新改动,从这里创建的 PR 才能避免与官方正在开发的功能冲突。

附:贡献要求速览与提交前自检

为了让 PR 更快被接受,这里汇总 Modify_requirements.rst 中的核心要求(完整清单请查阅原文):

严格要求:

  • 许可:提交 PR 即表示同意在 LAMMPS 的许可条款下分发贡献——公开版本为 GPL v2(非 v3 或更高);新源文件顶部应带有 LAMMPS 版权和 GPL 声明及作者姓名、邮箱;
  • 集成测试:必须在 GitHub 自动化测试中通过;代码须在 -DLAMMPS_BIGBIG 与默认 -DLAMMPS_SMALLBIG 两种配置下编译运行正常,串行与 MPI 并行均须通过;
  • 文档:新增样式或命令必须附带 doc/src/ 目录下的 .rst 文档(美式英语、纯 ASCII),并集成进 Sphinx 文档系统;
  • 编程语言标准:核心为 C++17(风格大致是"带类的 C",避免运算符重载和过度使用模板);Fortran 需兼容 Fortran 2003;Python 需兼容 Python 3.6;
  • 构建系统:新软件包可只支持 CMake 构建;独立成对的 .h/.cpp 文件通常只需加入 src/.gitignore;
  • 命名:用户可见的命令/样式名全小写、仅用字母数字和斜杠;例如 compute 样式 some/name 的源文件须命名为 compute_some_name.h / compute_some_name.cpp,头文件保护宏为 LMP_COMPUTE_SOME_NAME_H,类名为 ComputeSomeName。

偏好/可选要求:

  • 示例:尽量附带简单、小型、单 CPU 快速运行的示例脚本;
  • 错误信息:鼓励具体、能直接指出原因的错误消息(可借助 fmt 库的格式化错误 API);
  • 引用提醒:可在源文件中登记论文引用,当用户调用该功能时输出引用提示;
  • 单元测试:对不依赖 LAMMPS 对象的工具类建议在 unittest 树中补充测试;对新的力计算样式可添加带参考数据的 .yaml 测试配置。

提交 PR 前,对照 .github/PULL_REQUEST_TEMPLATE.md 中的核对清单逐项确认(许可与作者信息、AI 工具声明、文档及构建验证、单元测试、示例输入等),并用 git status 检查待提交内容——准备充分的分支会让评审和合并都顺畅很多。现在就可以注册账号、生成密钥、Fork 仓库,开始你的第一次 LAMMPS 贡献了。

登录后查看全文
lammps