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本仓库的 Lingala 语入门文档 README.ln.md 为骨架完整梳理一名零基础新手从 fork 仓库、clone 到本地、创建分支、修改Contributors.md、提交 commit、推送分支、发起 pull request再到保持 fork 与上游同步的完整链路。读完本文你将掌握这套在开源社区中最高频出现的 fork → clone → edit → pull request 协作流程并具备独立向任意 GitHub 项目提交首次贡献的能力。文档背景一份面向初学者的多语言入门指南first-contributions 是一个以教学为目的的仓库它没有复杂的业务代码核心载体是一份把「第一次开源贡献」拆解为若干可执行步骤的文档以及一个供贡献者实际动手修改的名单文件 Contributors.md。项目的描述本身就说明了定位——Help beginners to contribute to open source projects帮助初学者向开源项目做贡献。为了降低语言门槛主文档 README.md 被翻译成了数十种语言统一存放在 docs/translations/ 目录下并在 Translations.md 中集中索引本次讲解所依据的 README.ln.md 正是其中的 Lingala林加拉语版本。仓库还提供了 LICENSEMIT 协议允许文档被自由学习、复制与传播。这份文档的价值在于它刻意绕开了「先读一堆理论文章」的传统路径而是让学习者直接在一个真实仓库上动手走一遍完整的 GitHub 协作流程——即使犯错也不会破坏任何真实项目这正是它作为教学工具的核心设计。前置准备在本地安装 Git整个流程的第一步是在本机准备好 Git。文档指出如果你的机器上还没有安装 Git需要先完成安装Windows 用户也可以安装 Git Bash以获得与 macOS/Linux 一致的终端体验。安装完成后可以在终端中执行git --version确认 Git 可用。本文后续所有命令均假定你在终端Windows 下为命令提示符或 Git BashmacOS/Linux 下为 Terminal中执行。工作流全景一次贡献涉及哪些环节一次典型的首次贡献在逻辑上包含六个阶段Fork在 GitHub 网页端把目标仓库复制到自己的账户Clone把 fork 出来的仓库下载到本地电脑分支在本地创建一个独立的功能分支修改与提交编辑文件、用git add/git commit记录改动推送用git push把分支推送到 GitHub 的 fork 仓库Pull Request在网页端发起合并请求等待维护者审核合并。除此之外还有两个「事后」环节合并后保持 fork 与上游同步、清理不再需要的分支。下文按文档顺序逐节展开。第一步Fork 仓库打开仓库页面后点击页面顶部的Fork按钮GitHub 会在你自己的账户下生成一份该仓库的完整副本。这一步的本质是「复制」得到的是位于https://github.com/你的GitHub用户名/first-contributions的独立仓库。它与你无关紧要的修改完全隔离无论你在副本里如何操作都不会影响原仓库这正是新手可以放心大胆试错的前提。后续所有操作clone、push都是围绕这份副本进行的。第二步Clone 仓库到本地Fork 之后把副本拉到本地。操作路径是进入自己的 GitHub 账户 → 打开刚 fork 的仓库 → 点击Code按钮 → 切换到SSH标签页 → 点击「复制 URL 到剪贴板」图标。然后在终端执行git clone 你刚刚复制的仓库地址其中引号内的地址使用时去掉引号就是你 fork 出的仓库 URL。文档给出的示例为git clone https://github.com/你的GitHub用户名/first-contributions.git把你的GitHub用户名替换成真实用户名后git clone会把 GitHub 上first-contributions仓库的全部内容包括 Contributors.md、docs/ 等目录下载到本地生成同名目录。一个值得强调的细节是应当 clone 自己 fork 的副本而不是原仓库。因为后续的 push 权限只存在于自己的副本上clone 原仓库将无法把改动推回去。第三步创建功能分支克隆完成后先进入项目目录cd first-contributions然后基于默认分支main创建一条新分支。文档使用的是git checkout语法git checkout -b 你的分支名例如git checkout -b add-emmanuel-binengit checkout -b 分支名的含义是「创建新分支并立即切换过去」-b即--branch。文档特别说明分支名里带add前缀并非强制要求但它能让分支用途一目了然——这条分支就是为了「把你的名字加入名单」而存在的。这也是开源项目里常见的分支命名惯例add-、fix-、docs-等前缀描述意图便于维护者快速理解。兼容性说明git switch 与旧版 Git较新版本的 Git 推荐使用语义更明确的git switchgit switch -c your-new-branch-name如果你执行时遇到Git: switch is not a git command. See git --help之类的报错说明本机 Git 版本较旧switch子命令尚未引入git switch自 Git 2.23 起提供。此时回退到git checkout -b即可两条命令的作用等价。第四步修改 Contributors.md 并提交这是整个练习中唯一涉及「写文件」的步骤也是最能体验真实贡献流程的一步。用任意文本编辑器打开仓库根目录下的 Contributors.md在文件中间任意位置加入自己的名字文档特意提醒不要加在文件开头或结尾保存文件。为什么要求加在中间因为Contributors.md是一个持续增长的名单文件截至本文写作时已有数千行贡献者记录大家都加在开头或结尾会极大地增加合并冲突概率分散在中间则让每个人的改动落点错开降低 PR 冲突风险。这个细节本身就是开源协作中「减少摩擦」的真实写照。回到终端先运行git status查看工作区状态。你会看到类似「有修改」的输出——git status会列出被改动但尚未暂存的文件是提交前必做的检查。把改动加入暂存区stagegit add Contributors.mdgit add把指定文件的改动从工作区放入暂存区是提交前的准备动作。然后生成一次提交git commit -m Add 你的名字 to Contributors list把你的名字替换成你自己的名字。git commit -m用-m参数直接指定提交信息commit message。一次规范的提交信息应简短地说明「本次改动做了什么」这里Add ... to Contributors list就是符合惯例的描述格式。第五步推送分支到 GitHub改动提交到本地分支后还需要推到 GitHub 上 fork 出的远程仓库才能在网页端发起 PRgit push -u origin 你的分支名把你的分支名替换为你之前创建的分支名。这里有两个需要理解的要素originGit 约定的远程仓库名clone 后默认指向你 fork 的仓库-u即--set-upstream把本地分支与远程同名分支建立「上游跟踪」关系。首次推送带上-u后之后在同一分支上只需执行git push即可无需再写远程名和分支名。第六步提交 Pull Request推送成功后回到 GitHub 上你自己的 fork 仓库页面会出现一个醒目的Compare pull request按钮点击它在对比页面确认改动范围源分支是你的新分支目标分支通常是上游仓库的main确认无误后点击提交发出 pull request等待仓库维护者审核。文档明确承诺了后续流程维护者会尽快把你的改动合并进项目主分支合并完成后你会收到一封确认邮件。对新手而言这封邮件意味着「你的第一次开源贡献正式被接纳」。推送失败排查认证错误与 remote 配置新手最常卡住的环节就是推送时的认证错误。文档给出了一个典型报错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/你的用户名/first-contributions.git/这段报错的含义是GitHub 已于 2021 年 8 月 13 日起移除了对 HTTPS 方式密码认证的支持必须改用其他认证手段如 Personal Access Token 或 SSH 密钥。文档给出的处置建议是按照 GitHub 官方的 SSH 教程生成并把公钥配置到自己的账户上让 Git 通过 SSH 完成认证检查当前远程地址确认 clone 时用的协议。先用git remote -v查看本地仓库配置的远程地址-v会同时显示 fetch 与 push 两个地址origin https://github.com/你的用户名/first-contributions.git (fetch) origin https://github.com/你的用户名/first-contributions.git (push)如果地址是 HTTPS 形式可以把它改写成 SSH 形式git remote set-url origin gitgithub.com:你的用户名/first-contributions.gitgit remote set-url的作用是修改已有远程仓库的 URL。如果不做这一步后续每次推送仍会被要求输入用户名密码最终再次撞上认证错误。合并之后保持 fork 与上游同步你的 PR 被合并后fork 仓库的main分支不会自动包含上游的最新改动。为了让自己的副本跟上原仓库的演进尤其在你打算继续贡献时文档提供了标准的「上游同步」流程。1. 切回 main 分支git checkout main2. 添加上游远程git remote add upstream https://github.com/上游维护者/first-contributionsupstream是社区惯例中给「原仓库」起的远程名git remote add upstream url告诉 Git「还有一个版本存在于这个地址我们叫它 upstream」。注意它与origin的区别origin指向你自己的 forkupstream指向被 fork 的原始仓库。3. 拉取上游最新改动git fetch upstreamgit fetch会把 upstream 上的新提交下载到本地但不会改动你当前分支是「只取不并」的安全操作。4. 把上游改动合并进本地 maingit rebase upstream/maingit rebase会把本地main分支上尚未在上游出现的提交重放到upstream/main的最新提交之上从而让本地分支基于最新代码。这是保持分支干净的常用方式相比 mergerebase 不会产生多余的合并提交。5. 推送同步结果git push origin main注意这里的推送目标是origin你自己的 fork把同步后的main推上去fork 仓库就与上游保持一致了。收尾清理已合并的分支同步完成后你那条功能分支的使命已经结束可以安全清理先在本地删除分支git branch -d add-你的名字git branch -d只在分支已合并时才允许删除-D则强制删除这层保护可以防止误删未合并的工作。再删除远程副本上的分支git push origin --delete add-你的名字git push origin --delete 分支名会从远程仓库移除指定分支。文档也提到分支名是否带add-前缀并不影响功能但清晰的分支名能传达意图、让协作对象更容易理解每次提交的目的。进阶路径更多工具与深入话题命令行不是唯一的选择。仓库为不习惯 CLI 的读者准备了多套图形化工具教程对应文档中罗列的教程表格统一位于 docs/gui-tool-tutorials/ 目录GitHub Desktop 教程Visual Studio 2017 教程GitKraken 教程Visual Studio Code 教程Atlassian SourcetreemacOS教程IntelliJ IDEA 教程这些图形化工具覆盖了同样的 fork → clone → 修改 → PR 流程适合偏好可视化操作的学习者。如果你已完成基础流程、想进一步掌握真实的协作技能进阶材料 汇总了一批「第二次贡献」才会遇到的 Git 高级话题包括修改最近一次提交amend commit、撤销本地提交undo/reset commit回滚已推送的提交revert commit、移动提交到其他分支保持 fork 与上游同步、解决合并冲突resolving merge conflicts用交互式 rebase 压缩提交squash commits应对评审者「合并多个 commit」的要求配置 Git 用户信息、创建.gitignore、存储凭据storing credentials等。这些话题分别对应 docs/additional-material/git_workflow_scenarios/ 下的独立文档例如 amending-a-commit.md、resolving-merge-conflicts.md 等可按需查阅。结语回顾整条路径fork 建副本 → clone 到本地 → 建分支 → 改Contributors.md→ add/commit 记录 → push 推送 → 发起 PR → 合并后与上游同步 → 清理分支。这套流程覆盖了 GitHub 协作中 90% 的高频操作是每一位开源贡献者的必修课。first-contributions 的教学设计值得借鉴它用一个真实的仓库、一份需要你动手编辑的文件把「理论恐惧」转化为「一次可验证的成功」。当你收到合并确认邮件的那一刻你已经不是旁观者而是一位真正向开源项目提交过代码的贡献者。接下来要做的就是带着这套流程走向更大的项目。【免费下载链接】first-contributions✨ Help beginners to contribute to open source projects项目地址: https://gitcode.com/gh_mirrors/fi/first-contributions创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考