企业官网建设流程全解析

• 文档
• 教程
• 开源治理

导读

本指南以 first-contributions 项目官方白俄罗斯语版入门文档（docs/translations/README.be.md）为核心骨架，完整讲解新手开发者完成人生第一次开源贡献所需的全部步骤：Fork 仓库、Clone 到本地、创建分支、修改Contributors.md、提交 Commit、Push 到远程、发起 Pull Request，以及贡献合并后如何同步 Fork 与清理分支。读完本文，你将掌握开源协作中最高频的fork → clone → edit → pull request标准工作流，并能利用仓库中配套的进阶 Git 材料解决提交信息修改、合并冲突、提交回退等实战问题。

说明：本文面向中文读者，完整还原原文档的技术步骤，并结合仓库内 README.md、Contributors.md 及 docs/additional-material 等真实文件做源码级补充，所有路径均以仓库根目录为起点。

一、项目背景与文档定位

first-contributions 是一个帮助初学者完成首次开源贡献的教学项目。它的核心理念是：阅读文章和教程可以带来帮助，但没有什么比一次真实、无风险破坏的动手实践更有价值。项目的目的正是"引导新人以正确的方式完成第一次贡献"，并且刻意把流程设计得轻松、低压——越放松，学得越好。

仓库根目录的 README.md 是该项目的英文主文档，而 docs/translations/README.be.md 是其白俄罗斯语（Беларуская мова）翻译版。两者技术骨架完全一致，均由一系列循序渐进的 H2 小节构成，本文严格沿用该骨架并逐节展开、扩充。整个仓库结构（docs 目录）围绕这份指南配套了三种维度的支撑材料：

• 命令行教程：docs/cli-tool-tutorials 下的 GitHub CLI（gh）教程、Git Bash Windows 教程等；
• GUI 工具教程：docs/gui-tool-tutorials 下的 GitHub Desktop、VS Code、GitKraken、IntelliJ IDEA 等图形化工具教程；
• 进阶 Git 场景材料：docs/additional-material/git_workflow_scenarios 下的合并冲突解决、提交修改、Fork 同步等专题文档。

二、准备环境：安装 Git

原文档开篇强调：如果机器上尚未安装 Git，请先完成安装再继续。对于 Debian/Ubuntu 系 Linux 发行版，仓库提供了针对性的安装指南 installing-git-ubuntu.md；Arch Linux 用户则可参考 installing-git-arch.md。安装完成后，可通过git --version验证命令是否可用。

同时需要准备一个 GitHub 账号，并确认终端环境已就绪。

三、Fork 这个仓库（创建独立副本）

在仓库页面顶部点击Fork按钮。这一步会在你自己的 GitHub 账号下创建当前仓库的一份独立副本——也就是说，之后你在副本上的任何操作都不会影响原仓库，这正是"无风险实践"的关键设计。

Fork 的产物位于你自己的账号命名空间下，后续所有提交、推送都发生在这份副本上，直到最终通过 Pull Request 把改动合并回原仓库。

四、Clone 仓库到本地（复制到个人电脑）

4.1 获取复制链接

Fork 完成后，进入你账号下的这份副本仓库，点击Code / Clone按钮，再点击copy to clipboard（复制到剪贴板）图标，复制仓库地址。原文档提示：这个地址就是你 fork 出来的那份仓库的地址，而非原仓库地址。

4.2 执行 Clone 命令

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

git clone "url you just copied"

其中"url you just copied"（去掉引号）就是你刚复制的仓库地址。例如：

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

这里this-is-you是你的 GitHub 用户名。执行成功后，first-contributions仓库的全部内容就被复制到了你的电脑上。

细节提示：英文主文档 README.md 推荐使用 SSH 形式git@github.com:this-is-you/first-contributions.git；若使用 HTTPS 地址在 push 时遇到密码认证被拒绝的错误，可参考 docs/cli-tool-tutorials/github-cli-tutorial.md 中给出的处理办法：用git remote set-url origin git@github.com:your-username/your_repo.git将远程地址切换为 SSH 形式。

五、创建分支（Branch）

5.1 进入项目目录

cd first-contributions

