first-contributions 首次开源贡献实战指南从 fork 到 pull request 的完整 Git 流程【免费下载链接】first-contributions✨ Help beginners to contribute to open source projects项目地址: https://gitcode.com/gh_mirrors/fi/first-contributions本指南基于 first-contributions 仓库的乌兹别克语版入门教程 docs/translations/README.uz.md 编写面向零基础开发者完整讲解在开源项目中提交第一次代码贡献的标准流程fork → clone → 新建分支 → 修改 → commit → push → pull request。读完本文你将掌握这套可复用于任何 GitHub 协作项目的核心 Git 操作并能独立排查 push 时的认证错误、保持 fork 与上游仓库同步等常见问题。一、这份指南解决什么问题first-contributions 项目的定位非常聚焦简化并引导初学者完成第一次开源贡献。正如 README.md 所描述它假设读者对 Git 与 GitHub 协作几乎一无所知因此把第一次提交贡献这件事拆解为几个明确步骤每一步都有对应的命令与图解。这一流程之所以重要是因为它几乎是所有开源协作的最小公共集无论是修改文档、修复 bug 还是新增功能Contributor 的日常都离不开_fork - clone - edit - pull request_这条链路。在乌兹别克语教程 docs/translations/README.uz.md 中作者用乌兹别克语完整复述了这套流程并补充了 push 阶段的认证错误处理细节——这正是本篇要逐条展开讲解的内容。仓库内的 Contributors.md 是这套流程的试验田它是一份纯文本的贡献者名单目前已累积 5900 余行全部由历届初学者通过 pull request 把自己的名字添加进去。你可以把它理解为一次零风险的演练——没有编译、没有测试、没有代码审查压力只需学会 Git 协作的基本功。说明如果你不习惯命令行操作本仓库还提供了基于 GitHub Desktop、VS Code 等 GUI 工具的教程详见文末第六节。二、环境准备确保本机安装并验证 Git整个流程依赖git命令行工具。乌兹别克语教程开篇就强调如果电脑上还没有 Git请先安装。不同操作系统的安装方式不同仓库在 docs/additional-material/git_workflow_scenarios/installing-git-ubuntu.md 和 docs/additional-material/git_workflow_scenarios/installing-git-arch.md 中提供了 Ubuntu 与 Arch 系 Linux 的安装说明其他平台可参照官方安装包。安装完成后在终端执行以下命令确认 Git 可用且版本符合要求git --version输出形如git version 2.x.x即表示安装成功后续教程中的git switch命令需要 Git 2.23 及以上版本若版本过旧会报错对应处理方式见第四步。关于本仓库的克隆地址教程中用于演练的克隆地址是你 fork 之后的仓库地址形如https://github.com/你的用户名/first-contributions.git并非本项目主页本身。clone 命令只会把目标仓库的当前内容复制到本地不会影响远程仓库。三、第一步与第二步Fork 仓库并 Clone 到本地Fork在 GitHub 上复制一份仓库到你的账户打开 first-contributions 的仓库页面点击页面顶部的Fork按钮。Fork 会在你的 GitHub 账户下创建该仓库的一份完整副本。这一步的意义在于你无法直接向别人的仓库提交修改但可以在自己的副本上任意操作之后再通过 pull request 把修改请求合并回去。Clone把 fork 的副本下载到本地Fork 完成后进入你账户下的 first-contributions 副本页面点击页面上的Code按钮复制仓库 URL点击剪贴板图标在本地打开终端执行git clone 你刚刚复制的URL注意URL 不需要加引号引号只是为了标识占位内容。教程给出的示例为git clone https://github.com/bu-siz/first-contributions.git其中bu-siz这是你要替换为你的 GitHub 用户名。这条命令会把 first-contributions 仓库的全部内容下载到你当前目录下生成一个名为first-contributions的本地文件夹。四、创建分支branch进入本地仓库目录cd first-contributions接下来创建一个独立的分支用于承载你的修改。分支是 Git 协作的核心概念它让你在平行时空里工作不会干扰main主分支也便于维护者单独审查你的改动。教程推荐使用git switch命令git switch -c 你的新分支名其中-c是--create的简写表示创建并切换到新分支。命名示例git switch -c new_branch # 例如 add-你的名字从仓库内其他文档的惯例看如 github-desktop-tutorial.md 中建议的分支名add-james-smith推荐用add-你的名字这种动词对象的命名方式让维护者一眼看出这个分支做了什么。老版本 Git 的兼容写法教程专门用折叠块处理了一个常见报错如果执行git switch时出现Git: switch is not a git command. See git --help说明你本地的 Git 版本过旧低于 2.23此时改用传统命令即可git checkout -b 你的新分支名git checkout -b与git switch -c功能等价都创建分支并切换过去只是命令语法不同。五、修改文件、暂存并提交commit编辑 Contributors.md在文本编辑器中打开仓库根目录下的 Contributors.md把你的名字添加进去。教程特别强调不要加在文件开头或结尾而是加在任意中间位置——这样做的目的是让你在后续提交时真实地面对冲突可能性如果所有人都往文件头部添加pull request 之间极易发生冲突中间位置相对分散能降低新手第一次协作就撞上冲突的概率。保存文件后在项目目录执行git statusGit 会列出当前工作区的变更状态此时应能看到Contributors.md处于modified已修改状态。养成每次操作前后都跑git status的习惯是新手避免改错文件忘了提交最有效的自查手段。暂存add并提交commit先把改动加入暂存区git add Contributors.md然后创建一次提交git commit -m Contributors royxatiga ismingiz-ni kiritish这是乌兹别克语教程中的提交信息意为将你的名字加入贡献者列表。在实际操作中应替换为符合你自己内容的提交信息例如git commit -m Add your-name to Contributors list。-m参数用于直接在命令行附带提交信息避免进入交互式编辑器。至此你的修改已经以一次 commit 的形式固化在本地分支上。但从仓库的附加材料可以看到Git 还有大量围绕 commit 的进阶操作如amend修改最近一次提交、revert撤销已推送的提交、squash合并多个提交这些会在你后续参与真实项目时派上用场详见第七节。六、Push 到 GitHub 及认证错误排查本地提交完成后需要把分支推送到你在 GitHub 上的 fork 仓库git push origin -u new_branch # 替换为你创建的分支名参数说明origin本地 Git 对你 GitHub 上 fork 仓库的默认远程引用名-u即--set-upstream首次推送时把本地分支与远程分支建立关联之后就可以直接使用git push无需再带参数。常见的认证错误及处理教程专门列出了一种出现频率极高的 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/这意味着GitHub 已于 2021 年 8 月 13 日起彻底移除了 HTTPS 协议下的账号密码认证继续使用用户名密码推送会被拒绝。解决方案有二改用个人访问令牌Personal Access Token在 GitHub 账户设置中生成 tokenpush 时以 token 代替密码输入改用 SSH 认证生成 SSH 密钥并配置到 GitHub 账户。仓库的附加材料 storing-credentials.md 也提醒凭据存储涉及安全问题应遵循所在单位或学校的安全策略。如果你此前 clone 时使用的是 HTTPS 地址可以通过以下命令把远程地址切换为 SSH 形式避免每次推送都被反复要求输入用户名密码git remote -v # 先查看当前远程地址 git remote set-url origin gitgithub.com:你的用户名/你的仓库名.gitgit remote -v是排查远程地址配置问题的第一利器如果输出中的地址与你预期的 fork 地址不一致push 就必然失败。七、提交 Pull Request把改动交给维护者审查Push 成功后回到你在 GitHub 上的 fork 仓库页面页面顶部会出现一个醒目的Compare pull request按钮点击它。Pull Request简称 PR是向原仓库维护者发出的合并请求GitHub 会展示你的分支与原仓库main分支之间的差异维护者审阅后决定是否合并。教程中承诺一旦你的修改被合并进项目的main分支你会收到邮件通知。提交 PR 是整个流程的终点也是你作为 Contributor 的毕业仪式。合并后你的名字就正式出现在 Contributors.md 中了——仓库里那 5900 余行名字正是这一流程被反复验证过的证据。八、保持 fork 与上游同步开源协作的进阶必修课教程在流程完成后引导读者进入仓库的附加材料继续深造。其中最重要的一课是keeping-your-fork-synced-with-this-repository.md 讲解的Triangle Workflows三角工作流上游公共仓库原项目upstream你的 forkGitHub 上的副本origin本地仓库你电脑上的工作区。只要你想持续参与一个项目就必须定期把上游仓库的新提交同步到自己的 fork 和本地否则你的分支会逐渐落后最终合并时产生大量冲突。同步的标准步骤为git checkout main # 回到主分支 git remote add upstream 上游仓库URL # 首次登记上游远程 git fetch upstream # 拉取上游最新提交 git rebase upstream/main # 把本地 main 重放到上游最新提交之上 git push origin main # 把同步结果推送到你的 fork如果只想一次性完成拉取并合并也可以简写为git pull upstream main实践建议每次 GitHub 提示你的 fork 落后于上游若干 commit 时就执行一遍上述同步流程。九、其他工具教程与进阶学习路线如果命令行让你望而生畏仓库为同一套流程提供了完整的 GUI 工具教程操作步骤与命令行版一一对应工具教程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更高阶的 Git 技能清单完成第一次贡献后建议按需阅读 docs/additional-material/git_workflow_scenarios/additional-material.md 中罗列的进阶主题它们几乎覆盖了开源协作中你会遇到的所有 Git 场景修改与撤销amending-a-commit.md修改最近一次提交、reverting-a-commit.md撤销已推送的提交、undoing-a-commit.md重置本地提交分支管理moving-a-commit-to-a-different-branch.md、removing-branch-from-your-repository.md冲突与整理resolving-merge-conflicts.md合并冲突、squashing-commits.md提交压缩日常配置configuring-git.md用户信息配置、creating-a-gitignore-file.md.gitignore、storing-credentials.md凭据存储。另外docs/translations/Translations.md 汇总了本仓库 100 余种语言版本的教程索引中文读者可以直接阅读 docs/translations/README.zh-cn.md 对应的中文版本。十、总结从演练到真实贡献回顾一下你在本文中学到的完整链路Fork上游仓库得到自己的副本Clone到本地建立工作区git switch -c创建分支老版本 Git 用git checkout -b编辑 Contributors.md并git status确认变更git addgit commit固化修改git push -u origin 分支名推送到 fork注意 GitHub 已移除密码认证需使用 token 或 SSH点击 Compare pull request把修改提交给维护者审查合并。这套流程在 first-contributions 仓库中被数千名初学者实践过安全、无风险、可反复演练。走完一遍之后你可以把同样的方法迁移到任何真实开源项目找到标有 good first issue 的易上手任务Fork、改代码、提 PR——此时你已经是具备完整协作能力的 Contributor 了。【免费下载链接】first-contributions✨ Help beginners to contribute to open source projects项目地址: https://gitcode.com/gh_mirrors/fi/first-contributions创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考