使用 Visual Studio Code 完成你的第一个开源贡献Windows 环境下 Fork-Clone-PR 全流程实战first-contributions 项目【免费下载链接】first-contributions✨ Help beginners to contribute to open source projects项目地址: https://gitcode.com/gh_mirrors/fi/first-contributions本文基于 first-contributions 仓库官方 GUI 教程的孟加拉语版 github-windows-vscode-tutorial-bn.md 编写。该教程面向完全零基础的开源新手全程使用 Visual Studio Code 内置的 Git 能力在 Windows 10 上完成一次真实的贡献提交。读完本文你将掌握fork → clone → edit → PR这一开源协作标准工作流的每一步操作并了解出错时的排查思路与后续进阶学习路径。项目定位为什么需要这个教程first-contributions 仓库README.md的定位非常明确为第一次向开源项目提交贡献的新手提供指引并简化流程。第一次做任何事情都很难尤其是团队协作场景下犯错会让人不自在而开源恰恰建立在协作之上。阅读文章、观看教程都有帮助但都不如亲手把流程走一遍更有价值——这正是本教程存在的意义在不会破坏任何东西的前提下让你真实地做一遍。本教程对应的孟加拉语文档 github-windows-vscode-tutorial-bn.md 是仓库 GUI 教程体系的一部分其英文原版位于 github-windows-vs-code-tutorial.md仓库还提供了 GitHub Desktop、Visual Studio 2017、GitKraken、Sourcetree、IntelliJ IDEA 等其他工具的平行教程见 README.md 的Tutorials Using Other Tools表格。如果你不习惯命令行直接使用本文这套 GUI 操作即可完成与命令行完全相同的贡献流程。环境版本说明操作系统教程基于 Windows 10 机器制作孟加拉语原文明确标注了这一点。VS Code 版本制作时使用 Visual Studio Code 1.27.2。快捷键差异教程中使用的快捷键在其他操作系统macOS/Linux或不同键盘布局英式、德式等下可能有差异。如果快捷键失效可以在 VS Code 的 Command Palette命令面板中搜索shortcut查看并核对你的快捷键列表。前置安装如果机器上还没有安装 VS Code需要先从官方下载页完成安装原文档提供了安装链接同时需要有一个可用的 GitHub 账号。步骤一Fork 仓库在浏览器中完成在 GitHub 上打开 first-contributions 仓库首页点击页面右上角的Fork按钮。Fork 会在你自己的 GitHub 账户下创建一份该仓库的完整副本GitHub 会持续跟踪你的仓库与它 fork 自哪个原仓库之间的关联关系你可以把 fork 出来的仓库看作自己的一份可写工作副本从英文原版教程可以补充理解背后的协作模型大多数顶层仓库即没有 fork 来源的仓库只有一个很小的核心团队能直接提交改动其余所有贡献者都必须先 fork 仓库、在 fork 中修改再通过 Pull Request 请求把改动合并回顶层仓库。管理员认可后改动即被合并。这一步完全在网页端完成不需要打开 VS Code。步骤二在 VS Code 中 Clone 你的 Fork现在需要把 fork 下来的仓库克隆到本地机器才能开始修改。VS Code 需要拿到你仓库的 URL因此先在 GitHub 的 fork 仓库页面点击Code按钮再点击复制到剪贴板图标复制仓库地址。打开克隆命令打开 Visual Studio Code在欢迎页按下F1打开命令输入栏输入框中已经带有前缀也可以按CtrlP后再输入字符进入同样的命令提示。在下拉列表里输入git clone——只需输入git或clone即可该输入框按关键字搜索命令选中Git: Clone后按Enter。⚠️新手最常见的错误克隆了被 fork 的原仓库而不是克隆自己 fork 出来的仓库。请务必检查浏览器地址栏确认你复制的是自己账号下的仓库地址。英文原版教程特别强调必须确保克隆的是 fork 出来的仓库而非原仓库否则后续流程无法正常进行。粘贴地址并选择存储位置把复制的仓库 URL 粘贴进输入框按EnterVS Code 会弹出文件资源管理器选择仓库在本地磁盘上的存放目录克隆完成后VS Code 右下角会出现一个状态弹窗等待克隆结束后可以通过弹窗里的按钮直接打开克隆下来的仓库它现在是本机上的一个文件夹。步骤三创建分支Create Branch分支隔离是 Git 协作的核心实践在主分支main上直接修改并不是良好的习惯独立分支可以让你的改动与主线互不影响。再次按F1打开命令面板输入branch从列表中选择Create Branch命令。在下一步输入新分支的名字例如add-david-krol按Enter后分支即创建完成并且 VS Code 会**自动检出checkout**该分支——你后续的修改都会落在新分支上而不是主分支。关于分支命名README.md 中的命令行版本给出了同样的建议分支名不必强制包含add前缀但由于本任务的目的正是把你的名字加入列表以add-开头更能表达意图官方命令行示例为git switch -c add-alonzo-church。步骤四编辑 Contributors.md 完成修改本项目的贡献方式非常典型且简单把你自己的名字加进仓库根目录的 Contributors.md 文件。在 VS Code 中打开Contributors.md在文件中的任意位置加入你的名字不建议加在开头或结尾加在中间任意位置即可该文件使用的是GFMGitHub Flavored MarkdownGitHub 风味 Markdown语法每行贡献者的格式形如- 名字英文原版教程给出了一个很实用的技巧直接复制文件里另一位贡献者的一行把名字换成你自己的这样能保证 Markdown 语法完全正确——因为这种语法对格式相当挑剔修改完成后保存文件CtrlS变更即被 VS Code 的 Git 集成感知。从仓库现状可以看到Contributors.md 已积累超过 5900 行贡献者记录每位贡献者正是通过这种复制一行、替换名字的方式完成自己的第一次提交这也是该文件规模不断增长的原因。步骤五通过 Source Control 提交并推送改动已经保存接下来要把它们提交commit到本地仓库并推送到 GitHub。VS Code 左侧边栏提供了一组图标选择其中的源代码管理 / Source Control图标快捷键CtrlShiftG。1. 暂存Stage变更源代码管理面板会列出自上次提交以来所有被修改的文件。把鼠标悬停到文件上点击出现的加号按钮即可将该文件暂存stage相当于命令行中的git add Contributors.md见 README.md。2. 提交Commit把面板顶部输入框中的默认文字替换为提交信息例如Add your-name to Contributors list将your-name换成你的真实名字。然后点击输入框上方的✓对勾按钮改动即被提交到你的本地副本——对应命令行 README.md 中的git commit -m Add your-name to Contributors list。3. 发布分支Publish Branch提交只存在于本地还需要推送到 GitHub。点击源代码管理面板右上角的三点…菜单选择Publish Branch选项。VS Code 会弹出对话框要求输入 GitHub 凭据认证通过后新分支及其上的提交就被推送到你的 fork 仓库——这一步对应命令行 README.md 中的git push -u origin your-branch-name。步骤六发起 Pull RequestPR到此为止你的改动仍然只存在于自己的 fork 仓库中尚未进入原项目。最后一步是向顶层仓库管理员提交把改动合并回去的请求即 Pull Request。回到 GitHub打开你自己的 fork 仓库页面在新建分支的通知旁边会出现一个Compare pull request按钮点击它在打开的页面中确认改动内容无误后点击提交按钮发出 Pull Request。提交 PR 后原项目管理员会审查并合并你的改动合并完成后你会收到一封通知邮件。完成与进阶一个贡献者的标准起点恭喜你刚刚完整走过了开源贡献中最常见、最标准的工作流fork → clone → edit → PR这个流程今后会反复出现在你的开源协作生涯中。孟加拉语原文档还提供了两个可选的收尾动作通过配套 Web 应用与朋友分享你的贡献成果遇到问题时加入项目的 Slack 团队寻求帮助原文档均附有对应链接。仓库内进阶学习资料完成首次 PR 后仓库还准备了成体系的进阶材料入口在 additional-material.md建议按需阅读场景对应文档何时使用修改最近一次提交消息或遗漏的改动amending-a-commit.md提交后、推送前发现需要调整保持 fork 与上游仓库同步keeping-your-fork-synced-with-this-repository.mdGitHub 提示你的 fork 落后于上游若干提交时解决合并冲突resolving-merge-conflicts.mdPR 出现冲突、无法自动合并时把多个提交压缩为一个squashing-commits.md审查者要求合并提交信息撤销已推送的提交reverting-a-commit.md需要反向撤销线上改动删除本地分支delete-branch-locally.mdPR 合并成功后清理配置 Git 用户信息configuring-git.md提交时发现用户信息不对掌握更完整的 Git 命令README.md想用命令行完成同样的 fork→clone→edit→PR 流程其中特别值得提前了解的是 keeping-your-fork-synced-with-this-repository.md 描述的三角形工作流上游公共仓库upstream、你的 GitHub forkorigin、你的本地仓库三者之间需要定期同步。典型操作序列为git remote add upstream 上游地址→git fetch upstream→git rebase upstream/main→git push origin main或直接用git pull upstream main一步完成。在你与许多人共同向同一项目贡献时这一步会越来越重要。常见问题排查结合本教程涉及的环节与 README.md 中记录的问题汇总如下克隆了错误的仓库确认克隆的是你的用户名/first-contributions而不是firstcontributions/first-contributions否则你无法向自己的 fork 推送。推送时认证失败GitHub 已于 2021 年 8 月移除对 HTTPS 密码认证的支持。若报错提示 Support for password authentication was removed需要改用 Personal Access Token 或 SSH 密钥认证同时可用git remote -v检查远程地址必要时通过git remote set-url origin gitgithub.com:你的用户名/你的仓库.git切换为 SSH 地址。快捷键不生效教程基于 Windows 10 与 VS Code 1.27.2快捷键在 macOS/Linux 或其他键盘布局下可能不同在命令面板搜索shortcut可查看完整快捷键列表。分支未创建成功确认命令面板中选择的是Create Branch而非其他包含 branch 字样的命令创建后 VS Code 会自动检出新分支可观察左下角状态栏确认当前所在分支。完成首次贡献之后这套 fork → clone → edit → PR 的肌肉记忆会成为你参与任何开源项目的基础能力——先在一个安全的副本上自由实验再通过 Pull Request 把成果带给整个社区。【免费下载链接】first-contributions✨ Help beginners to contribute to open source projects项目地址: https://gitcode.com/gh_mirrors/fi/first-contributions创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考