first-contributions 首次开源贡献实战：从 Fork 到 Pull Request 的完整指南
【免费下载链接】first-contributions🚀✨ Help beginners to contribute to open source projects项目地址: https://gitcode.com/gh_mirrors/fi/first-contributions
本文以 GitHub 加速计划 fi 镜像中的 first-contributions 仓库为教学载体，系统讲解新手完成人生第一次开源贡献的标准工作流fork → clone → edit → pull request。全文覆盖从仓库分叉、本地克隆、分支创建、文件修改与提交，到推送远端并发起 Pull Request 的每一步，并给出可直接复制运行的 git 命令；读完你将完整掌握在真实开源项目中提交一次代码贡献的全部技术动作，同时了解该仓库内置的 Git 进阶学习材料与图形化工具教程入口。
项目概览：一个为「第一次贡献」而生的教学仓库
first-contributions 项目的定位非常明确：简化并引导初学者完成他们的第一次开源贡献。它不是展示复杂架构的业务代码库，而是一个刻意设计的练习场——任务只有一个：把自己的名字添加到 Contributors.md 中，并成功提交一个 Pull Request。
围绕这一单一目标，仓库组织了清晰的学习资源：
- README.md：主教程（本文所依据的 README.aze.md 即其阿塞拜疆语翻译版），也是全部语言版本的骨架；
- Contributors.md：贡献者名单文件，截至当前镜像快照已累计约 5919 行，是本次练习的实际操作对象；
- docs/additional-material/git_workflow_scenarios/：Git 进阶场景学习材料索引（修改提交、解决冲突、同步 fork 等）；
- docs/gui-tool-tutorials/：针对不熟悉命令行的读者准备的图形化工具教程。
整个流程虽然简单，却完整复刻了真实开源协作中的全部关键环节：分叉远端仓库、管理本地分支、暂存与提交变更、推送远端、发起审查请求。掌握这套流程，你就具备了参与绝大多数开源项目的基本能力。
前置准备：安装 Git 与准备 GitHub 账号
开始之前需要确认两件事：
- 本机已安装 Git。如果尚未安装，请先参照官方文档完成 Git 的安装与环境配置（原文档提示了 Git 安装入口，安装完成后可在终端用
git --version验证）。 - 拥有一个可登录的 GitHub 账号。后续的 Fork、Push、Pull Request 操作都发生在你的账号名下。
第 1 步：Fork（分叉）仓库
打开 first-contributions 仓库主页，点击页面右上角的Fork按钮。
这一操作会在你自己的 GitHub 账号下生成一份该仓库的完整副本。此后你对仓库的一切修改都发生在这份副本中，不会影响原仓库；这也正是后续发起 Pull Request 的前提——你无法直接向别人的仓库推送代码，但可以请求对方合并你副本中的改动。
第 2 步：Clone（克隆）仓库到本地
Fork 完成之后，需要把远端副本拉到本地电脑，才能编辑文件。
登录 GitHub，进入你 fork 出来的仓库，点击绿色的Code按钮，再点击复制到剪贴板（copy to clipboard）图标，复制仓库地址。然后打开终端，执行：
git clone "你刚复制的地址"把命令中的占位内容替换为实际复制的 URL（不要带引号）。例如：
git clone https://github.com/你的用户名/first-contributions.git其中你的用户名是你的 GitHub 用户名。执行后，GitHub 上 first-contributions 仓库的全部内容就被复制到了你的电脑上，本地会生成一个名为first-contributions的目录。
第 3 步：创建分支（Branch）
分支是 Git 协作的基石：它让你可以在独立的开发线上修改代码，而不影响主分支（main）的稳定状态。
先进入仓库目录（如果当前不在该目录下）：
cd first-contributions然后使用git checkout创建并切换到新分支：
git checkout -b <你的新分支名>分支命名建议遵循本项目惯例：以add-开头，后接你的名字，例如：
git checkout -b add-alonzo-church补充：如果你使用的 Git 版本较新（2.23+），也可以使用功能等价的
git switch -c <分支名>命令。若执行git switch时提示 "switchis not a git command"，说明 Git 版本过旧，改用git checkout -b即可（该兼容性说明来自仓库主 README.md）。
第 4 步：修改文件并提交（Commit）
这是整个练习的核心动作。
用任意文本编辑器打开仓库根目录下的 Contributors.md，把自己的名字添加进去。注意：不要把名字加在文件开头或结尾，而是放在中间任意位置——这样做的目的是降低多名学习者同时提交时发生合并冲突的概率（仓库文档对此有明确指示）。保存文件后，本次练习的「代码变更」就完成了。
接下来按顺序执行三条命令，完成「查看变更 → 暂存 → 提交」：
1) 查看变更状态
git status在项目目录下执行后，你会看到Contributors.md被标记为已修改（modified），说明改动已被 Git 感知。
2) 暂存变更
git add Contributors.mdgit add把指定文件从工作区放入暂存区（staging area），使其进入待提交状态。这里只暂存了Contributors.md，符合「一次提交只包含一个逻辑变更」的良好习惯。
3) 提交变更
git commit -m "Add your-name to Contributors list"将your-name替换为你的名字。-m参数后的字符串是提交信息（commit message），用于说明本次提交做了什么，是开源协作中必须认真书写的内容。至此，变更已被固化到本地当前分支的历史中。
第 5 步：Push（推送）变更到 GitHub
本地提交只是完成了「本地一半」，要让远端仓库看到你的改动，需要执行推送：
git push origin <你的分支名>将<你的分支名>替换为你在第 3 步创建的分支名（注意原文档提示替换的是分支名）。推荐再加上-u参数建立本地分支与远端分支的追踪关系，之后在该分支上的推送就可以直接写git push：
git push -u origin <你的分支名>执行成功后，你 fork 出来的 GitHub 仓库中就会出现这个新分支及其上的提交。
第 6 步：提交 Pull Request（拉取请求）
推送完成后，回到 GitHub 上你自己的仓库页面，会看到一个醒目的Compare & pull request按钮，点击它。
随后进入 Pull Request 创建页面：确认比较方向（你的分支 → 上游仓库的main分支）与变更内容无误后，填写标题与说明，点击提交按钮，你的第一个 Pull Request 就正式发出了。
接下来只需等待仓库维护者审查。一旦变更被合并进项目的main分支，你就会收到通知邮件——至此，你的名字已永久写入 Contributors.md，第一次开源贡献宣告完成。
完成之后：巩固练习与开启更多贡献
恭喜！你已经完整走过了开源贡献者最常遇到的fork → clone → edit → pull request标准工作流。原文档还给出了三条后续路径：
- 分享成果：通过项目配套的 Web 应用（first-contributions 的在线站点）记录并分享你的第一次贡献；
- 更多练习：项目提供了 code-contributions 练习资源，可继续强化 Git 与贡献技能；
- 转向真实项目：项目整理了一批带 easy 级 issue（易上手问题）的开源项目清单，可以从这些项目开始，把刚刚掌握的流程应用到真实场景中。
进阶材料：Git 高阶场景学习索引
完成基础流程后，仓库在 docs/additional-material/git_workflow_scenarios/additional-material.md 中整理了面向真实协作场景的进阶学习材料，覆盖了首次贡献之后几乎所有会遇到的 Git 操作：
| 场景 | 文档 | 适用时机 |
|---|---|---|
| 修改最近一次提交 | amending-a-commit.md | 需要调整已做的一次提交（改提交信息或补漏文件） |
| 配置 Git 用户信息 | configuring-git.md | 需要更好地控制 Git 配置 |
| 同步 fork 与上游仓库 | keeping-your-fork-synced-with-this-repository.md | fork 落后于上游仓库，需要拉取最新变更 |
| 移动提交到其他分支 | moving-a-commit-to-a-different-branch.md | 提交落在了错误的分支上 |
| 删除本地文件 | removing-a-file.md | 提交前需要从本地仓库移除文件 |
| 删除本地分支 | removing-branch-from-your-repository.md | 你的 PR 被合并之后清理分支 |
| 解决合并冲突 | resolving-merge-conflicts.md | 合并时遇到冲突 |
| 回滚已推送的提交 | reverting-a-commit.md | 需要撤销已推送到远端的提交 |
| 压缩多个提交 | squashing-commits.md | 评审者要求把多个提交合并为一个 |
| 撤销本地提交 | undoing-a-commit.md | 本地仓库改乱了，需要重置 |
| 创建 .gitignore | creating-a-gitignore-file.md | 需要让 Git 忽略不需要跟踪的文件 |
| 凭据存储 | storing-credentials.md | 需要为仓库存储访问凭据（注意遵循所在机构的安全策略） |
| 更多学习链接 | Useful-links-for-further-learning.md | 想系统深入学习 Git 与开源领域知识 |
这些文档大多同样提供了多语言翻译版本（见 docs/translations），其中中文版可直接参考 docs/additional-material/git_workflow_scenarios 与 docs/translations/Chinese 目录。
不想用命令行？图形化工具教程汇总
如果对命令行感到吃力，仓库为常见 GUI 工具准备了完整的图文教程（位于 docs/gui-tool-tutorials），使用这些工具同样可以完成 fork、clone、commit、push、pull request 的全部流程：
| 工具 | 教程 |
|---|---|
| GitHub Desktop | github-desktop-tutorial.md |
| Visual Studio 2017 | github-windows-vs2017-tutorial.md |
| GitKraken | gitkraken-tutorial.md |
| Visual Studio Code | github-windows-vs-code-tutorial.md |
| Atlassian Sourcetree | sourcetree-macos-tutorial.md |
| IntelliJ IDEA | github-windows-intellij-tutorial.md |
常见问题与提示
推送时遇到认证错误。GitHub 已于 2021 年 8 月 13 日起移除了对密码认证的支持，改用 personal access token 或 SSH 密钥。若推送时报Authentication failed，可先执行git remote -v检查远端地址：
git remote -v如果远端使用的是https://github.com/你的用户名/first-contributions.git形式，可通过git remote set-url切换为 SSH 地址，再配合配置好的 SSH 密钥完成认证：
git remote set-url origin git@github.com:你的用户名/first-contributions.git（该提示同样来自仓库主 README.md 的错误处理章节。）
不要在 main 分支上直接改。整个练习刻意要求「先建分支再修改」，这正是真实开源项目的通行规范：特性分支隔离变更、便于审查与回滚，也让多名贡献者的工作互不干扰。养成「一个分支一件事」的习惯，是参与开源协作的第一步。
【免费下载链接】first-contributions🚀✨ Help beginners to contribute to open source projects项目地址: https://gitcode.com/gh_mirrors/fi/first-contributions
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
