first-contributions 首次贡献实战从 fork 到 pull request 的完整开源协作流程README.mm_unicode 指南深度解读【免费下载链接】first-contributions✨ Help beginners to contribute to open source projects项目地址: https://gitcode.com/gh_mirrors/fi/first-contributions导读first-contributions 是一个专门帮助开源新手完成人生第一次代码贡献的教学仓库其使命是让第一次总是最难的开源参与过程变得简单、直接、可操作。本篇文章以仓库中面向缅甸语Unicode读者的官方指南 README.mm_unicode.md 为骨架结合仓库主 README.md、Contributors.md 与进阶文档逐条拆解从 fork、clone、创建分支、修改提交、push 到提交 pull request 的完整命令链路并补充仓库源码级的佐证与常见错误排查帮助你一次跑通标准的开源贡献工作流。一、文档定位这份指南在仓库中的角色在仓库的 docs/translations 目录下存放着 README 的数十种语言翻译版本README.mm_unicode.md 是其中之一缅甸语、Unicode 编码。它并非独立的附加教程而是与主 README 内容一一对应的完整实操指南从项目立意、Fork 仓库、Clone 仓库、创建分支、修改并提交、Push 到 GitHub、提交 Pull Request到后续学习路径全部覆盖。文档开篇点明了这个项目的核心学习理念教程和视频固然有帮助但没有什么比真正动手实践更好只要按步骤执行你的第一次贡献就能顺利完成。全文围绕一条主线展开——fork → clone → edit → pull request这是几乎所有开源项目都会遇到的经典协作流程。二、开始之前环境准备与仓库结构文档在进入正式步骤前提醒读者如果电脑上还没有安装 Git需要先完成 Git 的安装配置英文版主 README.md 中同样在开头给出了安装指引。安装完成后需要理解这个练习仓库的结构仓库根目录的 README.md英文主指南与缅甸语版内容一一对应并包含更多故障排查细节如git switch的旧版本兼容提示、push 时的认证错误处理Contributors.md练习提交的目标文件记录了数千名贡献者的名字当前文件已有近 6000 行格式为- 姓名的列表docs/translations全部语言的 README 翻译docs/additional-material进阶 Git 技巧索引docs/gui-tool-tutorials面向不使用命令行的读者的 GUI 工具教程。如果你的目标是完成一次真实的开源贡献练习你的任务就是把自己的名字加入 Contributors.md 的列表中间并通过 pull request 提交给仓库维护者合并。三、第一步Fork 这个仓库文档的第一个实操步骤是Fork。在仓库页面右上角点击Fork按钮这个仓库就会以完全相同的内容复制一份到你的 GitHub 账号名下。Fork 的意义在于你没有主仓库的直接写权限但拥有自己账号下这份副本的完全控制权后续所有修改都先在自己的副本中进行。从仓库的视角看Fork 之后你会同时拥有两个仓库上游公共仓库维护者所有和你自己的 fork。这种上游 你的 fork 你的本地仓库三方协作模式是开源协作的基础形态进阶文档 keeping-your-fork-synced-with-this-repository.md 中称之为三角形工作流Triangle Workflows。四、第二步Clone 到本地Fork 完成后进入你账号下的 fork 仓库点击Code按钮复制仓库 URL 到剪贴板然后在终端中执行git clone 你刚刚复制的链接注意引号只是占位提示实际执行时不需要输入引号。文档给出的示例将this-is-you替换为你自己的 GitHub 用户名git clone https://github.com/this-is-you/first-contributions.git这一步的作用是把 GitHub 上你 fork 的仓库完整复制到本地电脑。英文主 README.md 中展示的是 SSH 形式gitgithub.com:this-is-you/first-contributions.git两种形式本质相同区别只在于认证方式HTTPS 使用令牌token认证SSH 使用密钥认证。Clone 完成后你就拥有了一份可以在本地自由编辑的仓库副本。五、第三步创建自己的分支进入仓库目录并创建新分支cd first-contributions git checkout -b your-new-branch-name分支名可以随意命名但文档特别建议由于这个项目会把你的名字加入贡献者列表最好使用语义化、能体现新增贡献者含义的名字。文档给出的示例是git checkout -b add-alonzo-churchgit checkout -b的含义是创建分支并切换过去-b后面的名字是新分支名。这里有一个值得注意的补充英文主 README.md 使用的是更新的git switch -c写法git switch -c add-alonzo-church并附带说明——如果出现Git: switch is not a git command的错误说明你用的是旧版本 Git此时回退使用git checkout -b即可。本指南README.mm_unicode.md选择直接使用兼容性更好的git checkout -b两种写法在当前场景下效果完全一致。创建分支后你的所有修改都会在这个新分支上进行不会影响main或master分支——这正是 Git 分支协作的核心价值。六、第四步修改文件并提交commit这是整个流程中与仓库实体文件交互的关键环节。操作目标文件是仓库根目录的 Contributors.md。打开文件用任意文本编辑器打开Contributors.md添加名字文档明确要求——不要加在文件开头也不要加在文件末尾而是加在中间的任意位置格式仿照现有条目。查看 Contributors.md 的实际内容可以确认现有格式- [Conner Brown](https://github.com/thathallow) Github is an incredibly useful tool. - [Sachin Kumar](https://github.com/ST-SACHIN-KUM)即- 你的名字可以附上一句简短的个人说明保存文件查看改动在项目目录下执行git status会看到Contributors.md显示为已修改modified确认改动符合预期暂存改动git add Contributors.mdgit add将文件改动加入暂存区staging area只提交这一份文件避免误提交无关改动提交改动git commit -m Add your-name to Contributors list将your-name替换为你的真实姓名。-m参数后的信息是提交说明清晰的提交信息是良好协作习惯的体现。至此你的改动已经以一次提交commit的形式记录在本地的add-xxx分支上但还没有离开你的电脑。七、第五步Push 到 GitHub接下来把本地分支推送到你 GitHub 上的 forkgit push origin add-your-branch-name把add-your-branch-name替换为你第三步创建的分支名例如add-alonzo-church。这里的origin是本地仓库对你 GitHub fork 的远程别名——clone 时 Git 会自动为原始来源设置origin这个名字。英文主 README.md 使用的是带-u参数的等价写法git push -u origin your-branch-name-u即--set-upstream会把本地分支与远程分支建立跟踪关系之后在该分支上直接执行git push即可无需再写远程名和分支名。常见错误排查主 README.md 记录了 push 时最常见的认证错误——remote: Support for password authentication was removed... fatal: Authentication failed。这是因为 GitHub 已不再支持密码方式推送需要改用个人访问令牌Personal Access Token或 SSH 密钥。排查方法先执行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 RequestPush 成功后回到你 GitHub 上的 fork 仓库页面会看到一个醒目的Compare pull request按钮点击它确认对比双方base是目标仓库first-contributions 主仓库的main分支compare是你刚推送的add-xxx分支检查页面显示的改动内容确实是你在 Contributors.md 中加入的名字点击提交 Pull Request。提交后仓库维护者会把你的改动合并进主仓库的mainmaster分支。文档说明合并完成后你会收到通知邮件。你的第一次开源贡献就此完成。九、接下来学什么进阶路径与保持 fork 同步文档在恭喜读者完成标准流程后给出了清晰的进阶路径这也是原文档的重要组成部分对应仓库中一系列可继续阅读的文档1. 进阶 Git 技巧文档推荐的入口是 additional-material.md其中汇集了开源协作中高频使用的进阶操作例如amending-a-commit.md修改最近一次提交如补充遗漏的改动、修正提交信息resolving-merge-conflicts.md解决合并冲突squashing-commits.md将多个提交压缩为一个PR 评审者常会要求reverting-a-commit.md回退已推送到远程的提交undoing-a-commit.md撤销本地提交removing-a-file.md、removing-branch-from-your-repository.md删除文件与删除分支configuring-git.md配置 Git 用户信息与各项选项creating-a-gitignore-file.md创建 .gitignore 文件。2. 保持 fork 与上游同步首次贡献完成后随着你和其他人不断贡献你 fork 的副本会逐渐落后于主仓库。进阶文档 keeping-your-fork-synced-with-this-repository.md 给出了标准的同步流程这也解释了 fork → clone → PR 协作背后的三角形工作流# 1. 确认自己在 main 分支不在则切换 git checkout main # 2. 将上游公共仓库添加为名为 upstream 的远程 git remote add upstream https://github.com/firstcontributions/first-contributions.git # 3. 拉取上游最新内容 git fetch upstream # 4. 将上游 main 合并进本地 main git rebase upstream/main # 5. 推送本地 main 到你的 forkorigin git push origin main如果希望一步完成拉取并合并也可以直接使用git pull upstream main。文档强调每当 GitHub 提示你的 fork 落后于上游若干提交时就应该执行一次上述同步。3. 使用 GUI 工具完成相同流程如果你对命令行不熟悉文档还提供了完整的 GUI 工具替代教程列表以仓库相对路径给出与文档中目录一一对应GitHub DesktopVisual Studio 2017GitKrakenVisual Studio CodeAtlassian SourcetreeIntelliJ IDEA这些教程覆盖了主流桌面客户端与 IDE 集成方案与命令行流程殊途同归。十、总结一套流程终身受用回顾全文README.mm_unicode.md 传授的本质上是一套可以在任何 GitHub 开源项目中复用的标准贡献流程步骤命令/操作作用Fork页面点击 Fork 按钮在账号下创建主仓库副本Clonegit clone fork-URL将 fork 复制到本地建分支git checkout -b branch-name创建并切换新分支修改编辑 Contributors.md在列表中间加入自己的名字提交git add Contributors.md与git commit -m ...暂存并记录改动推送git push origin branch-name将分支推送到 GitHub fork合并点击 Compare pull request请求维护者合并改动这套fork → clone → edit → pull request的工作流贯穿于几乎所有开源协作场景。把名字写进 Contributors.md 只是一个开始——它证明你已掌握了 Git 协作的基本动作在独立分支上工作、以提交为单位记录改动、通过 pull request 请求合并。后续无论是修复 issue、实现功能还是参与文档建设底层都是同一套流程的延伸与组合。【免费下载链接】first-contributions✨ Help beginners to contribute to open source projects项目地址: https://gitcode.com/gh_mirrors/fi/first-contributions创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考