企业官网建设流程全解析

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 的祖鲁语（isiZulu）翻译版教程 README.zul.md 为骨架，系统讲解初学者如何通过fork → clone → edit → pull request四步标准流程完成第一次开源贡献。本指南覆盖 Git 环境准备、分支管理、提交与推送、Pull Request 提交，以及合并冲突、提交修正、fork 同步等进阶 Git 操作，阅读后你将具备独立向任意开源项目提交代码贡献的完整实战能力。

项目背景与本教程的定位

first-contributions 项目的定位非常明确：帮助开源新手迈出贡献的第一步。项目根目录的 README.md 用一句话点明了核心目标："This project aims to simplify and guide the way beginners make their first contribution"（简化并引导初学者完成第一次贡献）。

为了让不同语言背景的开发者都能无障碍学习，项目在 docs/translations 目录下维护了上百种语言的翻译版本，README.zul.md 就是面向祖鲁语使用者的完整教程。与其他翻译版一样，它完整保留了英文原版的全部操作步骤与命令示例——这意味着这套工作流是经过项目长期验证、可以直接照做的标准流程。

本教程的实操产物是向仓库根目录的 Contributors.md 贡献者名单文件追加自己的名字。该文件目前已有数千行条目（累计超过 5900 行），正是由一代代新手通过本文描述的流程累积而成的，是这套流程真实可用的直接证据。

环境准备：确保本机已安装 Git

动手之前，先确认你的电脑上是否安装了 Git。在终端执行：

git --version

如果系统提示找不到该命令，说明尚未安装。不同操作系统有对应的安装方式，可参考仓库中整理的安装指南：

• Ubuntu 系：installing-git-ubuntu.md
• Arch 系：installing-git-arch.md

如果你对命令行完全不熟悉，也可以跳过本节，直接使用文末列出的 GUI 工具教程（如 GitHub Desktop），效果相同。

第一步：Fork 本仓库

Fork（复刻）是 GitHub 提供的一种仓库复制机制。点击仓库页面右上角的 Fork 按钮，GitHub 就会在你自己的账户下生成一份该仓库的完整副本。

这一操作的关键意义在于：Fork 出来的副本归你所有，你可以在上面任意修改、创建分支、推送代码，而不会影响原始仓库（上游仓库）的任何内容。后续所有操作都基于你的这份 Fork，而不是原始仓库——请务必记住这一点，因为它决定了整套工作流的合法性：你只能从自己的 Fork 发起 Pull Request。

第二步：Clone 克隆仓库到本地

Fork 完成后，进入你自己账户下的 first-contributions 仓库页面：

1. 点击页面上的 Code 按钮；
2. 复制仓库 URL 到剪贴板；
3. 打开终端，执行 clone 命令：

git clone "url you just copied"

其中url you just copied替换为你刚才复制的地址（去掉引号）。例如，假设你的 GitHub 用户名为this-is-you：

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

这条命令会把 GitHub 上的仓库内容完整下载到本地电脑，形成一份与远程仓库完全一致的工作副本。从此，你就有了一套"远程 Fork + 本地仓库"的双重操作空间。

第三步：创建专属分支

Clone 完成后，先进入仓库目录：

cd first-contributions

然后创建一个属于本次贡献的分支。教程中推荐使用git checkout命令：

git checkout -b <add-你的名字>

例如，贡献者名为 Adam Kowalski，可以创建：

git checkout -b add-adam-kowalski

关于分支命名，教程特别给出了两条实用建议：

• 分支名不强制包含add前缀；
• 但加上add是合理的习惯，因为该分支的使命就是把你的名字"添加"到贡献者列表，见名知意。

需要说明的是，较新版本的 Git（2.23+）提供了语义更清晰的新命令git switch，根目录 README.md 的英文原版教程即采用git switch -c <新分支名>的写法。两条命令等价，若你的 Git 版本较旧、执行git switch报错，就退回使用git checkout -b。

第四步：修改文件并提交

用任意文本编辑器打开仓库根目录的 Contributors.md，把你的名字添加进去。教程给出了三条纪律：

• 不要把名字加在文件开头或结尾；
• 放在文件中间任意位置即可；
• 添加后保存文件。

