用 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 项目官方文档 github-windows-vs-code-tutorial_pt_br.md（巴西葡萄牙语版）及其英文原版 github-windows-vs-code-tutorial.md 编写。该项目旨在简化并引导初学者完成人生第一次开源贡献，如果你不习惯命令行，官方 README 也明确建议参考这套基于 GUI 工具的教程（见 README.md）。读完本文，你将完全使用 Visual Studio Code 图形界面，零命令行完成fork → clone → 创建分支 → 修改文件 → commit → push → Pull Request的完整贡献流程。

为什么用图形界面完成第一次贡献

万事开头难，尤其是协作时犯错总会让人不适，但开源的本质就是协作与共同工作。阅读文章和观看教程固然有帮助，但远不如在不搞砸任何东西的前提下亲自动手一次。first-contributions 项目提供的就是一条"安全练手"路径：它不要求你先掌握全部 Git 命令，而是让你在真实的仓库上走完一遍标准贡献流程。

本项目仓库中大部分教程都面向 CLI 用户，例如 README.md 中的git clone、git switch -c等命令式操作；而本教程对应的 github-windows-vs-code-tutorial.md 则是面向"不想碰命令行"的开发者——所有操作都通过 VS Code 的图形界面与命令面板完成。两套教程指向同一个目标文件 Contributors.md，结果等价，这正是本项目的设计意图：无论你用哪种工具，都能完成第一次真实贡献。

运行环境说明：官方教程基于Windows 10 + Visual Studio Code 1.27.2录制，后续步骤中会用到键盘快捷键，它们在 macOS / Linux 以及不同键盘布局（UK、DE 等）下可能不同。你可以随时在 VS Code 命令面板中搜索 "shortcuts"（快捷键）查看当前环境的键位列表。

前置条件：安装 Visual Studio Code

如果机器上还没有安装 VS Code，请先前往官方下载页安装。此外，本教程依赖 VS Code 内置的 Git 集成能力，因此建议同时确认本机已安装 Git，且 VS Code 能识别到git可执行文件（Windows 下通常随 Git for Windows 一起配置好）。

第一步：Fork 这个仓库

进入 first-contributions 的仓库主页，点击页面右上角的Fork按钮，即可在你的 GitHub 账户中创建该仓库的一份副本。

理解 Fork 的语义很重要：

GitHub 会持续记录你的仓库与你 Fork 的来源仓库之间的关系，可以把你的副本理解为一个"工作副本"（working copy）。
大多数顶层仓库（即不是从其他仓库 Fork 而来的仓库）只有一个小型核心团队能直接提交改动；其他所有贡献者都必须先 Fork，在副本上修改，再通过 Pull Request 请求把改动合并回顶层仓库。
如果仓库管理员认可你的改动并将其合并，你的贡献就正式进入项目了。

从仓库结构看，Fork 机制是 README.md 与 Contributors.md 协作模式的根基——Contributors.md中数千行贡献者名单，正是通过无数个 Fork + PR 累积出来的。

第二步：克隆你的仓库（注意别克隆错）

Fork 之后，下一步是把你自己的副本克隆到本机进行修改。关键警告：新手最常见的错误是克隆了"被 Fork 的那个原仓库"，而不是自己 Fork 出来的仓库。请检查浏览器地址栏，确认克隆的是你的用户名下的仓库。

在 GitHub 上点击Code按钮，再点击复制到剪贴板图标拿到仓库 URL。然后：

打开 Visual Studio Code，按下F1打开命令面板（输入框中已带有一个>提示符；也可以按CTRL-P后输入>进入同一入口）。
输入git clone（只输入git或clone也可以，命令面板按关键字模糊搜索）。
在下拉结果中选择Git: Clone并回车。
粘贴你刚才复制的仓库 URL 并回车，VS Code 会弹出文件资源管理器，让你选择仓库在本机的存放位置。

命令面板中列出的其他历史命令是"最近使用"的缓存，可以忽略。克隆过程中，VS Code 右下角会出现一个状态弹窗；完成后可通过弹窗中的按钮直接打开克隆下来的仓库文件夹。

再次强调：务必确认克隆的是你 Fork 出来的仓库而非原仓库，否则后续推送和 PR 都无法按预期工作。

第三步：创建一个分支

再次按F1打开命令面板，输入branch，从建议中选择Create Branch命令；随后输入新分支的名称，例如add-david-kroell（建议使用add-你的用户名的命名约定），回车后分支即创建完成，并自动完成 checkout（切换）。

关于 checkout：这是 Git 的经典概念，含义是"切换到指定分支的工作区状态"。在 VS Code 中，创建分支后会自动 checkout，因此你可以立刻在新分支上进行修改。从源码结构看，README 的命令行版本使用的是git switch -c并在旧版 Git 下回退到git checkout -b（见 README.md），而 VS Code 图形界面把这一过程封装成了单一的 "Create Branch" 命令，二者底层效果一致。

