first-contributions 实战用 Visual Studio 2017 Team Explorer 完成你的首次开源贡献Fork → Clone → Branch → PR 全流程【免费下载链接】first-contributions✨ Help beginners to contribute to open source projects项目地址: https://gitcode.com/gh_mirrors/fi/first-contributions本篇技术指南以 github-windows-vs2017-tutorial.md 为骨架完整讲解在 Windows 上使用 Visual Studio 2017 内置的 Team Explorer 完成一次真实开源贡献的标准流程Fork 上游仓库、Clone 到本地、创建功能分支、修改Contributors.md、提交并 Push、最后发起 Pull Request。读完本文你将不依赖命令行、纯靠 VS2017 图形界面走通开源协作中最常遇到的fork - clone - edit - PR工作流并理解其中每个动作背后的 Git 原理与仓库约定。为什么第一次开源贡献总是很难第一次做任何事都很难尤其是协作开发——犯错在所难免这并不舒服。但开源的本质就是协作与共同工作。first-contributions 项目仓库根目录 README.md的定位正是帮助新手简化并引导第一次贡献它希望通过在不搞砸任何东西的情况下真正动手做一遍来取代只读文章、只看视频的低效学习方式。记住你越放松学得越好。如果只是想在指导下完成第一次贡献按下面的步骤走即可。在动手之前你需要理解开源仓库的协作模型大多数顶层仓库非 fork 而来的仓库只有一个小型核心团队拥有直接提交commit权限其他所有贡献者都必须先 fork 仓库在自己的 fork 中修改再创建 Pull Request 请求将改动合并回顶层仓库。如果顶层仓库管理员认可你的改动它就会被合并——这也是本次教程要带你完成的完整链路。环境准备安装 Visual Studio 2017本教程全程使用 Visual Studio 2017 的Team Explorer面板完成 Git 操作如果你的机器上还没有安装 VS2017需要先自行安装安装包在微软官网 Visual Studio 下载页获取。本仓库并不要求你必须具备 .NET 开发能力——Team Explorer 只是借用了 VS2017 内置的 Git 图形界面你甚至不需要创建任何解决方案Solution文件。第一步Fork 这个仓库进入 first-contributions 的仓库主页点击页面顶部的Fork按钮即可在你自己的 GitHub 账户下生成一份该仓库的副本。GitHub 会自动记录你的 fork 与源仓库之间的父子关系你可以把 fork 理解为你专属的工作副本working copyfork 的意义在于你没有直接修改上游仓库的权限但可以随意改动自己的 fork并通过 Pull Request 把成果回馈给上游。第二步Clone 你的仓库而不是上游仓库Fork 完成后下一步是把你的仓库克隆到本机这样才能开始修改。Clone 需要仓库的 URL在你的 fork 仓库页面点击Clone或 Code按钮再点击复制到剪贴板copy to clipboard图标复制仓库地址⚠️ 特别警告新手最常见的错误是克隆了被 fork 的那个上游仓库而不是你自己的 fork。请检查浏览器地址栏确保克隆的是你自己的仓库URL 中是你的用户名而非 firstcontributions。现在进入 Visual Studio 2017本教程的大部分操作都发生在Team Explorer选项卡中如果默认没有打开通过菜单View Team Explorer打开Team Explorer 顶部有导航按钮可切换多个视图。克隆仓库需要位于Connect连接视图通常是默认视图如果看不到Clone按钮点击顶部的绿色插头图标plug即可切换过去在Local Git Repositories本地 Git 仓库下点击Clone选项在文本框中粘贴你刚才从 GitHub 复制的 fork 仓库 URL点击Clone按钮开始克隆。克隆完成后VS2017 会自动切换到Solution Explorer选项卡你可以在这里看到仓库的完整内容。你的目录结构会和教程截图略有不同因为仓库内容会随时间变化。第三步创建功能分支Git 的最佳实践是每个改动都放在独立分支上这样既能隔离实验性改动也方便在合并前审阅。切回Team Explorer选项卡用主导航下拉菜单打开Branches分支视图你会看到first-contributions仓库以及默认分支这个仓库的默认分支名为main右键点击main选择New Local Branch From...从当前分支新建本地分支按仓库约定的命名规范给分支起名add-你的名字例如add-alonzo-church保持Checkout branch创建后立即检出复选框为勾选状态点击Create Branch按钮。创建成功后新分支会出现在分支列表中且当前工作分支已自动切换到它。第四步修改 Contributors.md写下你的名字打开仓库根目录的 Contributors.md把你的名字添加到名单末尾该文件当前已有数千位贡献者。注意该文件使用GFMGitHub Flavored Markdown语法即 GitHub 特有的 Markdown 变体格式比较挑剔最稳妥的做法是复制其他贡献者的一行再改成自己的名字确保列表项的语法如- 名字完全正确避免因格式错误导致合并失败。第五步提交Commit并推送Push到 GitHub切回Team Explorer导航到Changes更改视图在首次提交前VS2017 会要求填写提交人信息姓名与邮箱。填写后点击SaveVisual Studio 会记住这些信息供后续提交复用。Git 在创建提交时必须绑定一个名字和一个邮箱这是协作时谁改了什么、何时改的得以追溯的基础稍等片刻你会看到变更文件列表和一个提交说明commit message文本框。提交说明应当简洁但完整——I updated some stuff 这样的说明没有任何信息量花几秒钟把这次改动说清楚将来的同事以及未来的你自己会感谢你点击Commit All and Push一步完成本地提交 推送到你的 GitHub fork。关于提交与推送的两个关键概念Commit 与 Push 可以分开执行。此处二合一仅为方便Commit 只在本地记录改动日志改动并不会出现在你的 GitHub 仓库中直到你执行 Push首次 Push 到 GitHub 时VS2017 会询问你的 GitHub 凭据之后会被缓存你不会频繁看到登录提示。Push 完成后打开 GitHub 上的 fork 仓库你会看到一条最近推送了新分支的提示。点击Branch: main下拉菜单并选择你的新分支即可查看你的改动——此时你可以把分支 URL 分享给朋友展示你的进度。关于.vs隐藏文件夹的补充说明Visual Studio 会在仓库内创建一个隐藏的.vs文件夹用于存放个人设置与偏好这些内容不应被保存进 Git。如果没有被忽略你需要告诉 Git 忽略该文件夹避免把本地个性化配置上传到仓库。在本仓库中这一工作已经提前完成仓库根目录的 .gitignore 中已有忽略规则包括第 3 行的.vs以及第 37 行的# Visual Studio 2015/2017 cache/options directory下的.vs/规则所以你不需要再执行这一步——这里只是为将来的项目做个参考。同时该文件也一并忽略了.idea/、.vscode/、构建产物bin/、obj/、Debug/、Release/等 IDE 与编译生成物保证提交到仓库的都是源码与文档等必要文件。关于.gitignore的语法与全局忽略配置可参考 creating-a-gitignore-file.md。第六步提交 Pull Request请求合并到这里你的改动还只存在于你自己的 fork 仓库中。最后一步是向上游仓库管理员提交合并请求在你的 fork 仓库页面上新分支推送通知旁边会出现Compare pull request按钮点击它确认对比的两个分支无误你的新分支 → 上游main填写 Pull Request 的标题与说明然后提交 Pull Request。提交成功后上游仓库管理员会审阅并把你的改动合并进项目主分支合并完成后你会收到一封通知邮件。完成之后你已经掌握了什么恭喜你已经完整走通了开源贡献中最标准的fork - clone - edit - PR工作流——这是你之后参与几乎所有开源项目都会反复遇到的基本功。完成合并后可以进一步阅读 additional-material.md 中收录的进阶 Git 技巧建议按需取用amending-a-commit.md在 Push 之前修改最近一次提交改提交信息或补漏文件configuring-git.md深入理解git config的全局、仓库级、命令行级三种作用域及优先级命令行 仓库 全局以及core.editor、commit.template、color.ui等常用配置项keeping-your-fork-synced-with-this-repository.md用git remote add upstreamgit fetch upstreamgit rebase upstream/maingit push origin main的三角工作流让你的 fork 与上游保持同步——当你看到 GitHub 提示落后上游若干提交时就应该执行这一流程resolving-merge-conflicts.md 与 squashing-commits.md应对合并冲突与审阅者要求合并提交信息的常见场景creating-a-gitignore-file.md学习.gitignore的规则语法与全局忽略配置。使用其他工具参与贡献本教程只是 first-contributions 项目众多 GUI 工具教程之一。仓库的 README.md 底部收录了完整的工具教程索引包括 GitHub Desktop、GitKraken、Visual Studio Code、Sourcetree、IntelliJ IDEA 等如果你不习惯图形界面也可以直接使用 README.md 主流程中的git clone、git switch -c、git add、git commit、git push命令行方式完成同样的一趟贡献之旅。选择最适合你的工具把第一次贡献变成一件轻松、愉快的事。【免费下载链接】first-contributions✨ Help beginners to contribute to open source projects项目地址: https://gitcode.com/gh_mirrors/fi/first-contributions创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考