企业官网建设流程全解析

• 文档
• 教程
• 开源治理

导读

本指南围绕 first-contributions 仓库的经典入门教程（对应文档 docs/cli-tool-tutorials/github-cli-tutorial-Hindi.md）展开，面向第一次参与开源贡献的新手，完整讲解在 Windows 上使用 Git Bash 命令行完成fork -> clone -> edit -> pull request标准工作流的每一步。读完本文，你将掌握 fork 仓库、克隆到本地、创建分支、修改Contributors.md、提交并推送更改、最终提交 Pull Request（PR）的全套操作，并能对照仓库源码与配套进阶文档继续深化 Git 技能。

项目背景：为什么要做第一次贡献

首次做一件事总是困难的，尤其是协作开发时，害怕犯错是人之常情。但开源的本质就是协作与共同进步。first-contributions 项目的核心目标，正是"简化并引导初学者完成第一次贡献"——正如项目根目录 README.md 开头所写的：This project aims to simplify and guide the way beginners make their first contribution。

阅读文章、观看教程固然有帮助，但真正动手、在"不搞砸任何东西"的前提下完成一次真实贡献，才是最有效的学习方式。本项目把这次练习设计得足够简单：你只需要在一个叫Contributors.md的贡献者名单文件里加上自己的名字，就能完整体验一次真实的开源协作流程。仓库根目录下的 Contributors.md 目前已有数千位贡献者，其中大量记录正是新手们按本教程提交的第一个 PR。

环境准备：安装 Git 与 Git Bash

开始之前，请确认你具备以下条件：

1. Git 已安装：Git 是版本控制工具，所有后续命令都依赖它。若尚未安装，请前往 Git 官方下载页面选择对应 Windows 安装包完成安装。
2. GitHub 账户：fork 与提交 PR 都需要 GitHub 账户。
3. （Windows 用户）Git Bash：如果机器上没有 Git Bash，请随 Git 一起安装（Git for Windows 默认自带 Git Bash 终端）。本教程全程在 Git Bash 中执行命令，它是 Windows 下体验最接近 Linux/Mac 终端的命令行环境，你下载安装完成后打开的 Git Bash 界面即为操作入口。

进阶补充：本教程对应的英文原版 docs/cli-tool-tutorials/github-cli-tutorial.md 还介绍了 GitHub 官方命令行工具gh（GitHub CLI），它允许你在终端中完成 fork、创建 PR 等原本需要在网页上操作的动作。如果你倾向于"一切都在终端里完成"，可以在安装 Git 后额外安装gh工具，并先执行gh auth login完成命令行登录授权，后续小节会给出对应的gh命令。

工作流全景：fork -> clone -> edit -> pull request

整篇教程围绕一个在开源社区中最常见、你今后作为贡献者会反复遇到的标准流程展开：

理解这个"三角"协作结构很关键：上游公共仓库（first-contributions）、你自己的 GitHub fork、本地机器上的仓库副本，三者共同构成开源协作的基本形态，具体说明见 docs/additional-material/git_workflow_scenarios/keeping-your-fork-synced-with-this-repository.md。

第一步：Fork 这个仓库

Fork 即"复刻"：在 first-contributions 仓库页面右上角点击Fork按钮，GitHub 会在你的账户下生成一份该仓库的完整副本。这份副本完全归你所有，你可以在上面随意修改而不影响原始仓库。

如果你安装了 GitHub CLI，也可以完全在终端里完成：

gh repo fork firstcontributions/first-contributions

重要提示：执行gh repo fork时，命令会询问你是否同时把仓库克隆到本地，请选择yes（选了 yes 可以跳过下面手动的 clone 步骤）。

第二步：Clone 仓库到本地

现在把这份 fork 克隆到你的机器上。

重要：不要克隆原始仓库，而是克隆你自己的 fork。请回到你的 GitHub 账户，打开刚才 fork 出来的仓库，点击绿色的Code按钮，复制其中的仓库地址字符串。

打开你下载好的 Git Bash 应用，先用cd命令切换到你想保存项目的文件夹：

cd <folder>

然后使用刚才复制的地址执行克隆命令：

git clone <repo-url>

例如（this-is-you换成你的 GitHub 用户名）：

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

克隆完成后，进入仓库目录并打开编辑器：

cd first-contributions

第三步：创建你的专属分支

创建分支是 Git 协作的关键习惯：分支让你在不干扰主干（main）的前提下安全工作。执行下面这条命令，它不仅能创建分支，还会自动切换到新分支上：

git checkout -b <branch-name>

分支名建议用add-你的名字的格式，例如add-james-smith。如果add-james-smith这个分支已存在，可以换一个更独特的名字，比如add-james-smith-2024。

版本说明：如果你的 Git 版本较新，也可以使用等价的git switch -c <branch-name>命令。README 主流程（见 README.md）默认使用git switch -c，并提示：若出现 "switchis not a git command" 报错，说明 Git 版本过旧，请改用git checkout -b。两种写法效果完全相同，任选其一即可。