建议照抄仓库中已有的条目格式- 名字，例如- [Antonio Campello](https://github.com/antoniocampello)，便于维护者审阅。

保存后，在仓库目录下执行git status检查工作区状态，你会看到Contributors.md显示为已修改（modified）状态。

接下来把改动加入暂存区：

git add Contributors.md

然后提交，提交信息中把<你的名字>替换为真实姓名：

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

例如：

git commit -m "Add Adam Kowalski to Contributors list"

至此，你的改动已作为一条本地提交记录，挂在刚才创建的add-adam-kowalski分支上。

第五步：推送改动到 GitHub

将本地分支推送到你自己的远程 Fork：

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

把<add-your-branch-name>替换为之前创建的分支名，例如：

git push origin add-adam-kowalski

推送失败：认证错误的排查与修复

新手推送时最常见的错误是认证失败。如果你看到类似下面的报错：

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 停用的密码认证方式（GitHub 已全面转向 token / SSH 密钥认证）。此时应改用 SSH 方式连接。先检查当前远程地址配置：

git remote -v

如果输出显示远程地址是 HTTPS 形式：

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

需要将远程地址切换为 SSH 形式：

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

同时，为本机配置好 SSH 公钥并添加到 GitHub 账户（生成与配置步骤参见仓库内的 storing-credentials.md 及英文 README 中引用的 GitHub 官方文档）。否则推送时仍会被要求输入用户名和密码，导致同样的认证错误。

第六步：提交 Pull Request

推送成功后，回到 GitHub 上你自己的 Fork 页面，页面顶部会出现一个醒目的Compare & pull request按钮，点击它：

1. 确认对比范围：base 仓库为原始仓库的 main 分支，compare 分支为你刚推送的分支；
2. 点击Create pull request，填写标题与描述后正式提交。

提交后，仓库维护者会收到通知，并将你的改动合并进 main 分支。合并成功后，你会收到一封邮件通知。至此，一次完整的开源贡献闭环完成。

第七步：后续进阶——让 Fork 与上游保持同步

完成第一次贡献后，你必然会遇到一个问题：上游仓库持续有新的提交，你的 Fork 和本地仓库会逐渐落后。仓库在 keeping-your-fork-synced-with-this-repository.md 中详细讲解了这一场景。

开源协作中典型的"三角工作流"（Triangle Workflows）涉及三个仓库：

1. 上游公共仓库（本项目的原始仓库）；
2. 你在 GitHub 上的 Fork；
3. 你本地的仓库。

同步的核心思路是：先让本地仓库与上游对齐，再把本地仓库推送到你的 Fork。

首先确保本地处于 main 分支：

git status # 查看当前所在分支（第一行输出） git checkout main # 若不在 main 分支则切换

然后把上游仓库添加为名为upstream的远程：

git remote add upstream https://github.com/firstcontributions/first-contributions.git

拉取上游最新内容：

git fetch upstream

将上游 main 分支的更新合并到本地 main（教程采用 rebase 方式）：

git rebase upstream/main

最后把同步后的本地 main 推送到你的 Fork（远程名为origin）：

git push origin main

如果想一步完成"拉取并合并"两个动作，可以直接使用：

git pull upstream main

建议在 GitHub 提示"你的 Fork 落后于上游若干提交"时，就执行一次上述同步流程。

更多进阶 Git 场景

围绕首次贡献可能遇到的各种 Git 操作，仓库在 docs/additional-material/git_workflow_scenarios 目录下提供了系统化的专题文档，入口为 additional-material.md。几个与贡献者高度相关的场景：

• 修正最近一次提交（amending-a-commit.md）：如果提交信息有拼写错误，或忘了把某个改动包含进最近一次提交，可以执行git commit --amend -m "新的提交信息"；若该提交已推送远程，则需在 amend 后用git push --force覆盖远程历史。文档特别警告：force push 会覆盖远程上他人的改动，若仅想安全更新自己分支，优先使用--force-with-lease。
• 解决合并冲突（resolving-merge-conflicts.md）：当多个贡献者修改同一文件的同一行、或一人删除文件另一人继续修改时，Git 无法自动合并，会在文件中插入<<<<<<< HEAD、=======、>>>>>>> branch-name三类冲突标记。处理流程为：用git status找出处于 "Unmerged paths" 下的文件 → 手动编辑取舍 → 删除冲突标记 →git add <文件名>标记已解决 →git commit完成合并。
• 压缩提交（squashing-commits.md）：当维护者在 PR 评审中要求把多个提交合并为一个信息完整的提交时，可使用交互式 rebase 完成。
• 撤销提交（undoing-a-commit.md、reverting-a-commit.md）：分别面向本地未推送提交的撤销与已推送提交的回滚场景。
• 删除文件与分支（removing-a-file.md、removing-branch-from-your-repository.md）：覆盖提交前删除文件、PR 合并后清理分支的常规操作。
• .gitignore 与凭证管理（creating-a-gitignore-file.md、storing-credentials.md）：前者保证只提交必要文件，后者讲解凭据安全存储，需遵循所在机构的安防策略。

不习惯命令行？试试 GUI 工具教程

README.zul.md 明确提示：如果不习惯命令行，可以使用 GUI 工具完成同样流程。仓库在 docs/gui-tool-tutorials 目录下为六大主流工具提供了图文教程，操作路径与命令行版完全对应（fork → clone → 建分支 → 改文件 → PR）：

以 GitHub Desktop 教程为例，其核心提示与命令行版一致："DO NOT CLONE THE ORIGINAL REPO. Go to your fork and clone it"（不要克隆原始仓库，去你的 Fork 克隆），进一步印证了"一切操作基于自己的 Fork"这条贯穿全流程的核心原则。

总结：一次贡献，一生受用的标准工作流

本教程表面上只教你往贡献者名单里加一个名字，但正如 README.zul.md 结尾所言，你完成的是fork → clone → edit → pull request这一"贡献者日后会反复遇到的标准工作流"。它涵盖了 Git 分支隔离、暂存提交、远程推送、PR 评审协作的全部核心环节——掌握它，就等于拿到了进入任何开源项目的入场券。完成第一次贡献后，你可以通过仓库整理的项目清单寻找更多带 easy 标签的入门 Issue，把这套流程持续实践下去。

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