企业官网建设流程全解析

first-contributions 项目实战：从 Fork 到 Pull Request 的第一次开源贡献完整指南

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

本篇技术指南以 docs/translations/README.my.md（马来语版入门指南）为骨架，系统讲解在 first-contributions 仓库中完成第一次开源贡献的标准流程：Fork 仓库、Clone 到本地、创建分支、修改Contributors.md、提交并推送、发起 Pull Request。读完本文，你将完整掌握开源社区最常见的fork → clone → edit → pull request协作工作流，并了解git switch、git status、git add、git commit、git push等核心命令的实战用法，以及遇到认证失败、分支推错等问题时的排错方法。

项目背景与文档定位

first-contributions 是一个专门帮助初学者完成第一次开源贡献的教学仓库（项目描述为 "Help beginners to contribute to open source projects"）。它本身没有复杂的业务代码，其核心资产正是这份入门指南以及围绕它展开的 Contributors.md 贡献者名单和 docs 目录下的大量多语言教程。

README.my.md 是该指南的马来语翻译版本，其英文原版是仓库根目录的 README.md。整个仓库的运作方式就是"实战演练"：每位学习者按照指南把名字加入Contributors.md，再通过 Pull Request 提交，由维护者合并进main分支——这一步本身，就是一次真实的开源贡献。从 Contributors.md 当前近六千行的内容可以看出，已有大量学习者通过这条路径完成了自己的第一次贡献。

指南在开头特意说明：如果你不习惯使用命令行（CLI），可以跳转到文末的 GUI 工具教程章节，使用 GitHub Desktop、VS Code 等可视化工具完成同样流程。

准备工作：安装 Git

在进行任何操作之前，需要确认你的机器上已经安装 Git。指南原文的说明是：如果机器上尚未安装 Git，请先完成安装。

提示：主流操作系统（Windows / macOS / Linux）均有对应的 Git 安装方式，仓库内也提供了面向不同系统的安装文档，例如 docs/additional-material/git_workflow_scenarios/installing-git-ubuntu.md 和 docs/additional-material/git_workflow_scenarios/installing-git-arch.md。安装完成后，可在终端执行git --version验证是否成功。

另外，如果这是你第一次使用 Git 提交，Git 会要求你先配置用户名和邮箱（详见下文"进阶：Git 基础配置"一节），否则执行git commit时会收到*** Please tell me who you are.的提示。

第一步：Fork 这个仓库

Fork（分叉）是 GitHub 上的一种操作：点击仓库页面右上角的Fork按钮，就会在你自己的 GitHub 账号下生成一个该仓库的副本。

Fork 前：仓库位于 firstcontributions / first-contributions（只读） Fork 后：仓库位于 <你的账号> / first-contributions（可写）

这个副本归你所有，你可以自由地修改、提交、推送。它是后续所有操作的基础，因为只有从你自己的 Fork 才能发起 Pull Request（这一规则在 docs/additional-material/git_workflow_scenarios/keeping-your-fork-synced-with-this-repository.md 中再次强调）。

第二步：Clone 这个仓库

Fork 完成后，需要把远端仓库复制到本地机器。操作如下：

1. 进入你的 GitHub 账号，打开刚才 Fork 出来的仓库；
2. 点击Code按钮（Clone 按钮），再点击复制 URL 到剪贴板的图标；
3. 打开终端，执行：

git clone "你刚刚复制的 URL"

其中"你刚刚复制的 URL"（不带引号）就是你 Fork 出来的仓库地址。以马来语版指南的示例为例（this-is-you替换为你的 GitHub 用户名）：

git clone https://github.com/<this-is-you>/first-contributions.git

这条命令会把first-contributions仓库的全部内容（包括历史提交）下载到你的电脑上，形成一个本地仓库目录。

第三步：创建分支

进入克隆下来的仓库目录（如果终端当前不在该目录）：

cd first-contributions

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

git switch -c add-your-name

其中-c是--create的简写，表示"创建并切换到新分支"。示例：

git switch -c add-emma-maembong

兼容性提示（来自英文原版 README）：如果你的 Git 版本较旧，执行git switch可能报错Git: 'switch' is not a git command. See 'git --help'。此时请改用传统写法：

git checkout -b your-new-branch-name

git checkout -b与git switch -c效果等价，都是"创建分支并切换过去"。

为什么要创建分支？因为开源协作中不应直接在main主分支上改动，独立的分支让每次贡献彼此隔离，也方便维护者审阅。

第四步：修改文件并提交

现在用任意文本编辑器打开仓库根目录下的 Contributors.md 文件，把你的名字添加进去。注意指南的明确要求：

不要加在文件的开头或结尾，放在两者之间的任意位置，然后保存。

保存后回到项目目录，执行git status查看工作区状态，你会看到Contributors.md处于"已修改但未暂存"的状态。

接下来分两步提交：

1. 暂存（stage）修改——用git add把文件加入暂存区：

git add Contributors.md

2. 提交（commit）——用git commit把暂存内容固化为一次提交：

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

其中<your-name>替换成你的名字。-m参数后紧跟提交信息，这样提交时不会弹出文本编辑器。

第五步：推送变更到 GitHub

用git push把本地分支推送到你在 GitHub 上的 Fork 仓库：

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

其中<add-your-name>替换为你第三步创建的分支名。这里的-u（--set-upstream的简写）会在推送的同时建立本地分支与远端分支的追踪关系，之后在这个分支上就可以直接使用git push/git pull而无需再带参数。origin是 GitHub 上你的 Fork 仓库这个远程源的默认名称。

