first-contributions 新手开源首贡献实战指南Fork、Clone、改代码、提 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.no.md 挪威语版本为骨架系统讲解新手向开源项目提交第一个贡献的完整流程Fork → Clone → 新建分支 → 修改并提交 → Push → 提交 Pull Request。读完本文你将掌握这套在所有开源协作中反复出现的标准工作流并学会处理最常见的 push 认证报错为后续参与其他开源项目打下扎实基础。项目与文档背景first-contributions 是一个专门帮助初学者迈出开源贡献第一步的教学型仓库。正如其挪威语 README 开篇所述第一次做某件事总是困难的尤其是在与他人协作时犯错会让人有压力。我们希望让新手更容易为开源项目做出贡献。原文Det er alltid vanskelig å gjøre noe for første gang... Vi ønsker å gjøre det lettere for nybegynnere å bidra til open-source.阅读文章和观看视频可以有所帮助但纸上得来终觉浅该项目的核心思路是让新手直接上手实践通过一个真实可运行的最小任务——把自己的名字写进 Contributors.md——完整体验一次真实的开源贡献流程。值得一提的是Contributors.md 当前已积累了数千行贡献者名单本仓库中该文件约有 5920 行这正是无数开发者通过本教程完成首次贡献后留下的真实痕迹也是本教程先实践、后理论理念的最好证明。同时README 已被翻译为 80 多种语言完整索引见 docs/translations/Translations.md挪威语版本即位于 docs/translations/README.no.md。若你不习惯使用终端可以跳到文末的其他工具教程一节那里提供了 GitHub Desktop、VS Code、IntelliJ 等 GUI 工具的教学入口。前置准备安装 Git在执行任何操作之前请确认你的机器上已经安装了 Git。如果尚未安装请先参照官方安装文档完成配置本仓库的 docs/additional-material/git_workflow_scenarios/installing-git-ubuntu.md 与 installing-git-arch.md 分别提供了 Ubuntu 与 Arch Linux 下的安装指引。安装完成后建议先按 docs/additional-material/git_workflow_scenarios/configuring-git.md 配置你的用户名与邮箱git config --global user.name与git config --global user.email否则第一次git commit会被 Git 拦截并提示 Please tell me who you are。第一步Fork 这个仓库Fork 操作的本质是在你自己的账号下创建一份当前仓库的完整副本。操作方式很简单——点击本仓库页面顶部的Fork按钮即可。完成之后你的 GitHub 账号下就会出现一个名为first-contributions的仓库副本在 GitHub 中仓库被称为 repository。Fork 与直接 Clone 的关键区别在于你 Fork 出的副本归你所有你可以自由地向它 Push 代码而原始仓库upstream你没有写权限只能通过 Pull Request 请求维护者合入你的改动。这正是整个协作流程的起点。第二步Clone 仓库到本地Fork 完成后需要把副本从 GitHub 拉到你的本地机器。操作如下进入你的 GitHub 账号打开刚 Fork 出来的仓库点击绿色的Code按钮复制弹窗中给出的仓库地址URL。然后在终端中执行克隆命令git clone din-link把din-link替换为你上一步复制的地址。例如如果你的 GitHub 用户名是ditt-brukernavn则命令形如git clone https://github.com/ditt-brukernavn/first-contributions.git这条命令会把 first-contributions 项目的全部内容从你的 GitHub 账号复制到本地机器。第三步创建自己的分支Branch分支branch是 Git 最重要的协作机制之一它让你可以在不影响主分支main/master的情况下独立开发这也是开源项目要求贡献者在独立分支上工作的原因。相关理念可进一步阅读 docs/additional-material/git_workflow_scenarios/why-using-branches.md。先进入项目目录cd first-contributions然后使用git checkout命令创建并切换到新分支git checkout -b navn-til-branch-her其中navn-til-branch-her替换为你想要的分支名。例如git checkout -b add-alonzo-church分支名不一定要包含add这个词但在向 Contributors 名单添加自己这个场景下以add-开头是符合惯例的命名方式能让维护者一眼看出这个分支做了什么。把示例中的alonzo-church换成你自己的名字即可。第四步修改文件并提交Commit现在进入本次贡献的核心环节——修改文件。用任意文本编辑器打开仓库根目录下的 Contributors.md把你的名字添加进贡献者名单。注意原文档的明确要求不要加在文件开头或结尾加在中间任意位置即可。保存文件后回到终端执行git status你会看到 Git 报告Contributors.md已被修改——git status用于查看工作区的变更状态是日常开发中最常用的检查命令之一。接下来把改动加入暂存区staging areagit add Contributors.md然后提交到当前分支git commit -m Add ditt-navn to Contributors list把ditt-navn替换成你的名字。-m参数用于直接在命令行指定提交信息避免打开文本编辑器。一次规范的提交应该只包含逻辑相关的改动、附有清晰描述性的提交信息——正如上面的 Add XXX to Contributors list。第五步Push 改动到 GitHub本地提交完成后需要把改动推送到 GitHub 上的你的 Fork 仓库git push origin navn-på-din-branch把navn-på-din-branch替换为你第三步创建的分支名。这里origin是指向你自己 Fork 仓库的远程remote名称。常见报错认证失败Authentication Error如果你是第一次通过 HTTPS 方式 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/ditt-brukernavn/first-contributions.git/原因自 2021 年 8 月 13 日起GitHub 已全面移除密码认证改用**个人访问令牌Personal Access Token**或SSH 密钥完成认证。解决方案是配置 SSH 密钥生成密钥并添加到你的 GitHub 账号后将本地仓库的远程地址从 HTTPS 切换为 SSH 形式。首先检查当前远程地址git remote -v如果输出形如origin https://github.com/ditt-brukernavn/ditt-repo.git (fetch) origin https://github.com/ditt-brukernavn/ditt-repo.git (push)则执行下面的命令把远程地址改为 SSH 形式git remote set-url origin gitgithub.com:ditt-brukernavn/ditt-repo.git否则即使配置了令牌你仍然可能被反复要求输入用户名和密码并最终报认证错误。切换为 SSH 地址后Push 将使用本机 SSH 密钥完成认证不再需要交互式输入账号密码。第六步提交 Pull RequestPR改动已经推到你的 Fork 仓库现在需要请求上游维护者合入这些改动这一步靠Pull Request完成。回到 GitHub 上你的 Fork 仓库页面页面上会出现一个醒目的Compare pull request按钮点击它确认 PR 的比较范围base 是上游仓库的 main 分支compare 是你的新分支提交 Pull Request。提交后维护者会把你的改动合并进项目的主分支合并完成时你会收到一封通知邮件。至此你就完成了人生第一次开源贡献完成之后这套流程的意义与进阶方向恭喜你刚刚完整走通了开源协作中最经典的fork → clone → edit → PR标准流程。这套流程绝不仅限于 first-contributions 这一个仓库——它几乎出现在你今后参与的每一个开源项目中是你必须内化的核心技能。在此基础上可以进一步探索以下方向保持 Fork 与上游同步当上游仓库有了新提交你的 Fork 会落后。此时需要配置upstream远程并执行 fetch、rebase、push 三部曲完整的三角形工作流讲解见 docs/additional-material/git_workflow_scenarios/keeping-your-fork-synced-with-this-repository.md。进阶 Git 技巧合集上游维护者整理了一份进阶资料索引 docs/additional-material/git_workflow_scenarios/additional-material.md涵盖修改最近一次提交git commit --amend修正提交信息或把遗漏的改动并入上一次提交压缩提交squashing commits用交互式 rebase 把多个提交合并为一个这是开源评审中常被要求做的事解决合并冲突resolving merge conflicts当多人修改同一文件时如何手动处理冲突标记并完成合并撤销提交reverting / undoing a commit回滚已推送或本地的提交查看提交日志check commit loggit log的常用变体与参数以及配置 Git、创建 .gitignore、保存凭据、Git Flow 分支模型 等主题。参与真实项目在掌握流程后你完全有能力去其他开源项目贡献代码了。许多项目会为新手标注good first issue类问题适合作为起步练习。其他工具教程不使用终端也能完成贡献如果你对命令行感到吃力仓库同样提供了基于 GUI 工具的完整教学。下表列出了六种主流工具的教学文档入口对应文档位于 docs/gui-tool-tutorials/ 目录许多还有多语言版本工具教学文档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这些 GUI 教程走的是与命令行完全一致的底层流程同样是 Fork、Clone、建分支、修改、提交、Push、提 PR只是把命令操作封装成了可视化界面适合作为终端操作之外的另一条学习路径。小结first-contributions 用一个名字、一个 PR的最小任务把开源协作中最核心的fork → clone → edit → PR流程完整演练了一遍。本文从 Fork 出发逐步完成了仓库克隆、分支创建、文件修改、本地提交、远程推送、认证问题排查与 Pull Request 提交并延伸到了同步上游、压缩提交、解决冲突等进阶 Git 技巧。建议你立刻动手实践一次——第一次提交的成就感正是后续持续参与开源的起点。【免费下载链接】first-contributions✨ Help beginners to contribute to open source projects项目地址: https://gitcode.com/gh_mirrors/fi/first-contributions创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考