first-contributions 开源新手实战指南：从 fork 到 Pull Request 的首次贡献完整工作流

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 项目的塞尔维亚语（拉丁字母）版教程 docs/translations/README.sr-Latn.md 为核心，逐步骤拆解fork → clone → edit → pull request这一开源协作经典工作流，并结合仓库内的 Contributors.md、进阶文档与 GUI 教程，帮助初学者在真实仓库中完成第一个开源贡献，同时掌握每次贡献都会用到的 Git 命令、分支规范与常见报错处理。

一、项目定位与本文文档背景

first-contributions 是一个以教学为唯一目的的开源仓库：它的 README 本身就是"活教材"。初学者不需要先学习整套 Git 理论，只需按照 README 的指引一步步操作，把名字加入 Contributors.md 贡献者名单，就能真实地走完一次完整的代码贡献流程。

本文依据的 docs/translations/README.sr-Latn.md 是该项目 README 的塞尔维亚语拉丁字母版本，与根目录 README.md（英文原版）内容同构；仓库还在 docs/translations/README.sr-Cyrl.md 提供了塞尔维亚语西里尔字母版本。整个仓库通过 docs/translations/Translations.md 维护了数十种语言的入口索引，体现了开源项目"降低语言门槛"的社区文化。仓库采用 MIT 许可证（README 徽章标注）。

二、动手前的准备：git 环境与 GitHub 账号

原文开篇明确提示：如果本机还没有安装 git，请先完成安装（文档指向 GitHub 官方的 Set up Git 指引，本文以文字说明替代外部链接）。安装完成后，可以在终端执行以下命令确认环境就绪：

git --version

除此之外还需要：

• 一个 GitHub 账号（用于 fork 仓库、创建 pull request）；
• 一种认证方式：推荐提前配置 SSH 密钥；如果使用 HTTPS 地址，则需准备 personal access token（密码认证已于 2021 年 8 月 13 日起被 GitHub 移除，详见下文"认证错误"一节）。

三、第一步：Fork 仓库

概念：fork 是在你自己的 GitHub 账号下创建原仓库的一份完整副本。此后所有的改动都发生在自己的副本里，不会影响原仓库，这是开源协作中"先分叉、再合并"的基础。

操作：打开本仓库页面，点击页面顶部的Fork按钮。完成后，你的账号下会出现一个first-contributions仓库副本。

四、第二步：克隆仓库到本地

概念：clone（克隆）会把 GitHub 上 fork 出来的仓库完整下载到本地机器，之后才能在本地编辑文件。

获取克隆地址：

1. 进入自己的 GitHub 账号，打开刚刚 fork 出来的first-contributions仓库；
2. 点击Code按钮；
3. 切换到SSH标签页；
4. 点击"复制 URL 到剪贴板"图标，复制地址。

执行克隆：打开终端，运行以下 git 命令：

git clone "url you just copied"

其中"url you just copied"（不带引号）替换为刚复制的、指向你自己 fork 副本的仓库地址。例如：

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

其中this-is-you代表你的 GitHub 用户名。这条命令会把 GitHub 上 first-contributions 仓库的内容完整复制到你的电脑上。

补充原理：git clone在复制内容的同时，会默认把来源仓库注册为名为origin的远程引用，并检出默认分支（main）、建立本地分支与远程分支的跟踪关系，因此后续git push、git pull可以直接基于origin工作，这是克隆后"开箱即用"的原因。

五、第三步：创建专属分支

先进入克隆下来的仓库目录（如果尚未进入）：

cd first-contributions

然后使用git switch命令创建新分支并切换过去：

git switch -c your-new-branch-name

例如：

git switch -c add-alonzo-church

参数说明：-c是--create的缩写，含义是"创建名为your-new-branch-name的新分支，并立即切换到该分支"。

兼容旧版 git：文档特别给出了一个常见报错场景——如果命令执行后提示Git: "switch" is not a git command. See "git –help"，说明你使用的是较旧版本的 git（尚未引入git switch），此时改用传统写法即可：

git checkout -b your-new-branch-name

为什么必须建分支：这是开源协作的基本规范。每个 pull request 应当对应一个独立的功能分支，把不相关的改动隔离在不同分支中，既方便维护者逐个审查，也便于自己在多个任务之间切换。文档示例中add-alonzo-church这类"动词-对象"式命名（add-你的名字）也是社区中常见的命名习惯。

六、第四步：修改文件并提交

修改文件：用文本编辑器打开仓库根目录下的 Contributors.md 文件，在文件中加入你的名字。文档特别强调：不要加在文件开头或结尾，请加在中间任意位置，然后保存文件。