第四步：做出必要的修改

在 VS Code 资源管理器中打开仓库根目录下的 Contributors.md 文件，把名字加到贡献者列表中。

几个实操要点：

该文件使用GFM（GitHub Flavored Markdown）语法，即 GitHub 特有的 Markdown 方言，对格式要求比较严格（"它可能很挑剔"）。
推荐做法是复制一行已有贡献者的条目，再改成你自己的名字，确保语法正确；文件条目格式为- [姓名](https://github.com/用户名)这种列表形式。
保存文件（CTRL-S）以登记改动。

README 的命令行版本还给出了一条额外建议：不要加在文件开头或结尾，放在中间任意位置即可（见 README.md），这样可以尽量避免与同一行附近的其他贡献者产生冲突。

第五步：Commit 并 Push 改动到 GitHub

VS Code 左侧边栏有五个图标，点击其中的源代码管理 / Source Control图标（快捷键CTRL + SHIFT + G），进入版本控制视图：

暂存（Stage）：文件资源管理器会列出自上次 commit 以来所有改动的文件，鼠标悬停文件并点击+号，将文件加入暂存区。
提交（Commit）：在暂存区顶部的输入框中填写提交信息，例如Add your-name to Contributors list，然后点击对勾（checkmark）按钮，改动即被提交到本地仓库。
推送（Push）：改动目前只存在于本地副本，还需推送到 GitHub。点击视图右上角的三个点菜单，选择Publish Branch（发布分支）选项，VS Code 会弹出对话框要求输入 GitHub 凭据；认证通过后，新分支连同其提交即被推送到你的 Fork 仓库。

从 README 的命令行对照可以看出，这一步等价于git add Contributors.md、git commit -m "Add your-name to Contributors list"与git push -u origin your-branch-name（见 README.md）；此外 README 还提醒，如果推送时遇到"密码认证被移除"的错误，需要改用 Personal Access Token 或 SSH 密钥，并用git remote set-url切换远程地址（见 README.md）。在 VS Code 的图形流程中，只要使用浏览器登录或已配置 SSH，这一环节通常是透明的。

第六步：提交你的改动以供审查

至此改动已经完整存在，但还只停留在你的仓库里。这一步是把改动提交给原仓库管理员审查、请求合并：

回到你的 GitHub Fork 仓库页面，在新分支通知旁边会看到Compare & Pull Request按钮，点击它。
在对比页面确认改动内容无误后，点击Create pull request提交 PR。

PR 提交后，改动会进入原仓库维护者的审查队列，合并完成后你会收到邮件通知，贡献正式生效。原文档中也描述了同样的流程（见 github-windows-vs-code-tutorial_pt_br.md）。

进阶：保持你的 Fork 与上游同步

完成首次贡献后，后续参与项目时还会频繁遇到一个场景：你的 Fork 落后于上游仓库。官方附加文档 keeping-your-fork-synced-with-this-repository.md 对此有详细说明。

其核心是开源协作中典型的Triangle Workflows（三角工作流），涉及三个仓库：

上游公开仓库github.com/firstcontributions/first-contributions.git；
你在 GitHub 上的 Fork 仓库；
你本地机器的克隆仓库。

同步顺序必须是：先让本地与上游同步，再把本地推送到你的 Fork。标准命令序列如下：

git status # 确认当前在 main 分支 git checkout main # 若不在 main 分支则先切换 git remote add upstream https://github.com/firstcontributions/first-contributions.git git fetch upstream # 拉取上游最新版本 git rebase upstream/main # 把上游合并进本地 main git push origin main # 推送本地 main 到你的 Fork（origin）

如果只想一条命令同时完成"拉取 + 合并"上游改动，可以直接使用：

git pull upstream main

建议在 GitHub 提示你的 Fork "落后若干提交"（a few commits behind）时，就执行一次上述同步。

总结

恭喜！你已经通过 Visual Studio Code 图形界面完整走通了fork → clone → edit → PR这一标准贡献工作流——这也是日后参与任何开源项目都会反复遇到的基本功。接下来，你可以把这份经验迁移到其他项目：先 Fork，克隆到本地，开分支，改代码，提交推送，最后发起 PR 等待维护者审查合并。

如果你更习惯命令行，本仓库还提供了完整的 CLI 教程（见 README.md）；如果想在其他工具（GitHub Desktop、GitKraken、IntelliJ IDEA、Sourcetree 等）中重复这套流程，可以在 README.md 的 "Tutorials Using Other Tools" 表格中找到对应指南。