self-llm 开源项目贡献实战：GitHub 提 Issue 与提交 PR 全流程指南

  本文以《开源大模型食用指南》项目（self-llm）通用设置篇的 04-Issue&PR&update 文档为骨架，系统讲解参与该开源项目共建的完整链路：从「提 Issue 描述问题」到「Fork 仓库并完成修改」，再到「提交 Pull Request、同步上游更新与 PR 迭代修改」。读完本文，你将掌握网页端与 Git 命令行两种修改方式，能够独立提交一次规范、可被维护者顺利 Review 的 PR，真正成为开源社区的贡献者。

一、self-llm 的协作模式：Issue 与 PR 是参与共建的入口

self-llm 是一个围绕开源大模型、面向 Linux 平台初学者的大模型教程项目，其 README.md 明确写道："任何人都可以提出 issue 或是提交 PR，共同构建维护这个项目"。也就是说，Issue 与 PR 机制正是这个项目对外开放共建的核心通道。

从仓库结构看，贡献者可以参与的内容包括：

• 新增或完善模型的部署 / 微调教程：models 目录按模型家族组织（如 Qwen2.5、GLM-4、DeepSeek 等），每个模型目录内部按"01-FastApi 部署调用、02-Langchain 接入、03-WebDemo 部署、04-Lora 微调"等编号文档组织，配套截图统一放在各自的 images 目录；
• 完善通用环境配置文档：models/General-Setting 目录形成了面向新手的入门路径，依次是 pip、conda 换源、AutoDL 开放端口、模型下载，以及本文所讲的 Issue 与 PR 提交；
• 提供完整示例项目：如 examples 下的 Chat-嬛嬛、Tianji-天机、AMChat 等，配套数据可见 dataset；
• 修正文档错误、补充数据集、翻译英文文档等细粒度贡献。

contributors.json 详细记录了数十位贡献者的姓名与各自承担的任务数量，README.md 的致谢章节也列出了核心贡献者名单——这些都是"共建共享"协作模式的直接体现。下面，就从最基础的一步开始。

二、第一步：从提 Issue 开始

一般情况下，第一次提 PR 前，建议先提一个 Issue 来描述你的问题或者提议，让维护者确认你的工作方向符合项目预期，避免做无用功。但这并非强制要求：如果你已经准备好了明确、完整的改进内容，完全可以跳过 Issue，直接 Fork 仓库并提交 PR。

提 Issue 的操作非常简单：

1. 打开目标仓库页面，进入 Issues 标签页，点击右上角的绿色 New issue 按钮；
2. 在新建表单中填写内容（见下图）：
   • Title：一句话概括问题或提议；
   • 描述区：使用 Markdown 详细说明问题现象、复现步骤或改进方案，编辑器支持 Write / Preview 切换和代码块、列表、链接等格式化工具；
   • 右侧可选设置 Assignees（指派人）、Labels（标签）、Milestones（里程碑）；
3. 确认填写无误后，点击右下角绿色 Submit new issue 按钮提交。

提交后，维护者会在 Issue 下与你沟通、确认方案。对于 self-llm 这类教程仓库，一个好的 Issue 通常包含：想要新增的模型名称或文档章节、当前缺失/有误的内容、你计划如何实现等要素。

三、第二步：Fork 仓库并完成修改

确认方向后（或直接开始），点击仓库右上角的 Fork 按钮，将原始仓库复制到自己的 GitHub 账号下。此后所有的修改都在你自己的 fork 仓库中进行，改完后通过 PR 将更改合并回原始仓库。修改方式有网页端与 Git 命令行两种，按需选择。

3.1 网页端（图形界面）操作：新建文件夹、上传与删除文件

适合少量、单文件级别的改动，全程无需本地环境：

1. 新建文件夹：在仓库文件列表的"文件名"输入框中直接输入 文件夹名/，按下 / 键后 GitHub 会自动将其识别为文件夹，随后在该路径下创建一个 readme 或其他文件即可（后续不需要了也可以删除）；
2. 上传文件：进入目标目录后，点击右上角 Add file → Upload files（见下图），将本地写好的文件拖入或选择上传即可；
3. 删除文件 / 文件夹：点击文件或文件夹右侧的 ...（三个点）菜单，选择 Delete file 即可删除。

网页端的每次新建、编辑或删除操作都会引导你填写 Commit 信息（如 Create readme.md），点击 Commit changes 后即直接提交到你的 fork 仓库。这种方式适合在仓库目录结构中新增 models/新模型名/ 这样的入口文件或简单修正文档。

3.2 Git 命令行操作：clone、commit、push 全流程

当需要批量新增文件（例如一套完整的模型教程、配套代码与多张截图）时，建议使用 Git 命令行在本地完成修改。首先找到你 fork 仓库的克隆地址——在 fork 仓库页面点击 Code 按钮，即可看到 HTTPS / SSH 两种格式的仓库地址，将其记为 your/fork_repo_url。

在 Windows 上，建议在本地文件夹空白处右键选择 Git Bash Here 打开命令行（见下图）；在 Linux / macOS 上直接打开终端即可。

git clone 'your/fork_repo_url'   # 克隆你的 fork 仓库到本地
cd /path/to/your/local/folder    # 进入你的本地仓库目录

克隆完成后，即可在本地进行任意的增删减改。修改完成后，按以下顺序提交并推送：

