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.sr-Latn.md 为核心逐步骤拆解fork → clone → edit → pull request这一开源协作经典工作流并结合仓库内的 Contributors.md、进阶文档与 GUI 教程帮助初学者在真实仓库中完成第一个开源贡献同时掌握每次贡献都会用到的 Git 命令、分支规范与常见报错处理。一、项目定位与本文文档背景first-contributions 是一个以教学为唯一目的的开源仓库它的 README 本身就是活教材。初学者不需要先学习整套 Git 理论只需按照 README 的指引一步步操作把名字加入 Contributors.md 贡献者名单就能真实地走完一次完整的代码贡献流程。本文依据的 docs/translations/README.sr-Latn.md 是该项目 README 的塞尔维亚语拉丁字母版本与根目录 README.md英文原版内容同构仓库还在 docs/translations/README.sr-Cyrl.md 提供了塞尔维亚语西里尔字母版本。整个仓库通过 docs/translations/Translations.md 维护了数十种语言的入口索引体现了开源项目降低语言门槛的社区文化。仓库采用 MIT 许可证README 徽章标注。二、动手前的准备git 环境与 GitHub 账号原文开篇明确提示如果本机还没有安装 git请先完成安装文档指向 GitHub 官方的 Set up Git 指引本文以文字说明替代外部链接。安装完成后可以在终端执行以下命令确认环境就绪git --version除此之外还需要一个 GitHub 账号用于 fork 仓库、创建 pull request一种认证方式推荐提前配置 SSH 密钥如果使用 HTTPS 地址则需准备 personal access token密码认证已于 2021 年 8 月 13 日起被 GitHub 移除详见下文认证错误一节。三、第一步Fork 仓库概念fork 是在你自己的 GitHub 账号下创建原仓库的一份完整副本。此后所有的改动都发生在自己的副本里不会影响原仓库这是开源协作中先分叉、再合并的基础。操作打开本仓库页面点击页面顶部的Fork按钮。完成后你的账号下会出现一个first-contributions仓库副本。四、第二步克隆仓库到本地概念clone克隆会把 GitHub 上 fork 出来的仓库完整下载到本地机器之后才能在本地编辑文件。获取克隆地址进入自己的 GitHub 账号打开刚刚 fork 出来的first-contributions仓库点击Code按钮切换到SSH标签页点击复制 URL 到剪贴板图标复制地址。执行克隆打开终端运行以下 git 命令git clone url you just copied其中url you just copied不带引号替换为刚复制的、指向你自己 fork 副本的仓库地址。例如git clone gitgithub.com:this-is-you/first-contributions.git其中this-is-you代表你的 GitHub 用户名。这条命令会把 GitHub 上 first-contributions 仓库的内容完整复制到你的电脑上。补充原理git clone在复制内容的同时会默认把来源仓库注册为名为origin的远程引用并检出默认分支main、建立本地分支与远程分支的跟踪关系因此后续git push、git pull可以直接基于origin工作这是克隆后开箱即用的原因。五、第三步创建专属分支先进入克隆下来的仓库目录如果尚未进入cd first-contributions然后使用git switch命令创建新分支并切换过去git switch -c your-new-branch-name例如git switch -c add-alonzo-church参数说明-c是--create的缩写含义是创建名为your-new-branch-name的新分支并立即切换到该分支。兼容旧版 git文档特别给出了一个常见报错场景——如果命令执行后提示Git: switch is not a git command. See git –help说明你使用的是较旧版本的 git尚未引入git switch此时改用传统写法即可git checkout -b your-new-branch-name为什么必须建分支这是开源协作的基本规范。每个 pull request 应当对应一个独立的功能分支把不相关的改动隔离在不同分支中既方便维护者逐个审查也便于自己在多个任务之间切换。文档示例中add-alonzo-church这类动词-对象式命名add-你的名字也是社区中常见的命名习惯。六、第四步修改文件并提交修改文件用文本编辑器打开仓库根目录下的 Contributors.md 文件在文件中加入你的名字。文档特别强调不要加在文件开头或结尾请加在中间任意位置然后保存文件。这个文件正是本教程的练兵场——它是真实存在的贡献者名单当前仓库中已积累 5920 行每位学习者的贡献就是把名字追加进这份名单从而在不涉及复杂业务代码的情况下完整体验提交流程。查看变更回到项目目录执行git status可以看到有改动存在Contributors.md会出现在未暂存的更改区域。暂存改动使用git add把改动加入刚刚创建的分支git add Contributors.md提交改动使用git commit提交git commit -m Add your-name to Contributors list将命令中的your-name替换为你的真实名字。-m参数用于直接指定提交信息避免打开交互式编辑器。底层原理补充这条流程对应 Git 的三区模型——工作区你编辑文件的地方→ 暂存区git add后改动被记录但尚未入库→ 本地版本库git commit后改动正式成为一次提交。git status正是用来观察文件在这三个区域之间流转状态的命令未暂存的改动与已暂存的改动会分别展示是提交前检查内容是否完整的重要工具。七、第五步推送到 GitHub使用git push把本地提交推送到 GitHubgit push -u origin your-branch-name将your-branch-name替换为之前创建的分支名。参数说明origin默认的远程仓库名即你 fork 出来的 GitHub 仓库-u--set-upstream建立本地分支与远程分支的跟踪关系。加上它之后以后在这个分支上执行git push/git pull可以直接省略远程名和分支名your-branch-name要推送的本地分支名。常见错误认证失败文档用较大篇幅专门处理了 push 阶段最常见的报错。自 2021 年 8 月 13 日起GitHub 移除了 HTTPS 协议的密码认证只能使用 personal access token 或 SSH 密钥。典型报错信息如下remote: Support for password authentication was removed on August 13, 2021. Please use a personal access token instead. remote: Please see https://github.blog/2020-12-15-token-authentication-requirements-for-git-operations/ for more information. fatal: Authentication failed for https://github.com/your-username/first-contributions.git/处理步骤为你的账号生成并配置 SSH 密钥文档建议参照 GitHub 官方的 SSH 密钥添加教程操作此处以文字说明替代外部链接先检查当前远程地址是否确实指向 HTTPSgit remote -v如果输出类似origin https://github.com/your-username/your_repo.git (fetch) origin https://github.com/your-username/your_repo.git (push)将远程地址切换为 SSH 格式git remote set-url origin gitgithub.com:your-username/your_repo.git否则 push 时仍会被反复要求输入用户名和密码并最终报认证错误。八、第六步提交 Pull Request推送成功后回到 GitHub 上你自己的 fork 仓库页面会出现一个Compare pull request按钮点击该按钮进入 pull request 创建页面确认改动内容无误后点击提交 pull request维护者审核后会把这些改动合并进项目的主分支main合并完成后你会收到邮件通知。至此一个贡献从想法到合入上游仓库的完整链路就打通了。值得说明的是仓库根目录的 Contributors.md 中那数千行名单正是由无数个这样的小型 pull request 累积而成这本身就是开源协作力量最直观的证明。九、完成之后的进阶方向恭喜你已经完成了标准的fork → clone → edit → pull request工作流——这是作为开源协作者最常遇到、也最重要的标准流程。完成首秀之后文档给出了三个进阶方向更多练习继续在其他练习项目中反复打磨这套流程参与真实项目从带有easy issue标签的简单问题入手开始为其他开源项目做贡献学习进阶 Git 技巧本仓库在 docs/additional-material/git_workflow_scenarios/additional-material.md 汇总了一系列实战场景文档覆盖协作中会反复遇到的进阶问题进阶主题仓库文档路径修改amend最近一次提交docs/additional-material/git_workflow_scenarios/amending-a-commit.md配置 git 用户信息等选项docs/additional-material/git_workflow_scenarios/configuring-git.md保持 fork 与上游仓库同步docs/additional-material/git_workflow_scenarios/keeping-your-fork-synced-with-this-repository.md把提交移动到其他分支docs/additional-material/git_workflow_scenarios/moving-a-commit-to-a-different-branch.md从本地仓库删除文件docs/additional-material/git_workflow_scenarios/removing-a-file.md从仓库删除分支docs/additional-material/git_workflow_scenarios/removing-branch-from-your-repository.md解决合并冲突docs/additional-material/git_workflow_scenarios/resolving-merge-conflicts.md撤销revert已推送的提交docs/additional-material/git_workflow_scenarios/reverting-a-commit.md用交互式 rebase 合并squash提交docs/additional-material/git_workflow_scenarios/squashing-commits.md撤销本地提交docs/additional-material/git_workflow_scenarios/undoing-a-commit.md学习资源汇总docs/additional-material/git_workflow_scenarios/Useful-links-for-further-learning.md创建 .gitignore 文件docs/additional-material/git_workflow_scenarios/creating-a-gitignore-file.md安全地存储凭证docs/additional-material/git_workflow_scenarios/storing-credentials.md此外该目录还收录了why-using-branches.md、rebase-vs-merge.md、resetting-a-branch.md、resetting-a-commit.md、stashing-a-file.md、check-commit-log.md、gitflow.md、delete-branch-locally.md等更多实战场景文档可作为持续进修的索引。十、不习惯命令行用 GUI 工具完成同样流程如果命令行让你感到不适文档明确给出了替代路径仓库在 docs/gui-tool-tutorials 目录下维护了多款图形界面工具的完整教程覆盖了主流平台与 IDE工具教程路径GitHub Desktopdocs/gui-tool-tutorials/github-desktop-tutorial.mdVisual Studio 2017docs/gui-tool-tutorials/github-windows-vs2017-tutorial.mdGitKrakendocs/gui-tool-tutorials/gitkraken-tutorial.mdVisual Studio Codedocs/gui-tool-tutorials/github-windows-vs-code-tutorial.mdAtlassian Sourcetreedocs/gui-tool-tutorials/sourcetree-macos-tutorial.mdIntelliJ IDEAdocs/gui-tool-tutorials/github-windows-intellij-tutorial.md该目录还包含旧版 GitHub Desktop 教程 github-desktop-old-version-tutorial.md、Sublime Merge 教程 sublime-merge-tutorial.md 以及 translations 多语言子目录基本覆盖了各类开发环境。结语回顾整条路径fork 建立自己的副本 → clone 拉到本地 → 新建分支隔离改动 → 编辑文件并 commit 记录 → push 推回远程 → 提交 pull request 请求合并。这套流程既是 first-contributions 项目的核心教学主线也是所有开源项目协作的通用范式。无论你后续参与多少个项目遇到多少次 review 意见、合并冲突或版本回退本文涉及的这些基础命令与 进阶文档 都会是你最可靠的工具箱。【免费下载链接】first-contributions✨ Help beginners to contribute to open source projects项目地址: https://gitcode.com/gh_mirrors/fi/first-contributions创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考