常见报错：认证失败（来自英文原版 README 的排错说明）

推送时可能遇到类似下面的错误：

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 密钥或个人访问令牌（Personal Access Token）完成认证。

同时可以执行git remote -v检查你的远程地址：如果显示的是https://github.com/...形式，可以改用 SSH 地址：

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

否则推送时仍会持续要求输入用户名和密码并最终认证失败。

第六步：发起 Pull Request 供审查

推送成功后，回到你的 GitHub 仓库页面，会看到一个Compare & pull request按钮，点击它，然后提交（Submit）这个 Pull Request。

提交之后，维护者会尽快把改动合并进项目的main分支，合并完成后你会收到一封通知邮件。

到这一步，你就完整走完了fork → clone → edit → pull request这条标准工作流——它正是开源贡献者在日常协作中反复使用的核心模式。

完成之后：庆祝、分享与继续进阶

指南在"接下来去哪里"一节给出了建议：

• 庆祝并分享你的第一次贡献；
• 通过 web 应用提供的易上手项目清单（收录了一批带简单 issue 的项目），继续开始对其他项目的贡献；
• 阅读 docs/additional-material/git_workflow_scenarios/additional-material.md（补充材料索引）学习更多 Git 进阶技巧。

进阶材料：把 Fork 与上游仓库保持同步

第一次贡献只是起点。当你的 Fork 落后于上游（upstream，即 firstcontributions/first-contributions 原仓库）时，需要执行同步操作。这正是开源协作中典型的三角工作流（Triangle Workflows）：上游公共仓库、你的 GitHub Fork、你的本地仓库三方协同。完整的同步流程记录在 docs/additional-material/git_workflow_scenarios/keeping-your-fork-synced-with-this-repository.md，核心步骤为：

# 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 git rebase upstream/main # 5. 推送本地 main 到你的 Fork（origin） git push origin main

如果想一步完成"拉取并合并"上游最新改动到本地当前分支，可以直接：

git pull upstream main

值得注意：文档中强调GitHub Fork 是最后一个被更新的仓库——因为 Pull Request 只能从你的 Fork 发起，所以必须等本地更新完并推送后，Fork 才随之同步。建议每当 GitHub 提示你"落后于上游若干 commit"时就执行上述同步。

进阶材料：Git 基础配置

如果你是第一次用 Git 提交，会遇到身份提示。Git 需要知道"你是谁"，这样协作时才能追溯每次改动出自谁手。git config有三级作用域，详见 docs/additional-material/git_workflow_scenarios/configuring-git.md：

进阶材料：修改提交、合并提交与解决冲突

补充材料索引 docs/additional-material/git_workflow_scenarios/additional-material.md 汇总了一批后续常用的 Git 操作文档，与本文工作流直接相关的包括：

修改最近一次提交（amend）—— 来自 docs/additional-material/git_workflow_scenarios/amending-a-commit.md：

• 仅改提交信息：git commit --amend -m "新的提交信息"（不带-m则会打开编辑器）；
• 忘了把某处小改动并入上次提交：先git add <文件>，再git commit --amend；
• 如果该提交已经推送到了远端，需要用git push --force覆盖远端历史；更安全的做法是用git push --force-with-lease，避免误覆盖他人同时期的改动。

压缩提交（squash）—— 来自 docs/additional-material/git_workflow_scenarios/squashing-commits.md：开源项目审查者常要求把分支上零散的多次提交合并成一条信息清晰的提交。先用git log查看提交历史，再用交互式变基：

git rebase -i HEAD~2

在打开的编辑器里把待合并提交的pick改成squash（或s）即可。

解决合并冲突—— 来自 docs/additional-material/git_workflow_scenarios/resolving-merge-conflicts.md：当不同分支的改动相互冲突（如两人改了同一行、一人删了他人修改的文件等）时，Git 会暂停合并并标记冲突文件。标准处理流程为：

1. 用git status找出 "Unmerged paths" 下列出的冲突文件；
2. 打开文件，识别冲突标记：

   <<<<<<< HEAD 你的改动 ======= 对方分支的改动 >>>>>>> branch-name

   <<<<<<< HEAD与=======之间是当前分支内容，=======与>>>>>>> branch-name之间是传入分支内容；

3. 手动决定保留哪一方或整合双方，并删除所有冲突标记；
4. 对每个解决完的文件执行git add <文件名>；
5. 完成合并提交。

不想用命令行？试试 GUI 教程

指南在文末为不习惯 CLI 的读者提供了完整的图形界面工具教程矩阵（位于docs/gui-tool-tutorials目录），以下链接均已转换为仓库根目录下的相对路径：

这些教程覆盖了 fork、clone、commit、push、PR 的完整同等流程，只是把命令行操作替换为图形界面点击。

结语

回顾整个流程，从点击 Fork 按钮、克隆仓库、创建分支，到把名字写进 Contributors.md、提交推送、最终发出 Pull Request——你完成的不只是一次 Git 操作练习，而是真实参与了一次开源协作。这套fork → clone → edit → pull request工作流在之后的任何开源项目中都会反复出现；配合本文引用的同步上游、修改提交、压缩提交、解决冲突等进阶材料，你已经具备了独立参与开源项目的基础能力。其他语言版本可继续查阅 docs/translations/Translations.md 中列出的全部翻译，仓库内还提供了面向非程序员与更多 CLI 场景的教程（如 docs/additional-material/git_workflow_scenarios/git_workflow_scenarios/additional-material.md 索引下的gitflow、rebase-vs-merge、undoing-a-commit等主题），可按需深入。

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