5.2 用 checkout 创建分支

原文档使用经典的git checkout命令创建分支：

git checkout -b <add-your-name>

例如：

git checkout -b add-alonzo-church

命名约定说明：语法上并不强制分支名包含add字样，但加上它是有意义的——它直白地表达了这个分支的用途：把名字加入贡献者列表。

版本兼容提示：较新版本的 Git 推荐使用语义更清晰的git switch命令，即git switch -c your-new-branch-name（见 README.md 与 github-cli-tutorial.md）。如果执行git switch时报错 "Git:switchis not a git command"，说明本地 Git 版本较旧，此时回退使用git checkout -b即可。

六、修改文件并提交 Commit

6.1 编辑 Contributors.md

用文本编辑器打开仓库根目录的 Contributors.md 文件，把你的名字写入其中并保存。该文件当前已有数千条贡献者记录（每行格式为- 名字或带个人备注），按原文档建议，把你的名字加在文件中间任意位置，而不是开头或结尾，以避免与现有贡献者条目产生冲突（这也为后面练习"合并冲突解决"埋下伏笔）。

6.2 查看变更状态

回到项目目录执行：

git status

你会看到Contributors.md被标记为已修改（modified）。

6.3 暂存变更

用git add把改动加入暂存区：

git add Contributors.md

6.4 提交 Commit

用git commit创建一次提交：

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

把<your-name>替换成你的名字。这一提交被记录在你本地的新分支上，尚未进入远程。

补充：如果你在首次 commit 时收到 "*** Please tell me who you are" 提示，说明 Git 尚未配置用户身份，需先执行git config --global user.email "you@example.com"与git config --global user.name "Your Name"。更完整的配置层次说明（全局配置、仓库配置、命令行临时配置及其优先级）参见 configuring-git.md。

七、把变更 Push 到 GitHub

提交完成后，用git push把本地分支推送到远程（你 fork 的仓库）：

git push origin <add-your-name>

将<add-your-name>替换为你之前创建的分支名。推送后，改动就到了你 GitHub 账号下的 fork 副本中。

提示：Git 较新版本推荐首次推送时加上-u参数建立本地分支与远程分支的追踪关系：git push -u origin your-branch-name（见 github-cli-tutorial.md），此后该分支可直接使用git push推送。

八、提交 Pull Request 等待审查

回到你 GitHub 账号下的 fork 仓库页面，会看到一个Compare & pull request按钮，点击它。随后进入 Pull Request 创建页面，确认改动内容无误后，点击提交按钮正式发起 Pull Request。

项目维护者会审查并尽快将你的改动合并进主分支（main branch）。一旦合并，你会收到一封通知邮件。

这一小节是整个工作流的"验收环节"：前面的所有操作——fork、clone、branch、commit、push——最终都汇聚到这一份 PR 上，由维护者审阅后合入项目主线。

九、同步你的 Fork（保持与原仓库一致）

原文档强调：你的 PR 被合并后，你 fork 仓库的主分支并不会自动更新。此时需要按以下步骤把上游仓库（原仓库）的新内容同步下来。仓库配套专题文档 keeping-your-fork-synced-with-this-repository.md 对这一"三角工作流"（上游公共仓库 → 你的本地仓库 → 你的 fork）有更详尽的图解说明。

9.1 切回主分支

git checkout master

9.2 添加上游远程地址

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

这一步告诉 Git：在指定地址存在该项目的另一个版本，我们称之为upstream（上游），并把它视为主版本来源。

9.3 拉取上游最新内容

git fetch upstream

git fetch会把上游仓库的所有新提交拉到本地，但不会自动合并到当前分支。

9.4 变基合并到本地主分支

git rebase upstream/master

git rebase将你本地 master 分支的提交"重放"到上游最新提交之上，使本地主分支与上游完全同步。

9.5 推送本地主分支到你的 Fork

git push origin master

注意这里 push 的是名为origin的远程（你自己的 fork）。推送完成后，你 GitHub 上的 fork 主分支也同步到了最新状态。