git init                          # 初始化为 Git 仓库
git add .                         # 添加文件夹中的所有文件到暂存区
git commit -m "Added new folder"  # 提交，替换为你的提交信息
git remote add origin 'your/fork_repo_url'  # 将本地仓库关联到你的 fork 远程仓库
git push -u origin master         # 推送到远程仓库的 master 分支

各命令要点说明：

• git add . 会将当前目录下所有变更（新增、修改、删除）加入暂存区；若只想提交指定文件，可写为 git add 文件名；
• git commit -m 的提交信息建议写清楚改动内容，例如 add Qwen3 deployment tutorial，便于维护者 Review；
• git remote add origin 仅在本地仓库尚未关联远程仓库时使用——如果是 git clone 而来，origin 已自动配置好，可直接跳过；
• git push -u origin master 中的 -u 会建立本地分支与远程分支的跟踪关系，之后可直接使用 git push；部分仓库默认分支名为 main，以你 fork 仓库实际显示的分支为准。

执行完毕后，本地修改已全部同步到你的 fork 仓库，接下来就可以发起 PR 了。

四、第三步：提交 Pull Request 并完成 PR 迭代

修改推送完成后，从自己的 fork 仓库向原始仓库发起 PR：

1. 打开你的 fork 仓库，在页面顶部点击 Pull requests 标签；

2. 点击右上角的 New pull request 按钮；

3. 进入 Comparing changes 页面后，务必核对两个下拉菜单：

   • base：接受修改的目标仓库与分支，即原始仓库（通常是 master/main）；
   • head / compare：修改的来源，即你自己的 fork 仓库与分支；

   方向必须准确：base 是接受方原库，head 是自己更改好的 fork。弄反方向会导致 PR 内容异常或根本无法比较；

4. 点击 Create pull request 按钮，填写一个简短的标题和描述，说明本次修改的目的与内容；

5. 确认无误后，再次点击 Create pull request 提交 PR。

关于"修改 PR"：PR 提交后，维护者会进行 Review 并可能提出修改意见。此时你无需重新发起 PR——只需在自己的 fork 仓库中按第 3 节的方式再次修改对应文件并 git push，已提交的 PR 会自动同步更新为最新改动。这就是文档标题中"提交 PR 与修改 PR"的完整闭环，整个过程对维护者来说始终是同一个 PR 下的连续迭代。

对于 self-llm 项目，一个典型的教程类 PR 通常包含：models/模型名/ 下按编号组织的若干 Markdown 教程、配套代码文件（.py / .ipynb / train.sh 等）、截图（images/ 目录）。从仓库现有结构看，新增模型教程一般还需要同步维护 support_model.md 与 README.md 中的模型列表，建议在 PR 描述中明确说明改动范围。

五、第四步：同步上游仓库的最新更新

如果你的 fork 时间较早，而原始仓库在这期间已经有了新的更新，直接基于旧代码修改容易产生合并冲突。此时需要在本地先同步上游仓库的最新内容：

git remote add upstream <原仓库地址>   # 将原作者仓库添加为远程仓库（首次配置）
git fetch upstream                     # 将原仓库的更新拉取到本地
git checkout master                    # 切换到 master（或 main）分支
git merge upstream/master              # 合并原作者仓库的更新
git push origin master                 # 将合并后的代码推送到自己的 fork 仓库

其中 <原仓库地址> 替换为 self-llm 原始仓库的实际地址（HTTPS 或 SSH 格式均可）。建议在每次准备新 PR 之前都执行一次上述同步，确保你的改动基于最新的上游代码。对于需要同时维护模型列表、README 等多处文档的贡献场景，保持 fork 与上游同步能显著减少冲突概率。

六、常见问题：push 连接失败与 SSH 方案

有时候在 git push 时，HTTPS 方式的网络连接会"犯病"（超时、被限制或频繁报错），此时可以改用 SSH 方式关联远程仓库：

git remote add origin [e-mail]:username/repo.git

将 username/repo 替换为你的 GitHub 用户名与仓库名，然后重新执行 git push 即可。使用 SSH 方式前，需要在 GitHub 账号的 Settings → SSH and GPG keys 中添加本机的 SSH 公钥（GitHub 平台的标准配置），此后推送将不再依赖 HTTPS 连接，稳定性更高。

七、总结：PR 提交完整操作清单

最后，将"在 fork 仓库更新文件后，向原始仓库提交 PR"的全流程浓缩为五步清单：

1. 打开 fork 仓库，在页面顶部找到 Pull requests 标签并点击；
2. 在右上角点击 New pull request 按钮；
3. 在 Comparing changes 页面，核对两个下拉菜单：base 选择原始仓库及目标分支，head 选择自己的 fork 仓库及修改分支，并确认要提交的分支（通常是 master / main）；
4. 点击 Create pull request 按钮，填写一个简短的标题和描述，说清楚修改了什么、为什么改；
5. 确认无误后，再次点击 Create pull request 提交 PR。

除此之外，还有三个贯穿始终的要点值得牢记：提交前先同步上游（第 5 节），确保基于最新代码；PR 需要修改时，在 fork 中改完直接 push 即可，PR 会自动更新（第 4 节）；push 遇到连接问题时改用 SSH（第 6 节）。掌握了这套流程，你就具备了参与 self-llm 乃至任何 GitHub 开源项目共建的基本能力——从提交第一个 Issue 开始，迈出成为开源贡献者的第一步。