news 2026/9/19 16:36:19

first-contributions 实战指南：从 Fork 到 Pull Request 的首次开源贡献完整流程

作者头像

张小明

前端开发工程师

1.2k 24
文章封面图
first-contributions 实战指南：从 Fork 到 Pull Request 的首次开源贡献完整流程
  • 文档
  • 教程
  • 开源治理

【免费下载链接】first-contributions

🚀✨ Help beginners to contribute to open source projects

项目地址：https://gitcode.com/gh_mirrors/fi/first-contributions
点击查看免费下载

本指南以开源仓库 first-contributions 的核心入门文档为主体，系统讲解初学者完成第一次开源贡献所需的完整 Git 工作流：Fork 仓库 → 克隆到本地 → 创建分支 → 修改并提交 → 推送远程 → 提交 Pull Request。读完本文，你将能独立完成一次真实的开源贡献，并掌握分支管理、远程同步与冲突处理等后续进阶技能。

文档背景与本指南的定位

本文基于仓库中的入门文档 README.pcm.md 展开。该文档是项目主 README 的尼日利亚皮钦英语（Nigerian Pidgin）翻译版本，与 主 README 内容完全对应：项目定位是帮助初学者以最简单的方式完成第一次开源贡献（项目描述为 "Help beginners to contribute to open source projects"）。仓库根目录的 Contributors.md 已有近六千行贡献者名单，每位贡献者的名字正是通过本文将要讲解的流程逐步添加进去的——它本身就是这套工作流最好的运行示例。

文章中所有命令均以终端操作为主。如果你不习惯命令行，仓库还提供了使用图形界面工具的教程，可在文章末尾的「图形界面工具」一节查看。

开始之前：准备 Git 环境

整个流程的第一步是确认本机已安装 Git。在终端执行：

git --version

如果提示找不到命令，需要先完成 Git 的安装与基础配置。安装完成后，建议先用git config配置用户名和邮箱，因为提交（commit）会记录作者信息。关于用户信息、默认编辑器等配置项的详细说明，可参考仓库文档 configuring-git.md。

第一步：Fork 仓库

进入 first-contributions 仓库页面，点击页面顶部的Fork按钮。

Fork 的本质是在你自己的账号下创建一份该仓库的完整副本。这一步之后，你会拥有一个属于自己的first-contributions仓库，后续所有修改都发生在你的副本上，不会影响原始仓库。

第二步：克隆仓库到本地

克隆（clone）是把远程仓库的内容下载到本机。操作如下：

  1. 登录 GitHub，打开你刚才 Fork 出来的仓库；
  2. 点击页面上的Code按钮（建议切换到 SSH 标签页），点击复制按钮把仓库地址复制到剪贴板；
  3. 打开终端，执行git clone命令：
git clone "url wey you just copy"

其中"url wey you just copy"（去掉引号）替换为刚复制的地址，即你 Fork 出来的仓库地址。例如：

git clone git@github.com:this-is-you/first-contributions.git

这里的this-is-you是你的 GitHub 用户名。执行成功后，远程仓库的全部内容就被复制到了本机。如果想在本地查看本仓库（镜像）的代码而不进行贡献流程，也可以直接克隆镜像地址：git clone https://gitcode.com/gh_mirrors/fi/first-contributions.git。

第三步：创建分支

先进入仓库目录（如果还没进去的话）：

cd first-contributions

然后使用git switch命令创建一个新分支：

git switch -c your-new-branch-name

例如：

git switch -c add-desmond-ezo-ojile

分支是 Git 的核心概念之一：它让你在独立的开发线上修改代码，而不会干扰主分支（main）。这也是后续 Pull Request 能够「按分支评审合并」的基础。

兼容性提示：如果执行git switch时出现类似 "Git:switchis not a git command" 的错误，说明你的 Git 版本较旧。此时改用等价的git checkout命令即可：

git checkout -b your-new-branch-name

（此后备方案详见主文档 README.md 中的说明。）

第四步：修改文件并提交

现在开始做出你的实际贡献。用文本编辑器打开仓库根目录的 Contributors.md 文件，把你的名字添加进去。注意：不要加在文件开头或结尾，而是加在文件中间任意位置，这是为了让多位贡献者的提交减少冲突概率。

