first-contributions 实战指南从 Fork 到 Pull Request 完成你的第一次开源贡献【免费下载链接】first-contributions✨ Help beginners to contribute to open source projects项目地址: https://gitcode.com/gh_mirrors/fi/first-contributions本教程以开源教学仓库 first-contributions 的入门文档docs/translations/README.un-aln.md与仓库根目录 README.md 同源为主体完整拆解一次开源贡献的标准流程Fork 仓库、Clone 到本地、创建分支、修改 Contributors.md、提交并推送、最后发起 Pull Request。读完本文你将掌握fork → clone → edit → pull request这条几乎所有开源项目通用的协作链路并具备排查推送认证错误的实战能力。一、先理解这份教程在教什么first-contributions 是一个专门为开源新人设计的教学项目其目标是简化并引导初学者完成第一次贡献。整个仓库的骨架非常简单一份教程文档、一个贡献者名单文件 Contributors.md以及大量面向不同工具、不同语言的辅助教程。这正是刻意设计的教学场景你的任务不是读懂复杂的业务代码而是走完一次真实的 Git 协作流程——把贡献这个抽象概念落实为在 Contributors.md 里加上自己的名字并成功合并这一件具体小事。仓库根目录的 README.md 开头明确写道This project aims to simplify and guide the way beginners make their first contribution而本文对应的关联文档docs/translations/README.un-aln.md是它的完整同源版本正文结构与操作步骤完全一致。整个流程的核心链路是Fork复制到自己的账户→ Clone拉到本地→ Branch新建分支 → Edit修改文件→ Commit本地提交→ Push推送到远程 → Pull Request发起合并请求→ Merge维护者合并下文每一步都给出可直接复制运行的命令。二、准备工作安装 Git并确认版本差异在开始前先确认你的机器上已经安装 Git。如果尚未安装请按平台官方的 Git 安装指南完成安装Windows 可安装 Git BashmacOS 与 Linux 可通过各自包管理器安装。安装完成后可以用一条命令验证版本git --version这里有一个新手很容易踩的坑创建分支的命令存在新旧版本差异。本教程正文使用的是经典写法git checkout -b而仓库主 READMEREADME.md 的 Create a branch 一节使用的是新版 Git 推荐的git switch -c并明确说明如果执行git switch时提示 switchis not a git command说明你的 Git 版本较旧请改用git checkout -b。两种写法效果相同本文统一采用兼容性最好的git checkout -b。三、第一步Fork 这个仓库Fork分叉是开源协作的第一步。打开仓库主页点击页面右上角的Fork按钮点击页面顶部的 fork 按钮即可 Fork 这个仓库这会在你自己的账户下创建一个该仓库的副本。Fork 与直接修改原仓库的关键区别在于Fork 得到的副本属于你个人你对它有完全的读写权限原仓库上游的代码不受你的任何操作影响后续你通过 Pull Request 把副本中的改动申请合并回上游由维护者审核决定是否接受。四、第二步Clone 到本地4.1 复制你的 Fork 地址Fork 完成后进入你账户下的这个副本仓库点击Code按钮本教程早期版本为 SSH 标签页下的复制图标然后点击复制到剪贴板图标得到该仓库的 URL。注意复制的是你自己 fork 出来的副本地址而不是上游原仓库的地址。4.2 执行 clone 命令打开终端运行下面的命令引号内替换为你刚复制的地址引号本身不需要git clone url you just copied示例git clone https://gitcode.com/gh_mirrors/fi/first-contributions.git在实际练习中把示例地址换成你自己的 fork 地址即可。这条命令会把远程仓库的完整内容包括所有分支与历史记录复制到你的本地计算机生成一个与仓库同名的目录first-contributions。五、第三步创建分支5.1 进入仓库目录克隆完成后切换到仓库目录如果你已经在这里可跳过cd first-contributions5.2 用 checkout 创建并切换分支使用git checkout命令创建并切换到一个新分支git checkout -b your-new-branch-name示例git checkout -b add-alonzo-church这里的-b参数表示创建并切换分支名通常用add-前缀加上你要贡献的内容来命名例如add-alonzo-church。为什么不直接在默认分支上改因为分支提供了一条隔离的开发线你的实验性修改不会干扰主干即使改坏了也可以随时丢弃。仓库的进阶文档 docs/additional-material/git_workflow_scenarios/why-using-branches.md 对这一主题有专门讲解。六、第四步修改文件并提交6.1 编辑 Contributors.md现在用任意文本编辑器打开仓库根目录的 Contributors.md把你的名字加进去。教程有一个具体且刻意的要求不要把名字加在文件的开头或结尾把它放在文件中间的任何位置。这个要求的背后是刻意制造的冲突训练——因为大量贡献者都在往同一个文件里加名字如果你刚好和别人的改动发生重叠就会在后续的合并阶段遇到合并冲突merge conflict这其实是教学环节的一部分。从仓库现状看Contributors.md 已经积累了约 5953 行、数千位贡献者的记录文件内部正是类似- [你的名字](https://github.com/你的用户名)的 Markdown 列表项格式照此格式在中间任意位置插入一行并保存即可。6.2 用 git status 查看变更保存文件后在项目目录执行git status你会看到类似modified: Contributors.md的输出表示文件已被修改但尚未暂存。这个命令能帮你随时确认当前工作区的状态是 Git 使用频率最高的命令之一。6.3 用 git add 暂存修改把修改加入刚刚创建的分支暂存区git add Contributors.md6.4 用 git commit 提交提交并附上规范的提交信息git commit -m Add your-name to Contributors list把your-name替换成你的真实名字。git commit把暂存区的改动固化成本地历史记录-m参数指定提交信息。提交信息遵循动词开头 做了什么的简洁约定这在开源社区是通用习惯。七、第五步Push 到 GitHub7.1 推送分支本地提交完成后用git push把改动推送到远程仓库git push origin -u add-your-branch-name把add-your-branch-name替换为你前面创建的分支名。这里的两个参数含义分别是origin远程仓库的默认别名指向你 fork 的副本-u--set-upstream的简写把本地分支与远程分支建立跟踪关联此后在该分支上只需执行git push即可。7.2 推送报错排查认证错误推送时最容易遇到的错误是认证失败。原文档给出了典型的报错信息remote: Support for password authentication was removed on August 13, 2021. remote: Please use a personal access token instead. fatal: Authentication failed for https://github.com/your-username/first-contributions.git/这意味着自 2021 年 8 月 13 日起GitHub 已不再支持用账号密码进行 Git 操作认证需要改用个人访问令牌Personal Access Token或 SSH 密钥。修复方法在账户设置中生成一个 Personal Access Token并授予仓库读写权限用它替代密码或生成 SSH 密钥对并把公钥配置到账户的 SSH keys 中仓库的进阶文档 docs/additional-material/git_workflow_scenarios/storing-credentials.md 对凭据存储有专门说明。另一个常见原因是远程地址指向错误。执行以下命令检查你的远程地址git remote -v如果输出形如https://github.com/your-username/your_repo.git的 HTTPS 地址且你希望改用 SSH 认证可以这样修改git remote set-url origin gitgithub.com:your-username/your_repo.git否则推送时会反复提示输入用户名和密码并最终报认证错误。八、第六步提交 Pull Request推送成功后回到你账户下的仓库页面会看到一个Compare pull request按钮点击它确认比较方向base目标即上游仓库的主分支←compare你的分支填写 Pull Request 的标题与说明简要描述你做了什么修改点击提交 Pull Request。提交后维护者会收到通知并审核你的改动。一旦审核通过并被合并到主分支你会收到一封通知邮件——至此你的第一次开源贡献就完成了。九、完成后去哪里进阶材料与更多练习完成这次fork → clone → edit → pull request流程后你已经掌握了贡献者最常使用的一条标准链路。仓库还为你准备了大量进阶资源9.1 进阶 Git 场景材料仓库的 docs/additional-material/git_workflow_scenarios/additional-material.md 汇总了十余个进阶主题按需取用场景对应文档修改最近一次提交amendamending-a-commit.md配置 Git 用户信息与选项configuring-git.md保持 fork 与上游仓库同步keeping-your-fork-synced-with-this-repository.md把提交移动到其他分支moving-a-commit-to-a-different-branch.md从本地仓库移除文件removing-a-file.md删除本地/远程分支delete-branch-locally.md、removing-branch-from-your-repository.md解决合并冲突resolving-merge-conflicts.md撤销/回退提交reverting-a-commit.md、undoing-a-commit.md用交互式 rebase 压缩提交squashing-commits.md创建 .gitignore 与存储凭据creating-a-gitignore-file.md、storing-credentials.md常用链接汇总Useful-links-for-further-learning.md9.2 不习惯命令行的读者GUI 工具教程如果你对命令行不熟悉仓库在 docs/gui-tool-tutorials/github-desktop-tutorial.md 等目录下提供了多款图形化工具的分步教程覆盖 GitHub Desktop、VS Code、IntelliJ IDEA、GitKraken、Atlassian Sourcetree、Visual Studio 2017 等中文版见 docs/gui-tool-tutorials/translations/Chinese/。这些教程用鼠标点击即可完成同样的流程适合零命令行基础的同学。9.3 多语言版本与 CLI 教程仓库还维护了大量语言版本的主教程见 docs/translations/Translations.md含中文版 docs/translations/README.zh-cn.md以及 Git 命令行与 GitHub CLI 的专项教程见 docs/cli-tool-tutorials/。十、小结一次提交背后的协作心智回顾整个过程你实际完成的是一次标准的开源协作闭环Fork 保证人人可改而不破坏原仓库分支保证改动彼此隔离Pull Request 保证所有变更经过审核。这套机制正是现代开源协作得以大规模运转的基石。完成第一次贡献后你可以把同样的流程迁移到任何你感兴趣的项目上阅读它的贡献指南、认领一个 easy issue、按本文的六步走完提交——从此你就不再是旁观者而是开源社区的一员。关键命令速查git clone your-fork-url # 克隆 fork 到本地 cd first-contributions # 进入仓库目录 git checkout -b add-your-name # 创建并切换分支 git status # 查看工作区状态 git add Contributors.md # 暂存修改 git commit -m Add your-name to Contributors list # 提交 git push origin -u add-your-name # 推送并建立跟踪推送报错时先git remote -v检查远程地址再用令牌或 SSH 密钥完成认证若需切换认证方式用git remote set-url更新远程地址即可。【免费下载链接】first-contributions✨ Help beginners to contribute to open source projects项目地址: https://gitcode.com/gh_mirrors/fi/first-contributions创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考