第四步：修改 Contributors.md 并提交

添加你的名字

用文本编辑器打开仓库根目录下的Contributors.md文件，滚动到文件中间位置，把名字加在文件开头和末尾之间的任意位置，保存文件。

文件中的每一行遵循 Markdown 链接格式，例如 James Smith 应添加：

[James Smith](https://github.com/jamessmith)

参考 Contributors.md 中真实存在的条目，可以看到大量这样的记录，例如- [Sachin Kumar](https://github.com/ST-SACHIN-KUM)、- [Vanshi Patel](https://github.com/VAP2999)。有些人还会在名字后附带一句留言（如 "My first open-source contribution!"），这完全自由。

查看改动状态

回到 Git Bash，在项目目录下执行：

git status

Git 会以红色列出被修改的文件（此处为Contributors.md），表示你的改动尚未被跟踪。

暂存改动

把改动加入暂存区（staging area）：

git add file-name

此处应为：

git add Contributors.md

提交改动

用带-m参数的 commit 命令写入提交信息：

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

记得把your-name替换成你自己的名字，例如git commit -m "Add James Smith to Contributors list"。

验证提交

如需确认提交是否成功，可运行：

git log --oneline

输出会列出最近一次提交及其简短哈希与提交信息，例如：

a1b2c3d Add James Smith to Contributors list

第五步：推送改动到 GitHub

本地提交完成后，把分支推送到你的 GitHub fork：

git push origin <branch-name>

其中<branch-name>替换为第三步创建的分支名。如果希望同时建立本地分支与远程分支的跟踪关系（便于以后直接git push），可以使用带-u的写法：

git push -u origin <branch-name>

推送报错排查：认证问题

如果你在推送时遇到如下错误：

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/'

说明当前 Git 版本已不再支持通过 HTTPS 口令（密码）认证，需要改用 SSH 密钥或 personal access token。README 主文档（见 README.md）给出了详细处理建议：

1. 生成 SSH 密钥并配置到你的 GitHub 账户（参照 GitHub 官方 SSH 配置文档）；
2. 用git remote -v检查你的远程地址，若显示的是 HTTPS 形式（https://github.com/your-username/your_repo.git），请将其切换为 SSH 形式：

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

否则推送时仍会反复提示输入用户名和密码并认证失败。

第六步：提交 Pull Request 供审核

改动推送到远程后，回到你的 GitHub 仓库页面，你会看到醒目的Compare & pull request按钮，点击它。

进入创建 PR 的页面后，确认对比方向（base为上游的 main 分支，compare为你刚推送的分支），填写标题与说明，然后提交 Pull Request。仓库维护者收到 PR 后会进行审核，一旦通过审核，你的改动就会被合并进 first-contributions 的 main 分支，届时你会收到合并通知邮件。

如果你安装了 GitHub CLI，提交 PR 可以完全在终端完成——在本地仓库目录执行：

gh pr create --repo firstcontributions/first-contributions

按提示填写标题与正文后即可创建 PR；之后可用gh status实时查看你相关 PR 的状态。

收尾：同步 fork 与进阶 Git 技能

到这里，你已经完成了标准开源贡献流程！接下来可以继续深入：

• 保持 fork 与上游同步：随着越来越多贡献者的改动被合并，你的 fork 会逐渐落后于上游仓库。GitHub 页面会提示你 "behind" 若干提交。完整同步流程（添加upstream远程、git fetch upstream、git rebase upstream/main、git push origin main，或一步到位的git pull upstream main）见 docs/additional-material/git_workflow_scenarios/keeping-your-fork-synced-with-this-repository.md，其中还解释了"三角工作流"的协作原理。
• 进阶 Git 技术索引：本文档的姊妹篇 docs/additional-material/git_workflow_scenarios/additional-material.md 汇总了十余个高频实战主题，包括：
  • 修改最近一次提交（amend）
  • 配置 Git 用户信息
  • 解决合并冲突
  • 压缩多个提交
  • 回退已推送的提交 与 撤销本地提交
  • 删除本地分支 等
• 尝试其他工具教程：如果不习惯命令行，可以改用图形化工具完成同样的流程，相关教程（GitHub Desktop、VS Code、GitKraken、IntelliJ IDEA、Sourcetree 等）的入口与链接均收录在根目录 README.md 的 "Tutorials Using Other Tools" 表格中，中文版本参见 docs/translations/README.zh-cn.md。

结语

恭喜！你刚刚完成了一次真实的开源贡献。回顾整个流程：fork在云端复制仓库 →clone拉到本地 → 创建独立分支 → 编辑Contributors.md→add/commit提交 →push推回云端 →pull request交给上游审核，这正是所有开源贡献者的日常。把这次的经验应用到其他项目上，你会发现开源协作并不神秘——它就是一群人通过这套规范流程，安全、有序地把各自的小改进汇集成大项目的过程。

• 文档
• 教程
• 开源治理