快捷方式：如需一次性完成"拉取并合并"，可直接执行git pull upstream main（上游主分支名为main时）。判断同步时机也很简单：每当你的 fork 页面提示"当前分支落后于上游若干提交"（a few commits behind）时，就应执行上述同步流程。

9.6 删除已合并的功能分支

同步完成后，你的<add-your-name>分支使命已经完成，可以清理掉。本地删除：

git branch -d <add-your-name>

远程（fork 上）删除：

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

原文档特别说明：删除分支并非强制，但该分支的名称体现了它非常特定的用途，生命周期本就应该短暂。

十、使用其他工具完成相同流程

如果你不习惯命令行，原文档提供了完整的图形化工具教程矩阵，覆盖同样完整的fork → clone → edit → pull request流程，均可从仓库根目录路径访问：

此外，偏爱纯终端的开发者可以学习 github-cli-tutorial.md：安装 GitHub CLI 后执行gh auth login登录，用gh repo fork firstcontributions/first-contributions一键完成 fork 并选择同时 clone，最后用gh pr create --repo firstcontributions/first-contributions直接从命令行发起 Pull Request，全程无需打开浏览器。

十一、进阶：合并冲突与提交修订（实战补充）

贡献者多了之后，第 6.1 节提到的"在文件中间插入名字"恰恰是最容易引发合并冲突的场景。仓库为此准备了专门的进阶材料（索引见 additional-material.md），这里提炼与首次贡献最相关的两个主题：

11.1 解决合并冲突

当两个分支改动了同一文件的同一行、或一方删除的文件另一方仍在修改时，Git 无法自动合并，会暂停并标记冲突文件。解决流程（详见 resolving-merge-conflicts.md）：

1. git status找出 "Unmerged paths" 下的冲突文件；
2. 打开冲突文件，定位<<<<<<< HEAD（当前分支的改动）、=======（分隔线）与>>>>>>> branch-name（对方分支的改动）三组标记；
3. 手工决定保留哪边或合并两边内容，并删除所有冲突标记；
4. 对每个已解决的文件执行git add <filename>；
5. 最后git commit -m "Resolved merge conflicts"完成合并。

辅助命令：git mergetool可启动图形化合并工具（需预装 Meld、KDiff3 等）；git merge --abort可放弃本次合并；养成git pull origin main及时同步、每个功能用独立分支的习惯可显著减少冲突。

11.2 修改最近一次提交

若 commit 信息写错或漏改了一行，可执行git commit --amend -m "新的提交信息"直接改写最近一次提交；不加-m则会打开文本编辑器修改信息。若该提交已 push 到远程，改写会导致本地与远程历史分叉，此时需用git push --force覆盖远程历史——但这是危险操作，会丢弃他人同时期的改动，更安全的替代是git push --force-with-lease（详见 amending-a-commit.md）。

11.3 撤销本地提交

git reset可将暂存区重置到最近一次提交（工作区改动保留，可重新提交）；git reset <file>只把指定文件移出暂存区；git reset --hard HEAD~2则会连同工作区改动一起回退两个提交、并从历史中移除这两次快照。切记：git reset --hard只适用于尚未推送到共享仓库的本地提交（详见 undoing-a-commit.md）。

十二、接下来做什么

完成上述全部流程，你就已经走完了一次标准的fork → clone → edit → pull request开源贡献闭环。如果想继续练习或寻找更多"新手友好"的开源任务，可以：

• 阅读 how-to-contribute-to-open-source-projects.md 与 Useful-links-for-further-learning.md，系统了解参与开源的通用方法论与学习资源；
• 对照 Translations.md 了解该项目覆盖的全部语言版本，感受开源社区全球协作的氛围；
• 回到仓库根目录的 Contributors.md，看看自己的名字是否已与其他数千名贡献者一起出现在列表中。

结语

本指南完整继承了 docs/translations/README.be.md 的全部技术步骤，并以仓库内真实文件（Contributors.md、README.md、进阶材料目录）为佐证进行了逐层扩充。从 Fork 到 Pull Request，再到合并后的 Fork 同步与分支清理，这套工作流是参与任何开源项目都会反复使用的基本功。现在，打开终端，开始你的第一次贡献吧。

• 文档
• 教程
• 开源治理