first-contributions 实战指南用 fork-clone-edit-pull request 工作流完成你的第一次开源贡献【免费下载链接】first-contributions✨ Help beginners to contribute to open source projects项目地址: https://gitcode.com/gh_mirrors/fi/first-contributions本指南以开源教学仓库 first-contributions 的多语言文档含爪哇语README.jv.md在内的完整翻译体系为骨架面向从未参与过开源协作的初学者系统讲解一次标准开源贡献从 Fork、Clone、创建分支、修改提交、Push 到提交 Pull Request 的完整闭环。读完本文你将掌握开源协作中最常遇到的fork - clone - edit - pull request工作流并了解同步上游、撤销提交、解决合并冲突等进阶操作的去处。一、项目背景first-contributions 是什么first-contributions 是一个专门帮助初学者完成人生第一次开源贡献的教学项目。项目本身不承载复杂的业务代码而是把如何向一个 GitHub 仓库提交贡献这一流程拆解成若干可逐步照做的操作配合仓库内的 Contributors.md 作为实践素材——每位学习者把自己的名字加进这份名单即可真实走完一次贡献流程。从仓库结构可以直观看到项目的教学属性README.md 主文档提供命令行方式的完整入门流程docs/translations/Translations.md 收录了数十种语言的 README 翻译本文依据的 docs/translations/README.jv.md爪哇语即其中之一内容与主 README 一一对应docs/additional-material/git_workflow_scenarios/additional-material.md 提供进阶 Git 技巧索引docs/gui-tool-tutorials 目录提供 GitHub Desktop、VS Code、GitKraken、IntelliJ 等图形工具的教程。值得一提的是Contributors.md 当前已积累约五千余条贡献者记录这份不断增长的文件本身就是第一次贡献流程不断被真实执行的最好证据。二、前置准备安装 Git本教程的默认操作方式是命令行。开始之前请确认你的机器上已经安装了 Git。可以用以下命令检查git --version如果尚未安装仓库文档中也提供了不同平台的安装指引例如 installing-git-ubuntu.mdUbuntu、installing-git-arch.mdArch Linux等。安装完成后建议先按 configuring-git.md 配置好用户名和邮箱因为每次 commit 都会记录这些信息。如果你对命令行不熟悉可以直接跳到本文第七节使用图形化工具完成同样的流程。三、第一步Fork 仓库进入 first-contributions 仓库页面点击页面右上角的Fork按钮。Fork 的作用是在你自己的 GitHub 账号下生成一份仓库副本。这一步非常关键常规情况下你没有权限直接向别人的仓库写提交但对自己账号下的副本拥有完全控制权。后续所有修改都发生在你的副本中最后通过 Pull Request 把修改反向提交给原仓库。四、第二步Clone 仓库到本地Fork 完成后进入你自己账号下的仓库副本点击Code按钮切换到SSH标签页点击复制图标复制仓库地址。然后打开终端执行git clone url you just copied其中url you just copied不含引号就是你刚复制的仓库地址。例如git clone gitgithub.com:this-is-you/first-contributions.git这里的this-is-you需要替换为你的 GitHub 用户名。Clone 会把远程仓库的完整内容包括提交历史下载到你的本地计算机得到一个名为first-contributions的本地目录。五、第三步创建分支进入克隆下来的仓库目录cd first-contributions然后使用git switch命令创建一个新分支git switch -c your-new-branch-name例如主文档中给出的示例分支名是add-alonzo-church。分支的意义在于把你的改动与主分支main隔离即使改坏了也可以随时丢弃不影响主线。老版本 Git 的兼容写法如果你执行git switch时遇到类似 switch不是 git 命令 的错误说明本机 Git 版本较老。此时改用传统的git checkout即可git checkout -b your-new-branch-name两种写法效果等价-c/-b都表示创建并切换。六、第四步修改文件并提交用任意文本编辑器打开仓库根目录下的 Contributors.md把你的名字加入其中。按文档要求不要加在文件开头或结尾而是插入在名单中间任意位置以尽量降低多人同时编辑同一行引发的合并冲突概率关于冲突的成因与解决见本文第八节。保存文件。回到终端先执行git status查看当前工作区状态git status你会看到Contributors.md出现在变更列表中说明 Git 已经检测到这次修改。接下来把修改加入暂存区staging areagit add Contributors.md然后提交提交信息建议遵循该项目的惯例写法git commit -m Add your-name to Contributors list把your-name替换成你自己的名字。git commit会把暂存区的内容固化为一次新的提交记录。七、第五步Push 到 GitHub 并处理认证本地提交完成后用git push把分支推送到你的 GitHub 副本git push -u origin your-branch-name把your-branch-name替换为前面创建的分支名。-u即--set-upstream会把本地分支与远程同名分支建立关联之后直接执行git push即可。常见的认证错误与处理如果推送时报出类似下面的错误remote: Support for password authentication was removed on August 13, 2021. Please use a personal access token instead. fatal: Authentication failed for https://github.com/your-username/first-contributions.git/说明你的推送地址仍在使用 HTTPS 密码认证。文档明确提示GitHub 已于 2021 年 8 月 13 日移除密码认证现在必须使用个人访问令牌Personal Access Token或 SSH 密钥。推荐的解决路径是配置 SSH 密钥。同时可以先检查当前远程地址git remote -v如果输出类似origin https://github.com/your-username/your_repo.git (fetch) origin https://github.com/your-username/your_repo.git (push)说明origin指向的是 HTTPS 地址可以把它改为 SSH 形式git remote set-url origin gitgithub.com:your-username/your_repo.git改完后重新git push就不会再反复提示输入用户名和密码。仓库内还提供了 storing-credentials.md说明如何安全地保存凭据注意涉及安全策略请遵守所在团队的规定。八、第六步提交 Pull Request推送成功后回到 GitHub 上你自己的仓库副本页面会看到一个Compare pull request按钮。点击它进入 Pull Request 创建页确认对比对象是你的分支与原仓库的 main 分支然后点击创建。Pull Request 本质上是向原仓库维护者发起的一次请审查并合并我的改动的请求。提交后维护者会审查你的改动合并后你会收到通知邮件你的名字也会正式进入 Contributors.md。至此一次完整的fork - clone - edit - pull request贡献流程就走完了。九、从源码文档看进阶之路完成第一次贡献后你已具备开源协作的基本功。此后真正决定协作效率的是对 Git 更多场景的掌握。仓库在 docs/additional-material/git_workflow_scenarios/additional-material.md 中系统整理了进阶主题按需取用即可1. 让 Fork 与上游保持同步开源协作中你 Fork 的副本会随着原仓库的更新而逐渐落后。此时需要引入upstream远程并同步仓库内的 keeping-your-fork-synced-with-this-repository.md 给出了完整的三角工作流原仓库、你的 Fork、你的本地仓库同步方法git remote add upstream https://github.com/firstcontributions/first-contributions.git git fetch upstream git rebase upstream/main git push origin main其中origin指向你自己的 Forkupstream指向原仓库也可以用git pull upstream main一步完成抓取 合并。建议在 GitHub 提示你的分支落后若干提交时执行同步。2. 撤销本地提交如果不小心提交了不该提交的内容undoing-a-commit.md 介绍了分场景的撤销方案git reset仅重置暂存区工作区的修改仍然保留可重新提交git reset file只把指定文件移出暂存区git reset --hard HEAD~2连同工作区改动一起回退两个提交只适用于尚未推送到共享仓库的本地提交否则会影响其他协作者。3. 还原已推送的提交对于已经推送到远程的提交直接 reset 会造成历史重写正确做法是用git revert。如 reverting-a-commit.md 所述先用git log --oneline找到目标提交的 SHA再执行git revert commit-shaGit 会生成一个反向提交来抵消原提交的改动最后git push origin branch-name推送即可。文档还指出git log --oneline显示的每行前 7 位字符就是可用的缩写提交哈希。4. 解决合并冲突当多人同时修改同一文件的同一区域、或一方删除文件而另一方仍在修改时Git 无法自动合并就会产生合并冲突。resolving-merge-conflicts.md 给出了标准解法用git status定位冲突文件在编辑器中识别 HEAD、、 branch-name三组冲突标记手动取舍后删除标记再逐个git add filename最后git commit -m Resolved merge conflicts。也可以使用git mergetool调用可视化合并工具或用git merge --abort放弃本次合并。5. 其他常用场景此外进阶文档还覆盖了修改最近一次提交amending-a-commit.md、把多个提交压缩成一个squashing-commits.mdPR 审查者常会要求、删除本地/远程分支removing-branch-from-your-repository.md、创建.gitignorecreating-a-gitignore-file.md等主题全部可以在 docs/additional-material/git_workflow_scenarios/ 目录下按需查阅。十、不想用命令行图形工具教程同样完整仓库为不习惯命令行的初学者准备了完整的 GUI 工具教程流程与命令行版一一对应Fork → Clone → 建分支 → 改 Contributors.md → 提交 → Push → 发 PR可任选其一GitHub Desktop 教程官方桌面客户端Clone 时还会询问如何计划使用这个 Fork选择为父项目做贡献即可VS Code 教程GitKraken 教程IntelliJ IDEA 教程Visual Studio 2017 教程Sourcetree 教程。十一、小结本文完整还原了 first-contributions 仓库多语言 README以 docs/translations/README.jv.md 为代表所讲述的贡献全流程Fork → Clone → 创建分支 → 修改并提交 → Push → Pull Request并逐条覆盖了git switch与git checkout的兼容写法、GitHub 密码认证移除后的 SSH 配置、git remote -v与git remote set-url排障等实战细节。以此为起点配合仓库 docs/additional-material 下的进阶文档与 docs/gui-tool-tutorials 下的图形工具教程你可以把一次试试看真正变成可持续参与开源社区的协作能力——下一次试着把这个流程应用到任何你感兴趣的开源项目上。【免费下载链接】first-contributions✨ Help beginners to contribute to open source projects项目地址: https://gitcode.com/gh_mirrors/fi/first-contributions创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考