first-contributions 首次开源贡献实战从 Fork 到 Pull Request 的完整指南【免费下载链接】first-contributions✨ Help beginners to contribute to open source projects项目地址: https://gitcode.com/gh_mirrors/fi/first-contributions本文以 GitHub 加速计划 fi 镜像中的 first-contributions 仓库为教学载体系统讲解新手完成人生第一次开源贡献的标准工作流fork → clone → edit → pull request。全文覆盖从仓库分叉、本地克隆、分支创建、文件修改与提交到推送远端并发起 Pull Request 的每一步并给出可直接复制运行的 git 命令读完你将完整掌握在真实开源项目中提交一次代码贡献的全部技术动作同时了解该仓库内置的 Git 进阶学习材料与图形化工具教程入口。项目概览一个为「第一次贡献」而生的教学仓库first-contributions 项目的定位非常明确简化并引导初学者完成他们的第一次开源贡献。它不是展示复杂架构的业务代码库而是一个刻意设计的练习场——任务只有一个把自己的名字添加到 Contributors.md 中并成功提交一个 Pull Request。围绕这一单一目标仓库组织了清晰的学习资源README.md主教程本文所依据的 README.aze.md 即其阿塞拜疆语翻译版也是全部语言版本的骨架Contributors.md贡献者名单文件截至当前镜像快照已累计约 5919 行是本次练习的实际操作对象docs/additional-material/git_workflow_scenarios/Git 进阶场景学习材料索引修改提交、解决冲突、同步 fork 等docs/gui-tool-tutorials/针对不熟悉命令行的读者准备的图形化工具教程。整个流程虽然简单却完整复刻了真实开源协作中的全部关键环节分叉远端仓库、管理本地分支、暂存与提交变更、推送远端、发起审查请求。掌握这套流程你就具备了参与绝大多数开源项目的基本能力。前置准备安装 Git 与准备 GitHub 账号开始之前需要确认两件事本机已安装 Git。如果尚未安装请先参照官方文档完成 Git 的安装与环境配置原文档提示了 Git 安装入口安装完成后可在终端用git --version验证。拥有一个可登录的 GitHub 账号。后续的 Fork、Push、Pull Request 操作都发生在你的账号名下。第 1 步Fork分叉仓库打开 first-contributions 仓库主页点击页面右上角的Fork按钮。这一操作会在你自己的 GitHub 账号下生成一份该仓库的完整副本。此后你对仓库的一切修改都发生在这份副本中不会影响原仓库这也正是后续发起 Pull Request 的前提——你无法直接向别人的仓库推送代码但可以请求对方合并你副本中的改动。第 2 步Clone克隆仓库到本地Fork 完成之后需要把远端副本拉到本地电脑才能编辑文件。登录 GitHub进入你 fork 出来的仓库点击绿色的Code按钮再点击复制到剪贴板copy to clipboard图标复制仓库地址。然后打开终端执行git clone 你刚复制的地址把命令中的占位内容替换为实际复制的 URL不要带引号。例如git clone https://github.com/你的用户名/first-contributions.git其中你的用户名是你的 GitHub 用户名。执行后GitHub 上 first-contributions 仓库的全部内容就被复制到了你的电脑上本地会生成一个名为first-contributions的目录。第 3 步创建分支Branch分支是 Git 协作的基石它让你可以在独立的开发线上修改代码而不影响主分支main的稳定状态。先进入仓库目录如果当前不在该目录下cd first-contributions然后使用git checkout创建并切换到新分支git checkout -b 你的新分支名分支命名建议遵循本项目惯例以add-开头后接你的名字例如git checkout -b add-alonzo-church补充如果你使用的 Git 版本较新2.23也可以使用功能等价的git switch -c 分支名命令。若执行git switch时提示 switchis not a git command说明 Git 版本过旧改用git checkout -b即可该兼容性说明来自仓库主 README.md。第 4 步修改文件并提交Commit这是整个练习的核心动作。用任意文本编辑器打开仓库根目录下的 Contributors.md把自己的名字添加进去。注意不要把名字加在文件开头或结尾而是放在中间任意位置——这样做的目的是降低多名学习者同时提交时发生合并冲突的概率仓库文档对此有明确指示。保存文件后本次练习的「代码变更」就完成了。接下来按顺序执行三条命令完成「查看变更 → 暂存 → 提交」1) 查看变更状态git status在项目目录下执行后你会看到Contributors.md被标记为已修改modified说明改动已被 Git 感知。2) 暂存变更git add Contributors.mdgit add把指定文件从工作区放入暂存区staging area使其进入待提交状态。这里只暂存了Contributors.md符合「一次提交只包含一个逻辑变更」的良好习惯。3) 提交变更git commit -m Add your-name to Contributors list将your-name替换为你的名字。-m参数后的字符串是提交信息commit message用于说明本次提交做了什么是开源协作中必须认真书写的内容。至此变更已被固化到本地当前分支的历史中。第 5 步Push推送变更到 GitHub本地提交只是完成了「本地一半」要让远端仓库看到你的改动需要执行推送git push origin 你的分支名将你的分支名替换为你在第 3 步创建的分支名注意原文档提示替换的是分支名。推荐再加上-u参数建立本地分支与远端分支的追踪关系之后在该分支上的推送就可以直接写git pushgit push -u origin 你的分支名执行成功后你 fork 出来的 GitHub 仓库中就会出现这个新分支及其上的提交。第 6 步提交 Pull Request拉取请求推送完成后回到 GitHub 上你自己的仓库页面会看到一个醒目的Compare pull request按钮点击它。随后进入 Pull Request 创建页面确认比较方向你的分支 → 上游仓库的main分支与变更内容无误后填写标题与说明点击提交按钮你的第一个 Pull Request 就正式发出了。接下来只需等待仓库维护者审查。一旦变更被合并进项目的main分支你就会收到通知邮件——至此你的名字已永久写入 Contributors.md第一次开源贡献宣告完成。完成之后巩固练习与开启更多贡献恭喜你已经完整走过了开源贡献者最常遇到的fork → clone → edit → pull request标准工作流。原文档还给出了三条后续路径分享成果通过项目配套的 Web 应用first-contributions 的在线站点记录并分享你的第一次贡献更多练习项目提供了 code-contributions 练习资源可继续强化 Git 与贡献技能转向真实项目项目整理了一批带 easy 级 issue易上手问题的开源项目清单可以从这些项目开始把刚刚掌握的流程应用到真实场景中。进阶材料Git 高阶场景学习索引完成基础流程后仓库在 docs/additional-material/git_workflow_scenarios/additional-material.md 中整理了面向真实协作场景的进阶学习材料覆盖了首次贡献之后几乎所有会遇到的 Git 操作场景文档适用时机修改最近一次提交amending-a-commit.md需要调整已做的一次提交改提交信息或补漏文件配置 Git 用户信息configuring-git.md需要更好地控制 Git 配置同步 fork 与上游仓库keeping-your-fork-synced-with-this-repository.mdfork 落后于上游仓库需要拉取最新变更移动提交到其他分支moving-a-commit-to-a-different-branch.md提交落在了错误的分支上删除本地文件removing-a-file.md提交前需要从本地仓库移除文件删除本地分支removing-branch-from-your-repository.md你的 PR 被合并之后清理分支解决合并冲突resolving-merge-conflicts.md合并时遇到冲突回滚已推送的提交reverting-a-commit.md需要撤销已推送到远端的提交压缩多个提交squashing-commits.md评审者要求把多个提交合并为一个撤销本地提交undoing-a-commit.md本地仓库改乱了需要重置创建 .gitignorecreating-a-gitignore-file.md需要让 Git 忽略不需要跟踪的文件凭据存储storing-credentials.md需要为仓库存储访问凭据注意遵循所在机构的安全策略更多学习链接Useful-links-for-further-learning.md想系统深入学习 Git 与开源领域知识这些文档大多同样提供了多语言翻译版本见 docs/translations其中中文版可直接参考 docs/additional-material/git_workflow_scenarios 与 docs/translations/Chinese 目录。不想用命令行图形化工具教程汇总如果对命令行感到吃力仓库为常见 GUI 工具准备了完整的图文教程位于 docs/gui-tool-tutorials使用这些工具同样可以完成 fork、clone、commit、push、pull request 的全部流程工具教程GitHub Desktopgithub-desktop-tutorial.mdVisual Studio 2017github-windows-vs2017-tutorial.mdGitKrakengitkraken-tutorial.mdVisual Studio Codegithub-windows-vs-code-tutorial.mdAtlassian Sourcetreesourcetree-macos-tutorial.mdIntelliJ IDEAgithub-windows-intellij-tutorial.md常见问题与提示推送时遇到认证错误。GitHub 已于 2021 年 8 月 13 日起移除了对密码认证的支持改用 personal access token 或 SSH 密钥。若推送时报Authentication failed可先执行git remote -v检查远端地址git remote -v如果远端使用的是https://github.com/你的用户名/first-contributions.git形式可通过git remote set-url切换为 SSH 地址再配合配置好的 SSH 密钥完成认证git remote set-url origin gitgithub.com:你的用户名/first-contributions.git该提示同样来自仓库主 README.md 的错误处理章节。不要在 main 分支上直接改。整个练习刻意要求「先建分支再修改」这正是真实开源项目的通行规范特性分支隔离变更、便于审查与回滚也让多名贡献者的工作互不干扰。养成「一个分支一件事」的习惯是参与开源协作的第一步。【免费下载链接】first-contributions✨ Help beginners to contribute to open source projects项目地址: https://gitcode.com/gh_mirrors/fi/first-contributions创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
