LAMMPS GitHub 贡献指南:从 Fork 到 Pull Request 的完整协作流程
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" 按钮:
在接下来的页面中保持默认设置,点击 "Create fork" 创建。其中 "Copy the develop branch only"(仅复制 develop 分支)选项务必保持选中——因为所有对 LAMMPS 的贡献都必须基于 develop 分支:
创建完成后,你的账号下就有了 https://github.com/<你的用户名>/lammps 这个 fork 仓库。你可以在其中任意修改,然后通过 pull request 请求 LAMMPS 开发者把你的改动合入官方仓库。
在本地操作你的 fork
克隆你的 fork
在 GitHub 网页上打开你的 fork,点击 "Code" 按钮,选择 "SSH" 方式,复制仓库 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 的表单:
请仔细检查并填写以下内容:
- 目标与来源分支: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"(对话)页签的底部:
这些检查由仓库中的 .github/workflows 目录下的 GitHub Actions 工作流定义,包括:
- style-check.yml:运行
make check-whitespace、make check-permissions、make check-homepage、make check-errordocs、make check-fmtlib等编程风格一致性检查; - unittest-linux.yml:在 Linux 上以
LAMMPS_BIGGIG等配置构建并运行标准单元测试; - 此外还有跨平台的 unittest-macos.yml、unittest-arm64.yml、compile-msvc.yml,以及 check-gnu-make.yml、check-examples.yml、codeql-analysis.yml 等。
如果任何一项检查失败,你的 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):
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 中删除已经完成使命的功能分支:
然后在本机更新 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 贡献了。






