企业官网建设流程全解析

使用 Visual Studio Code 完成首次开源贡献：first-contributions 全流程图文指南

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

导读

本文基于开源仓库 first-contributions 的官方教程，完整讲解如何只使用 Visual Studio Code（VS Code）的图形界面完成一次真实的开源贡献：从 Fork 上游仓库、克隆到本地、创建分支、修改Contributors.md，到提交、推送并创建 Pull Request（PR）的完整链路。读完本文，即使你完全不熟悉命令行 Git，也能在 VS Code 中独立走完fork → clone → edit → pull request这一开源协作标准流程，并了解每一步背后的 Git 原理与常见的坑。

为什么选择 VS Code 完成首次贡献

很多新手在第一次参与开源项目时感到紧张——协作场景下犯错是难免的，而 open source 的本质恰恰是协作与共同进步。本项目（first-contributions）的宗旨正是为初学者提供引导，降低首次贡献的门槛，让"动手实践"代替"只看教程"。

VS Code 内置了完整的 Git 图形化集成，你可以在界面里完成克隆、建分支、暂存、提交、推送的全过程，而无需记忆 Git 命令行。本教程对应的英文原版见 github-windows-vs-code-tutorial.md，仓库主 README 中的命令行版流程见 README.md，两者操作一一对应，可互为参考。

环境说明：原版教程基于 Windows 10 机器上的 VS Code（版本 1.27.2）录制。教程中使用的键盘快捷键可能因操作系统（macOS/Linux）或键盘语言（UK、DE 等）而不同。你可以在 VS Code 的命令面板中搜索 "shortcut" 查看自己机器上的完整快捷键列表。

第一步：Fork 本仓库

Fork（叉）是把别人的仓库复制一份到你自己 GitHub 账户下的操作。在 first-contributions 仓库页面右上角点击Fork按钮，即可在你的 GitHub 账户中生成一份该仓库的副本。

Fork 背后的协作模型值得理解：GitHub 会持续追踪"你的仓库"与"你 Fork 的源头仓库"之间的关系，你可以把自己的 Fork 当作一份工作副本（working copy）。大多数顶层仓库（即不是从其他仓库 Fork 来的仓库）通常只有一个小型核心团队拥有直接提交（commit）权限；其余所有贡献者都必须先 Fork 仓库、在 Fork 中做出修改，再通过 Pull Request 请求把自己的改动合并回顶层仓库。如果顶层仓库管理员认可你的改动，合并后你的名字就会出现在项目贡献者列表里。

第二步：克隆你的仓库到本地

复制仓库 URL

下一步是把你的 Fork 克隆到本地机器，这样才能开始编辑。点击你 Fork 仓库页面上的Code按钮，再点击复制到剪贴板图标，获取仓库 URL。

⚠️ 新手最常见的错误：很多人会克隆"你 Fork 的源头仓库"而不是"你自己的 Fork 仓库"。克隆前务必检查浏览器地址栏，确保 URL 属于你自己的账户。

在 VS Code 中执行 Git: Clone

打开 VS Code，首先会看到欢迎页。按F1打开命令面板（输入框里已经预置了>提示符；也可以按CTRL-P再输入>字符进入）。在输入框中输入git clone（只输入git或clone也能模糊搜索到），从下拉列表中选择Git: Clone并回车。

随后粘贴你刚复制的仓库 URL 并回车，VS Code 会弹出文件资源管理器，让你选择仓库在本地磁盘上的存放位置。

重要：务必确认粘贴的是 Fork 后的仓库地址，而不是原仓库地址，否则后续无法推送你的改动。

克隆完成后，VS Code 右下角会弹出状态提示。你可以直接点击对话框中的按钮，在 VS Code 中打开这个克隆下来的仓库（此时它已经是本机上的一个普通文件夹）。

底层原理：命令面板是 VS Code 所有内置命令的统一入口，Git: Clone内部执行的实际上就是git clone <url>。主仓库 README 中的命令行流程（README.md）使用git clone "url you just copied"完成同样的动作，例如git clone git@github.com:this-is-you/first-contributions.git（把this-is-you替换为你的 GitHub 用户名）。

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

按F1再次打开命令面板，输入branch，选择创建分支（create branch）命令，输入新分支名称，例如add-your-name（教程原例为add-david-kroell），回车即可创建。分支创建后会被自动检出（checkout），也就是说你接下来的所有改动都会落在这个新分支上，而不是main主分支上。

为什么必须开分支？直接在主分支上提交改动，会让主分支变得混乱；而基于独立分支提交的改动互不影响、可单独被请求合并，这是 Pull Request 协作模型的基础。命令行的等价操作是git switch -c your-new-branch-name（旧版 Git 用git checkout -b your-new-branch-name），README 中对此有完整的对照说明。

第四步：在 Contributors.md 中写入你的名字

