企业官网建设流程全解析

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.un-aln.md，与仓库根目录 README.md 同源）为主体，完整拆解一次开源贡献的标准流程：Fork 仓库、Clone 到本地、创建分支、修改 Contributors.md、提交并推送、最后发起 Pull Request。读完本文，你将掌握fork → clone → edit → pull request这条几乎所有开源项目通用的协作链路，并具备排查推送认证错误的实战能力。

一、先理解这份教程在教什么

first-contributions 是一个专门为开源新人设计的教学项目，其目标是"简化并引导初学者完成第一次贡献"。整个仓库的骨架非常简单：一份教程文档、一个贡献者名单文件 Contributors.md，以及大量面向不同工具、不同语言的辅助教程。

这正是刻意设计的教学场景：你的任务不是读懂复杂的业务代码，而是走完一次真实的 Git 协作流程——把"贡献"这个抽象概念，落实为"在 Contributors.md 里加上自己的名字并成功合并"这一件具体小事。仓库根目录的 README.md 开头明确写道："This project aims to simplify and guide the way beginners make their first contribution"，而本文对应的关联文档（docs/translations/README.un-aln.md）是它的完整同源版本，正文结构与操作步骤完全一致。

整个流程的核心链路是：

Fork（复制到自己的账户）→ Clone（拉到本地）→ Branch（新建分支） → Edit（修改文件）→ Commit（本地提交）→ Push（推送到远程） → Pull Request（发起合并请求）→ Merge（维护者合并）

下文每一步都给出可直接复制运行的命令。

二、准备工作：安装 Git，并确认版本差异

在开始前，先确认你的机器上已经安装 Git。如果尚未安装，请按平台官方的 Git 安装指南完成安装（Windows 可安装 Git Bash，macOS 与 Linux 可通过各自包管理器安装）。

安装完成后，可以用一条命令验证版本：

git --version

这里有一个新手很容易踩的坑：创建分支的命令存在新旧版本差异。本教程正文使用的是经典写法git checkout -b，而仓库主 README（README.md 的 "Create a branch" 一节）使用的是新版 Git 推荐的git switch -c，并明确说明：如果执行git switch时提示 "switchis not a git command"，说明你的 Git 版本较旧，请改用git checkout -b。两种写法效果相同，本文统一采用兼容性最好的git checkout -b。

三、第一步：Fork 这个仓库

Fork（分叉）是开源协作的第一步。打开仓库主页，点击页面右上角的Fork按钮：

点击页面顶部的 fork 按钮即可 Fork 这个仓库，这会在你自己的账户下创建一个该仓库的副本。

Fork 与直接修改原仓库的关键区别在于：

• Fork 得到的副本属于你个人，你对它有完全的读写权限；
• 原仓库（上游）的代码不受你的任何操作影响；
• 后续你通过 Pull Request 把副本中的改动"申请合并"回上游，由维护者审核决定是否接受。

四、第二步：Clone 到本地

4.1 复制你的 Fork 地址

Fork 完成后，进入你账户下的这个副本仓库，点击Code按钮（本教程早期版本为 SSH 标签页下的复制图标），然后点击"复制到剪贴板"图标，得到该仓库的 URL。注意：复制的是你自己 fork 出来的副本地址，而不是上游原仓库的地址。

4.2 执行 clone 命令

打开终端，运行下面的命令（引号内替换为你刚复制的地址，引号本身不需要）：

git clone "url you just copied"

示例：

git clone https://gitcode.com/gh_mirrors/fi/first-contributions.git

在实际练习中，把示例地址换成你自己的 fork 地址即可。这条命令会把远程仓库的完整内容（包括所有分支与历史记录）复制到你的本地计算机，生成一个与仓库同名的目录first-contributions。

五、第三步：创建分支

5.1 进入仓库目录

克隆完成后，切换到仓库目录（如果你已经在这里，可跳过）：

cd first-contributions

5.2 用 checkout 创建并切换分支

使用git checkout命令创建并切换到一个新分支：

git checkout -b your-new-branch-name

示例：

git checkout -b add-alonzo-church

这里的-b参数表示"创建并切换"；分支名通常用add-前缀加上你要贡献的内容来命名，例如add-alonzo-church。为什么不直接在默认分支上改？因为分支提供了一条隔离的开发线：你的实验性修改不会干扰主干，即使改坏了也可以随时丢弃。仓库的进阶文档 docs/additional-material/git_workflow_scenarios/why-using-branches.md 对这一主题有专门讲解。

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

6.1 编辑 Contributors.md

现在用任意文本编辑器打开仓库根目录的 Contributors.md，把你的名字加进去。教程有一个具体且刻意的要求：

不要把名字加在文件的开头或结尾，把它放在文件中间的任何位置。