保存文件后，回到项目目录执行git status，你会看到该文件已被标记为有变更：

git status

git status会列出工作区中所有改动，是后续每个步骤前都建议执行的状态检查命令。

接下来把改动添加到暂存区（staging area），使用git add：

git add Contributors.md

git add只暂存你明确指定的文件，这给了你精确控制「哪些改动进入下一次提交」的能力。

然后提交这些改动：

git commit -m "Add your-name to Contributors list"

把your-name替换成你自己的名字。-m参数用于附加提交信息，一条清晰、描述性的提交信息是开源协作的基本礼仪。

第五步：推送到 GitHub

提交只发生在本地，接下来要把本地分支推送到你的 GitHub 仓库：

git push -u origin your-branch-name

把your-branch-name替换为你第三步创建的分支名。-u参数会把本地分支与远程分支建立跟踪关系，此后在该分支上直接执行git push即可，无需再指定远程和分支名。

推送失败：认证错误处理

如果推送时遇到认证错误，最常见的情形是 GitHub 自 2021 年 8 月 13 日起移除了密码认证，错误信息通常形如：

remote: Support for password authentication was removed on August 13, 2021. Please use a personal access token instead. fatal: Authentication failed for 'https://github.com/<your-username>/first-contributions.git/'

解决办法是按 GitHub 官方指引，为账号生成并配置 SSH 密钥（SSH key），以 SSH 方式认证。

此外，可用以下命令检查当前的远程地址配置：

git remote -v

如果输出类似于：

origin https://github.com/your-username/your_repo.git (fetch) origin https://github.com/your-username/your_repo.git (push)

说明仍然走 HTTPS 方式、会反复提示输入用户名密码。可改用 SSH 地址：

git remote set-url origin git@github.com:your-username/your_repo.git

这样即可避免后续的认证报错。

第六步：提交 Pull Request

推送成功后，回到你在 GitHub 上的仓库页面，页面上会出现一个Compare & pull request按钮，点击它，然后提交 Pull Request。

Pull Request（简称 PR）是开源协作的关键环节：它向原始仓库的所有者发出「请合并我分支上的这些改动」的请求。提交后，项目维护者会审查你的改动并合并到主分支；合并完成后，你会收到一封变更已合并的通知邮件。

至此，你已完整走通了开源贡献的标准流程：fork → clone → edit → pull request。这个四步工作流在几乎所有 GitHub 协作项目中都会反复遇到。

贡献完成之后：进阶主题

第一次贡献只是起点。仓库在 additional-material.md 中整理了一批进阶 Git 场景，以下两个与日常协作关系最密切：

保持 Fork 与上游仓库同步

随着项目持续演进，你 Fork 的仓库会落后于原始仓库。开源协作中常见「三角工作流」：原始公开仓库 → 你的 GitHub Fork → 你的本地仓库。同步的基本思路是先把原始仓库（称为upstream）的最新内容拉到本地，再推送到你的 Fork。

首先为本地仓库添加上游远程（只需配置一次）：

git remote add upstream https://github.com/firstcontributions/first-contributions.git

接着切换到 main 分支（可用git status第一行确认当前分支）：

git checkout main

然后拉取上游最新版本并变基到本地 main 分支：

git fetch upstream git rebase upstream/main

最后推送到你的 Fork（即名为origin的远程）：

git push origin main

如果想一步完成「拉取并合并上游 main」的操作，可以直接使用：

git pull upstream main

建议在 GitHub 提示「你的分支落后于上游 N 个提交」时执行上述同步流程。完整说明见 keeping-your-fork-synced-with-this-repository.md。

解决合并冲突

当不同分支修改了同一处内容、Git 无法自动合并时，就会产生合并冲突。冲突文件中会插入如下标记：

<<<<<<< HEAD 你的分支上的改动 ======= 来自其他分支的改动 >>>>>>> branch-name

