first-contributions 仓库实战：从 Fork 到 Pull Request 的首次开源贡献完整指南（Fork → Clone → Edit → PR 工作流）
【免费下载链接】first-contributions🚀✨ Help beginners to contribute to open source projects项目地址: https://gitcode.com/gh_mirrors/fi/first-contributions
导读
本文基于开源仓库 first-contributions 的西班牙语（墨西哥）官方翻译文档 README.mx.md，系统讲解初学者完成第一次开源贡献的标准路径：Fork → Clone → 创建分支 → 修改并提交 → Push → 提交 Pull Request。读完本文，你将掌握这套在几乎所有开源项目中都会遇到的协作工作流，学会用git switch、git add、git commit、git push完成一次真实贡献，并了解后续进阶的 Git 技巧与图形化工具路线。
一、项目背景：为什么需要"第一次贡献"实战
任何事情的第一次都很难，尤其是当你开始与他人协作时，犯错总让人不愉快。first-contributions 项目的核心目标，正如仓库根目录 README.md 所描述的那样："simplify and guide the way beginners make their first contribution"（简化并引导初学者完成第一次贡献）。
读文章、看教程固然有帮助，但有什么比在一个安全的练习环境里"真刀真枪"做一遍更好呢？该项目提供的就是这样一个演练场——你不需要理解复杂的项目业务，只需要按照步骤走完一遍完整流程，就能在本地把整套协作机制跑通。本项目以 MIT 协议开源（见 LICENSE），仓库结构非常简单，核心资产有两块：
- Contributors.md：贡献者名单，本文实战中要修改的文件，目前已有数千行贡献者记录；
- docs：涵盖 Git 工作流进阶文档、CLI 教程 和图形化工具教程 的完整学习体系。
而本文依据的 README.mx.md 正是这份入门教程的西班牙语（墨西哥）版本，与仓库根目录 README.md 内容结构一一对应，供西语社区的初学者使用。
二、准备工作：安装 Git 并配置身份
在开始之前，请确认本地机器已安装 Git。如果还没有安装，需要先完成 Git 的安装与环境配置。
Git 在设计上要求每次提交都必须关联一个名字和邮箱——在协作场景中，只有这样才能明确"谁在什么时候改动了项目的哪部分"。仓库的进阶文档 configuring-git.md 详细介绍了三种配置身份的方式：
1. 全局配置（Global Config）
存储在全局配置中的内容对当前系统上所有仓库生效，这是最常用、也最推荐的方式：
git config --global user.email "you@example.com" git config --global user.name "Your Name"2. 仓库级配置（Repository Config）
仅对当前仓库生效。例如你在公司项目里需要用公司邮箱提交时，可以省略--global标志：
git config user.email "you@alternate.com" git config user.name "Your Name"3. 命令行级配置（Command-line Config）
只对当前这一条命令生效。所有 Git 命令都支持用-c参数在动作动词之前注入临时配置：
git -c user.name='Your Name' -c user.email='you@example.com' commit -m "Your commit message"优先级说明：三种方式的优先级为命令行级 > 仓库级 > 全局。也就是说，如果同一个变量在命令行和全局都配置了，命令行里的值会优先生效。
除用户信息外，Git 配置还支持许多其他选项，例如：core.editor（指定编写提交信息的编辑器）、commit.template（指定提交信息模板文件）、color.ui（控制输出是否使用颜色）等。
三、第一步：Fork 仓库
Fork（分叉）是开源协作的起点。在仓库页面右上角点击Fork按钮，即可把该仓库复制一份到你自己的 GitHub 账户下。
这一步的意义在于：普通用户对公共仓库没有写入权限，但对自己账户下的副本拥有完全控制权。你后续的所有修改都发生在自己的副本上，通过 Pull Request 再把改动提交回原仓库。
小提示：如果你暂时不想登录 GitHub，只想先在本地预览本仓库内容，也可以直接克隆本仓库的镜像：
git clone https://gitcode.com/gh_mirrors/fi/first-contributions。但正式的贡献流程需要从你自己的 Fork 开始。
四、第二步：Clone 克隆仓库到本地
进入你自己的 GitHub 账户，打开刚才 Fork 出来的仓库，点击Code按钮，复制仓库地址（可切换 SSH 或 HTTPS 方式），然后在终端执行：
git clone "你复制的仓库地址"其中"你复制的仓库地址"（不含双引号）就是你 Fork 出来的仓库 URL。例如，如果你的 GitHub 用户名是usuarioGitHub：
git clone https://github.com/usuarioGitHub/first-contributions.git这条命令会把 GitHub 上 first-contributions 仓库的全部内容复制到你的电脑上。
五、第三步：创建分支（Branch）
克隆完成后，进入仓库目录：
cd first-contributions接下来用git switch命令创建并切换到一个新分支：
git switch -c <你的名字>例如：
git switch -c add-juan-perez分支名不一定包含add这个词，但加上它是合理的——因为这条分支的目的就是把你的名字加入名单。仓库根目录 README.md 还给出了一个兼容性提示：如果遇到git switch不可用的错误（提示 "switch is not a git command"），说明本地 Git 版本较旧，改用git checkout即可：
git checkout -b add-juan-perez为什么一定要新建分支？因为开源协作要求"功能隔离"：每个分支只承载一个明确的改动，主分支（main）保持稳定，便于维护者审查和合并。
六、第四步：修改文件并提交（Commit）
现在打开仓库根目录下的 Contributors.md 文件，用文本编辑器把你的名字加进去。注意：不要加在文件开头或结尾，加在中间任意位置即可。保存文件。
回到终端，在项目目录执行git status，可以看到改动已被 Git 识别。接着把改动加入暂存区：
git add Contributors.md然后提交这些改动：
git commit -m "Add <你的名字> to Contributors list"把<你的名字>替换成你的真实名字即可。
这一步对应着 Git 工作区的三个状态：工作区修改（git status可见）→ 暂存区（git add之后）→ 本地仓库（git commit之后）。git commit会在本地生成一条带唯一哈希值、作者信息和时间的提交记录，正如 check-commit-log.md 展示的提交日志那样：
$ git log commit e3fabb30ab536bd5876461d8a749301a321e714f (HEAD -> main, upstream/main, origin/main) Author: Dan Yunheum Seol <yunheum.seol@mail.mcgill.ca> Date: Tue Jun 4 01:07:25 2024 -0400 Add dan-seol to Contributors list (#84962)七、第五步：Push 推送改动到 GitHub
git commit只把改动保存在本地仓库，要让 GitHub 上的 Fork 副本同步这些改动，需要执行：
git push origin <分支名>把<分支名>替换为你之前创建的分支名称（例如add-juan-perez）。
根目录 README.md 还建议在首次推送时加上-u参数建立本地分支与远程分支的跟踪关系：git push -u origin your-branch-name，这样后续推送可以省略分支参数。
推送报错怎么办
仓库文档记录了两种常见问题：
- 认证错误（Authentication Error）：如果提示 "Support for password authentication was removed"，说明你的远程地址仍是 HTTPS 形式（可通过
git remote -v查看），此时需要改用 SSH 地址：
git remote set-url origin git@github.com:你的用户名/你的仓库.gitgit switch不可用：见上文，改用git checkout -b <分支名>。
八、第六步：提交 Pull Request（PR）
回到你的 GitHub 仓库页面，此时会看到一个绿色的Compare & pull request按钮，点击它。
GitHub 会展示你的分支与原仓库 main 分支的差异对比，确认无误后填写标题与描述，点击提交，即完成了一次 Pull Request。
提交之后，仓库维护者会审查你的改动并执行合并（merge）。合并完成后，你会收到一封邮件通知。此时再回头看你推送过的分支，可以用 removing-branch-from-your-repository.md 中介绍的方法在 PR 合并后清理本地与远程分支。
九、完整的协作全景：理解"三角工作流"
完成一次 PR 只是开始。在真实开源项目中，你会长期面临一个场景：上游公共仓库不断有新提交，你的 Fork 会落后。仓库文档 keeping-your-fork-synced-with-this-repository.md 将这种协作模式称为Triangle Workflows（三角工作流），涉及三个仓库：
| 仓库 | 角色 |
|---|---|
| 上游公共仓库（upstream） | 项目权威版本，维护者在此合并 PR |
| 你的 GitHub Fork（origin） | 你账户下的副本，PR 只能从这里发起 |
| 本地仓库 | 你实际编写代码的地方 |
同步流程分三步：
# 1. 回到 main 分支（用 git status 第一行确认当前分支） git checkout main # 2. 将上游仓库注册为名为 upstream 的远程 git remote add upstream https://github.com/firstcontributions/first-contributions.git # 3. 拉取上游最新代码 git fetch upstream # 4. 把上游 main 合并进本地 main git rebase upstream/main # 5. 推送本地 main 到你的 Fork git push origin main如果你希望"拉取并合并"一步完成，可以直接执行：
git pull upstream main养成习惯：每当 GitHub 提示你的 Fork "落后几个提交"（a few commits behind）时，就执行一次上述同步。
十、后续进阶：从第一次贡献到熟练贡献者
恭喜！你刚刚走完了贡献者最常遇到的fork → clone → edit → pull request标准工作流。之后你可以：
- 庆祝并分享这次贡献（社交分享入口位于项目的 Web 应用页面）；
- 继续练习，在 Web 应用中浏览由项目维护者整理的、带有简单 issue 的开源项目列表，开始向其他项目贡献；
- 深入学习 Git 进阶技巧——仓库的 additional-material.md 是整套进阶文档的索引，覆盖了贡献者后续几乎必然遇到的场景：
| 进阶主题 | 文档 | 适用场景 |
|---|---|---|
| 修改最近一次提交 | amending-a-commit.md | 提交信息有笔误、漏改了内容 |
| 撤销已推送的提交 | reverting-a-commit.md | 需要回滚已经推到远程的提交 |
| 撤销本地提交 | undoing-a-commit.md | 本地仓库改乱了想重置 |
| 压缩多个提交 | squashing-commits.md | 评审者要求把多个提交合并为一个 |
| 解决合并冲突 | resolving-merge-conflicts.md | 合并时出现冲突 |
| 移动提交到其他分支 | moving-a-commit-to-a-different-branch.md | 提交放错了分支 |
| 删除文件 | removing-a-file.md | 提交前需要移除文件 |
| 同步 Fork | keeping-your-fork-synced-with-this-repository.md | 本地仓库落后于上游 |
| 查看提交历史 | check-commit-log.md | 排查"谁改了什么" |
| 配置 Git | configuring-git.md | 配置身份、编辑器等 |
| 创建 .gitignore | creating-a-gitignore-file.md | 只提交必要文件 |
| 存储凭据 | storing-credentials.md | 免密推送（注意安全策略） |
以修改最近一次提交为例，仓库文档 amending-a-commit.md 给出了两种典型场景：
- 只改提交信息（不打开编辑器）：
git commit --amend -m "新的提交信息" git push origin <分支名>- 补充遗漏的改动并合并进上一次提交：先修改文件，再
git add <文件名>，然后执行git commit --amend（会打开编辑器让你确认信息），最后推送。
警告：如果该提交已经推送到远程，amend 会导致本地历史与远程分叉，需要强制推送覆盖远程：
git push --force。但强制推送会覆盖远程上其他人期间的改动，更安全的做法是用git push --force-with-lease，它会在覆盖前检查远程分支是否有他人新提交，避免误伤。
十一、不习惯命令行？图形化工具路线
README.mx.md 开头特别说明：如果你不习惯使用命令行，可以直接走图形化工具路线。仓库在 docs/gui-tool-tutorials 下为每种主流 GUI 工具提供了完整教程，覆盖与本文完全相同的 Fork→Clone→Edit→PR 流程：
- GitHub Desktop 教程
- Visual Studio 2017 教程
- GitKraken 教程
- Visual Studio Code 教程
- Atlassian Sourcetree 教程
- IntelliJ IDEA 教程
此外，docs/cli-tool-tutorials/github-cli-tutorial.md 还提供了基于 GitHub CLI（gh命令）的完整流程教程，适合偏好终端但想少记命令的开发者。
十二、多语言学习资源
first-contributions 是一个高度国际化的项目：根目录 README.md 顶部通过国旗图标链接到几十种语言的翻译版本，完整的语言索引见 docs/translations/Translations.md。本文所依据的 README.mx.md 正是其中"Español de México（墨西哥西班牙语）"版本，与 README.es.md（西班牙语）、README.zh-cn.md（简体中文）等其他翻译同属一个体系，方便不同语言背景的学习者对照阅读。
小结：从 Fork 到 Pull Request，本文完整还原了首次开源贡献的六个核心步骤，并结合仓库的 进阶文档 补充了身份配置、分支管理、提交修正、Fork 同步、冲突解决等真实协作中高频使用的技巧。把这套流程亲手走一遍，你就迈出了成为开源贡献者的第一步。
【免费下载链接】first-contributions🚀✨ Help beginners to contribute to open source projects项目地址: https://gitcode.com/gh_mirrors/fi/first-contributions
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