这个要求的背后是刻意制造的"冲突训练"——因为大量贡献者都在往同一个文件里加名字，如果你刚好和别人的改动发生重叠，就会在后续的合并阶段遇到合并冲突（merge conflict），这其实是教学环节的一部分。从仓库现状看，Contributors.md 已经积累了约 5953 行、数千位贡献者的记录，文件内部正是类似- [你的名字](https://github.com/你的用户名)的 Markdown 列表项格式，照此格式在中间任意位置插入一行并保存即可。

6.2 用 git status 查看变更

保存文件后，在项目目录执行：

git status

你会看到类似modified: Contributors.md的输出，表示文件已被修改但尚未暂存。这个命令能帮你随时确认当前工作区的状态，是 Git 使用频率最高的命令之一。

6.3 用 git add 暂存修改

把修改加入刚刚创建的分支（暂存区）：

git add Contributors.md

6.4 用 git commit 提交

提交并附上规范的提交信息：

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

把<your-name>替换成你的真实名字。git commit把暂存区的改动固化成本地历史记录，-m参数指定提交信息。提交信息遵循"动词开头 + 做了什么"的简洁约定，这在开源社区是通用习惯。

七、第五步：Push 到 GitHub

7.1 推送分支

本地提交完成后，用git push把改动推送到远程仓库：

git push origin -u <add-your-branch-name>

把<add-your-branch-name>替换为你前面创建的分支名。这里的两个参数含义分别是：

• origin：远程仓库的默认别名，指向你 fork 的副本；
• -u：--set-upstream的简写，把本地分支与远程分支建立跟踪关联，此后在该分支上只需执行git push即可。

7.2 推送报错排查：认证错误

推送时最容易遇到的错误是认证失败。原文档给出了典型的报错信息：

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

这意味着自 2021 年 8 月 13 日起，GitHub 已不再支持用账号密码进行 Git 操作认证，需要改用个人访问令牌（Personal Access Token）或 SSH 密钥。修复方法：

1. 在账户设置中生成一个 Personal Access Token，并授予仓库读写权限，用它替代密码；
2. 或生成 SSH 密钥对，并把公钥配置到账户的 SSH keys 中（仓库的进阶文档 docs/additional-material/git_workflow_scenarios/storing-credentials.md 对凭据存储有专门说明）。

另一个常见原因是远程地址指向错误。执行以下命令检查你的远程地址：

git remote -v

如果输出形如https://github.com/your-username/your_repo.git的 HTTPS 地址且你希望改用 SSH 认证，可以这样修改：

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

否则推送时会反复提示输入用户名和密码，并最终报认证错误。

八、第六步：提交 Pull Request

推送成功后，回到你账户下的仓库页面，会看到一个Compare & pull request按钮，点击它：

1. 确认比较方向：base（目标，即上游仓库的主分支）←compare（你的分支）；
2. 填写 Pull Request 的标题与说明，简要描述你做了什么修改；
3. 点击提交 Pull Request。

提交后，维护者会收到通知并审核你的改动。一旦审核通过并被合并到主分支，你会收到一封通知邮件——至此，你的第一次开源贡献就完成了。

九、完成后去哪里：进阶材料与更多练习

完成这次fork → clone → edit → pull request流程后，你已经掌握了贡献者最常使用的一条标准链路。仓库还为你准备了大量进阶资源：

9.1 进阶 Git 场景材料

仓库的 docs/additional-material/git_workflow_scenarios/additional-material.md 汇总了十余个进阶主题，按需取用：

9.2 不习惯命令行的读者：GUI 工具教程

如果你对命令行不熟悉，仓库在 docs/gui-tool-tutorials/github-desktop-tutorial.md 等目录下提供了多款图形化工具的分步教程，覆盖 GitHub Desktop、VS Code、IntelliJ IDEA、GitKraken、Atlassian Sourcetree、Visual Studio 2017 等，中文版见 docs/gui-tool-tutorials/translations/Chinese/。这些教程用鼠标点击即可完成同样的流程，适合零命令行基础的同学。

9.3 多语言版本与 CLI 教程

仓库还维护了大量语言版本的主教程（见 docs/translations/Translations.md，含中文版 docs/translations/README.zh-cn.md），以及 Git 命令行与 GitHub CLI 的专项教程，见 docs/cli-tool-tutorials/。

十、小结：一次提交背后的协作心智

回顾整个过程，你实际完成的是一次标准的开源协作闭环：Fork 保证"人人可改而不破坏原仓库"，分支保证"改动彼此隔离"，Pull Request 保证"所有变更经过审核"。这套机制正是现代开源协作得以大规模运转的基石。完成第一次贡献后，你可以把同样的流程迁移到任何你感兴趣的项目上：阅读它的贡献指南、认领一个 easy issue、按本文的六步走完提交——从此你就不再是旁观者，而是开源社区的一员。

关键命令速查：

git clone <your-fork-url> # 克隆 fork 到本地 cd first-contributions # 进入仓库目录 git checkout -b add-your-name # 创建并切换分支 git status # 查看工作区状态 git add Contributors.md # 暂存修改 git commit -m "Add <your-name> to Contributors list" # 提交 git push origin -u add-your-name # 推送并建立跟踪

推送报错时先git remote -v检查远程地址，再用令牌或 SSH 密钥完成认证；若需切换认证方式，用git remote set-url更新远程地址即可。

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