其中<<<<<<< HEAD表示当前分支的改动，=======是分隔线，>>>>>>> branch-name表示另一个分支的改动。解决步骤是：用git status定位冲突文件（位于 "Unmerged paths" 列表）→ 编辑文件、保留期望的改动并删除全部冲突标记 → 用git add <filename>标记已解决 → 最后提交合并。详细流程见 resolving-merge-conflicts.md。

其他常见场景索引

仓库的进阶文档还覆盖了以下高频场景，均位于docs/additional-material/git_workflow_scenarios/目录下：

  • 修改最近一次提交（amending-a-commit.md）：调整提交信息或补充遗漏的改动；
  • 撤销已推送的提交（reverting-a-commit.md）；
  • 撤销/重置本地提交（undoing-a-commit.md）；
  • 将多个提交压缩为一个（squashing-commits.md）：常用于响应评审者「把提交合并成一个并附上信息性提交信息」的要求；
  • 移除文件与删除分支（removing-a-file.md、removing-branch-from-your-repository.md）。

图形界面工具

如果你更习惯图形化操作而非命令行，仓库在docs/gui-tool-tutorials/下提供了多套工具的入门教程，例如 GitHub Desktop、Visual Studio Code、GitKraken 等，覆盖了 Windows、macOS 等不同平台。

结语：一份可复用的贡献检查清单

回顾全文，一次标准贡献可以浓缩为六步检查清单：

  1. Fork：在原始仓库页面点击 Fork，获得自己的副本；
  2. Clone：复制 Fork 地址并git clone到本地；
  3. Branch：git switch -c your-branch-name创建独立分支（旧版 Git 用git checkout -b）；
  4. Commit：修改 Contributors.md →git status检查 →git add Contributors.md→git commit -m "Add your-name to Contributors list"；
  5. Push：git push -u origin your-branch-name，遇认证错误时改用 SSH key 或git remote set-url调整远程地址；
  6. Pull Request：点击Compare & pull request提交 PR，等待维护者审查合并。

这套流程不仅适用于 first-contributions 仓库，也是所有 GitHub 开源项目通用的协作范式。完成首次贡献后，建议继续阅读仓库中的 进阶文档 与各语言版本（包括中文版 README），逐步从「会提 PR」成长为熟练的开源贡献者。

  • 文档
  • 教程
  • 开源治理

【免费下载链接】first-contributions

🚀✨ Help beginners to contribute to open source projects

项目地址：https://gitcode.com/gh_mirrors/fi/first-contributions
点击查看免费下载

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

版权声明: 本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若内容造成侵权/违法违规/事实不符，请联系邮箱：809451989@qq.com进行投诉反馈，一经查实，立即删除！
网站建设 2026/9/19 16:33:40

GmSSL 与 Nginx 国密双证书配置实战：TLCP 改造避坑指南

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

作者头像 李华
网站建设 2026/9/19 16:30:38

LLVM编译器基础设施详解：从IR构建到Pass优化实战

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

作者头像 李华
网站建设 2026/9/19 16:30:32

OpenStack多租户网络隔离实战：从VLAN到VXLAN的架构演进

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

作者头像 李华
网站建设 2026/9/19 16:30:06

机器人视觉导航中的图像内容匹配与SLAM全链路解析

简介&#xff1a;一份无人系统与智能机器人研究方向的高质量参考文献&#xff0c;核心是一篇发表于《光学 精密工程》的学术论文《结合图像内容匹配的机器人视觉导航定位与全局地图构建系统》。该研究针对室内自主定位中的“绑架”问题与相似物体干扰&#xff0c;提出了基于图像…

作者头像 李华
网站建设 2026/9/19 16:29:36

RK3568 MIPI DSI屏调试：uboot正常内核黑屏的软硬件全链路排查

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

作者头像 李华
网站建设 2026/9/19 16:29:35

Unity锁帧原理与热管理实战：从功耗控制到VR稳帧

1. 项目概述&#xff1a;为什么“锁帧”不是妥协&#xff0c;而是精密的热力学博弈“锁帧的智慧&#xff1a;拿帧率换发热余量”&#xff0c;这个标题里藏着一个被太多开发者轻描淡写、甚至误读的核心动作——Application.targetFrameRate。它不是一句简单的代码&#xff0c;而…

作者头像 李华