打开仓库根目录下的 Contributors.md，在文件的任意位置（教程建议放在中间而非开头或结尾）添加你的名字。该文件使用GFM（GitHub Flavored Markdown）语法——即 GitHub 特有的一种 Markdown 方言。

文件里现有条目就是最好的模板，例如典型的条目格式为：

- 你的名字

建议：直接复制其他贡献者的一行，再把自己的名字和主页地址替换进去，这样能保证语法正确——Markdown 语法有时相当挑剔（例如缺少方括号或括号不配对都会导致链接失效）。从该文件的实际内容可以看到，绝大多数贡献者都保持了- Name的统一格式，部分条目还会在行尾附上个人寄语。修改完成后务必保存文件，VS Code 才会感知到文件变动。

第五步：提交（Commit）并推送（Push）改动到 GitHub

暂存并提交

VS Code 左侧竖排菜单有 5 个图标，点击其中的源代码管理 / Source Control图标（快捷键Ctrl + Shift + G）。此时资源管理器会列出自上次提交以来所有被修改的文件。

把鼠标悬停在变更文件上，点击出现的+（加号）即可把该文件暂存（stage）——这一步等价于命令行的git add Contributors.md。然后在上方输入框里填写提交信息，例如Add your-name to Contributors list（把your-name替换成你的名字），点击输入框上方的对勾（✓），改动即提交到本地仓库，等价于git commit -m "Add your-name to Contributors list"。

推送分支到 GitHub

提交后的改动还只存在于本地。点击源代码管理面板右上角的三个点图标（⋯），在弹出的菜单中选择发布分支（Publish Branch），VS Code 会弹出对话框让你输入 GitHub 凭据（凭据可能来自浏览器登录态、GitHub 扩展或 Git 凭据管理器）。认证通过后，你的分支连同提交就会被推送到 GitHub 上的 Fork 仓库，等价于命令行的git push -u origin your-branch-name（-u用于建立本地分支与远端分支的追踪关系）。

第六步：提交 Pull Request 供审核

至此你的改动已经完整存在于你的 Fork 仓库中，但仍未进入原项目。现在需要向顶层仓库的管理员提交合并请求。

回到 GitHub 上你的 Fork 仓库页面，会看到新分支通知旁边出现一个Compare & pull request（比较并创建拉取请求）按钮，点击它，再点击Create pull request提交。请求提交后，上游仓库维护者会收到通知并审核你的改动；一旦合并，你就会收到一封邮件通知，你的名字也随之进入 Contributors.md 的贡献者列表——这就是 open source 协作中最经典的一次循环。

第七步：完成之后——标准工作流回顾与进阶学习

恭喜！你刚刚完成了开源贡献者最常遇到的fork → clone → edit → PR标准工作流。这套流程不只在 first-contributions 有效，几乎所有基于 GitHub 的开源项目都遵循同样的协作模式，学会一次即可迁移到任何项目。

进阶阅读

仓库中提供了丰富的进阶材料，全部位于 docs/additional-material/git_workflow_scenarios/ 目录下，索引见 additional-material.md。其中与你本次实践直接相关的高频场景包括：

• 保持你的 Fork 与上游同步：很多贡献者会同时参与同一项目，你的 Fork 会逐渐落后于原仓库，本文教你如何拉取上游更新；
• 解决合并冲突：当你的改动与其他人改动了同一区域时会出现冲突，这是每位贡献者迟早要面对的必修课；
• 修改最近一次提交（Amending a commit）：提交信息写错了或漏改了文件，可在推送前修改最近的提交；
• 压缩提交（Squashing commits）：当审核者要求把多次提交合并为一次有意义的提交时使用；
• 合并后删除分支：PR 合并后清理本地与远端的临时分支；
• 存储凭据（Storing credentials）：配置 Git 凭据持久化，避免每次推送都重复输入密码（注意遵循你所在组织的安全规范）；
• 配置 Git（Configuring git）：设置用户名、邮箱等全局配置；
• Gitflow 工作流：了解更完整的分支管理模型。

常见问题速查

• 克隆错了仓库：如果你克隆的是原仓库而非自己的 Fork，推送会因没有写权限而失败。重新按第二步流程，用你自己的 Fork URL 克隆即可。
• 认证失败：GitHub 已于 2021 年 8 月起移除密码认证，推送时需要使用个人访问令牌（Personal Access Token）或 SSH 密钥。可用git remote -v检查远端地址，必要时用git remote set-url origin切换为 SSH 地址（详见 README 中的故障排查段落）。
• 快捷键无效：不同操作系统和键盘布局下快捷键不同，在命令面板搜索 "shortcut" 即可查看和修改你的快捷键绑定。

最后，把你的首个贡献分享给朋友，然后去参与更多真实项目吧——你现在已经掌握了开源协作的入场券。

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