这个文件正是本教程的"练兵场"——它是真实存在的贡献者名单（当前仓库中已积累 5920 行），每位学习者的"贡献"就是把名字追加进这份名单，从而在不涉及复杂业务代码的情况下完整体验提交流程。

查看变更：回到项目目录执行git status，可以看到有改动存在（Contributors.md会出现在"未暂存的更改"区域）。

暂存改动：使用git add把改动加入刚刚创建的分支：

git add Contributors.md

提交改动：使用git commit提交：

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

将命令中的your-name替换为你的真实名字。-m参数用于直接指定提交信息，避免打开交互式编辑器。

底层原理补充：这条流程对应 Git 的"三区模型"——工作区（你编辑文件的地方）→ 暂存区（git add后，改动被记录但尚未入库）→ 本地版本库（git commit后，改动正式成为一次提交）。git status正是用来观察文件在这三个区域之间流转状态的命令：未暂存的改动与已暂存的改动会分别展示，是提交前检查内容是否完整的重要工具。

七、第五步：推送到 GitHub

使用git push把本地提交推送到 GitHub：

git push -u origin your-branch-name

将your-branch-name替换为之前创建的分支名。

参数说明：

• origin：默认的远程仓库名，即你 fork 出来的 GitHub 仓库；
• -u（--set-upstream）：建立本地分支与远程分支的跟踪关系。加上它之后，以后在这个分支上执行git push/git pull可以直接省略远程名和分支名；
• your-branch-name：要推送的本地分支名。

常见错误：认证失败

文档用较大篇幅专门处理了 push 阶段最常见的报错。自 2021 年 8 月 13 日起，GitHub 移除了 HTTPS 协议的密码认证，只能使用 personal access token 或 SSH 密钥。典型报错信息如下：

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

处理步骤：

1. 为你的账号生成并配置 SSH 密钥（文档建议参照 GitHub 官方的 SSH 密钥添加教程操作，此处以文字说明替代外部链接）；
2. 先检查当前远程地址是否确实指向 HTTPS：

git remote -v

如果输出类似：

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

3. 将远程地址切换为 SSH 格式：

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

否则 push 时仍会被反复要求输入用户名和密码，并最终报认证错误。

八、第六步：提交 Pull Request

推送成功后，回到 GitHub 上你自己的 fork 仓库，页面会出现一个Compare & pull request按钮：

1. 点击该按钮，进入 pull request 创建页面；
2. 确认改动内容无误后，点击提交 pull request；
3. 维护者审核后会把这些改动合并进项目的主分支（main），合并完成后你会收到邮件通知。

至此，一个贡献从"想法"到"合入上游仓库"的完整链路就打通了。值得说明的是：仓库根目录的 Contributors.md 中那数千行名单，正是由无数个这样的小型 pull request 累积而成，这本身就是开源协作力量最直观的证明。

九、完成之后的进阶方向

恭喜！你已经完成了标准的fork → clone → edit → pull request工作流——这是作为开源协作者最常遇到、也最重要的标准流程。

完成首秀之后，文档给出了三个进阶方向：

1. 更多练习：继续在其他练习项目中反复打磨这套流程；
2. 参与真实项目：从带有"easy issue"标签的简单问题入手，开始为其他开源项目做贡献；
3. 学习进阶 Git 技巧：本仓库在 docs/additional-material/git_workflow_scenarios/additional-material.md 汇总了一系列实战场景文档，覆盖协作中会反复遇到的进阶问题：

此外，该目录还收录了why-using-branches.md、rebase-vs-merge.md、resetting-a-branch.md、resetting-a-commit.md、stashing-a-file.md、check-commit-log.md、gitflow.md、delete-branch-locally.md等更多实战场景文档，可作为持续进修的索引。

十、不习惯命令行？用 GUI 工具完成同样流程

如果命令行让你感到不适，文档明确给出了替代路径：仓库在 docs/gui-tool-tutorials 目录下维护了多款图形界面工具的完整教程，覆盖了主流平台与 IDE：

该目录还包含旧版 GitHub Desktop 教程 github-desktop-old-version-tutorial.md、Sublime Merge 教程 sublime-merge-tutorial.md 以及 translations 多语言子目录，基本覆盖了各类开发环境。

结语

回顾整条路径：fork 建立自己的副本 → clone 拉到本地 → 新建分支隔离改动 → 编辑文件并 commit 记录 → push 推回远程 → 提交 pull request 请求合并。这套流程既是 first-contributions 项目的核心教学主线，也是所有开源项目协作的通用范式。无论你后续参与多少个项目，遇到多少次 review 意见、合并冲突或版本回退，本文涉及的这些基础命令与 进阶文档 都会是你最可靠的工具箱。

【免费下载链接】first-contributions🚀✨ Help beginners to contribute to open source projects项目地址: https://gitcode.com/gh_mirrors/fi/first-contributions