文档教程开源治理【免费下载链接】first-contributions✨ Help beginners to contribute to open source projects项目地址https://gitcode.com/gh_mirrors/fi/first-contributions点击查看免费下载导读本指南以 first-contributions 项目官方白俄罗斯语版入门文档docs/translations/README.be.md为核心骨架完整讲解新手开发者完成人生第一次开源贡献所需的全部步骤Fork 仓库、Clone 到本地、创建分支、修改Contributors.md、提交 Commit、Push 到远程、发起 Pull Request以及贡献合并后如何同步 Fork 与清理分支。读完本文你将掌握开源协作中最高频的fork → clone → edit → pull request标准工作流并能利用仓库中配套的进阶 Git 材料解决提交信息修改、合并冲突、提交回退等实战问题。说明本文面向中文读者完整还原原文档的技术步骤并结合仓库内 README.md、Contributors.md 及 docs/additional-material 等真实文件做源码级补充所有路径均以仓库根目录为起点。一、项目背景与文档定位first-contributions 是一个帮助初学者完成首次开源贡献的教学项目。它的核心理念是阅读文章和教程可以带来帮助但没有什么比一次真实、无风险破坏的动手实践更有价值。项目的目的正是引导新人以正确的方式完成第一次贡献并且刻意把流程设计得轻松、低压——越放松学得越好。仓库根目录的 README.md 是该项目的英文主文档而 docs/translations/README.be.md 是其白俄罗斯语Беларуская мова翻译版。两者技术骨架完全一致均由一系列循序渐进的 H2 小节构成本文严格沿用该骨架并逐节展开、扩充。整个仓库结构docs 目录围绕这份指南配套了三种维度的支撑材料命令行教程docs/cli-tool-tutorials 下的 GitHub CLIgh教程、Git Bash Windows 教程等GUI 工具教程docs/gui-tool-tutorials 下的 GitHub Desktop、VS Code、GitKraken、IntelliJ IDEA 等图形化工具教程进阶 Git 场景材料docs/additional-material/git_workflow_scenarios 下的合并冲突解决、提交修改、Fork 同步等专题文档。二、准备环境安装 Git原文档开篇强调如果机器上尚未安装 Git请先完成安装再继续。对于 Debian/Ubuntu 系 Linux 发行版仓库提供了针对性的安装指南 installing-git-ubuntu.mdArch Linux 用户则可参考 installing-git-arch.md。安装完成后可通过git --version验证命令是否可用。同时需要准备一个 GitHub 账号并确认终端环境已就绪。三、Fork 这个仓库创建独立副本在仓库页面顶部点击Fork按钮。这一步会在你自己的 GitHub 账号下创建当前仓库的一份独立副本——也就是说之后你在副本上的任何操作都不会影响原仓库这正是无风险实践的关键设计。Fork 的产物位于你自己的账号命名空间下后续所有提交、推送都发生在这份副本上直到最终通过 Pull Request 把改动合并回原仓库。四、Clone 仓库到本地复制到个人电脑4.1 获取复制链接Fork 完成后进入你账号下的这份副本仓库点击Code / Clone按钮再点击copy to clipboard复制到剪贴板图标复制仓库地址。原文档提示这个地址就是你 fork 出来的那份仓库的地址而非原仓库地址。4.2 执行 Clone 命令打开终端运行以下 git 命令git clone url you just copied其中url you just copied去掉引号就是你刚复制的仓库地址。例如git clone https://github.com/this-is-you/first-contributions.git这里this-is-you是你的 GitHub 用户名。执行成功后first-contributions仓库的全部内容就被复制到了你的电脑上。细节提示英文主文档 README.md 推荐使用 SSH 形式gitgithub.com:this-is-you/first-contributions.git若使用 HTTPS 地址在 push 时遇到密码认证被拒绝的错误可参考 docs/cli-tool-tutorials/github-cli-tutorial.md 中给出的处理办法用git remote set-url origin gitgithub.com:your-username/your_repo.git将远程地址切换为 SSH 形式。五、创建分支Branch5.1 进入项目目录cd first-contributions5.2 用 checkout 创建分支原文档使用经典的git checkout命令创建分支git checkout -b add-your-name例如git checkout -b add-alonzo-church命名约定说明语法上并不强制分支名包含add字样但加上它是有意义的——它直白地表达了这个分支的用途把名字加入贡献者列表。版本兼容提示较新版本的 Git 推荐使用语义更清晰的git switch命令即git switch -c your-new-branch-name见 README.md 与 github-cli-tutorial.md。如果执行git switch时报错 Git:switchis not a git command说明本地 Git 版本较旧此时回退使用git checkout -b即可。六、修改文件并提交 Commit6.1 编辑 Contributors.md用文本编辑器打开仓库根目录的 Contributors.md 文件把你的名字写入其中并保存。该文件当前已有数千条贡献者记录每行格式为- 名字或带个人备注按原文档建议把你的名字加在文件中间任意位置而不是开头或结尾以避免与现有贡献者条目产生冲突这也为后面练习合并冲突解决埋下伏笔。6.2 查看变更状态回到项目目录执行git status你会看到Contributors.md被标记为已修改modified。6.3 暂存变更用git add把改动加入暂存区git add Contributors.md6.4 提交 Commit用git commit创建一次提交git commit -m Add your-name to Contributors list把your-name替换成你的名字。这一提交被记录在你本地的新分支上尚未进入远程。补充如果你在首次 commit 时收到 *** Please tell me who you are 提示说明 Git 尚未配置用户身份需先执行git config --global user.email youexample.com与git config --global user.name Your Name。更完整的配置层次说明全局配置、仓库配置、命令行临时配置及其优先级参见 configuring-git.md。七、把变更 Push 到 GitHub提交完成后用git push把本地分支推送到远程你 fork 的仓库git push origin add-your-name将add-your-name替换为你之前创建的分支名。推送后改动就到了你 GitHub 账号下的 fork 副本中。提示Git 较新版本推荐首次推送时加上-u参数建立本地分支与远程分支的追踪关系git push -u origin your-branch-name见 github-cli-tutorial.md此后该分支可直接使用git push推送。八、提交 Pull Request 等待审查回到你 GitHub 账号下的 fork 仓库页面会看到一个Compare pull request按钮点击它。随后进入 Pull Request 创建页面确认改动内容无误后点击提交按钮正式发起 Pull Request。项目维护者会审查并尽快将你的改动合并进主分支main branch。一旦合并你会收到一封通知邮件。这一小节是整个工作流的验收环节前面的所有操作——fork、clone、branch、commit、push——最终都汇聚到这一份 PR 上由维护者审阅后合入项目主线。九、同步你的 Fork保持与原仓库一致原文档强调你的 PR 被合并后你 fork 仓库的主分支并不会自动更新。此时需要按以下步骤把上游仓库原仓库的新内容同步下来。仓库配套专题文档 keeping-your-fork-synced-with-this-repository.md 对这一三角工作流上游公共仓库 → 你的本地仓库 → 你的 fork有更详尽的图解说明。9.1 切回主分支git checkout master9.2 添加上游远程地址git remote add upstream https://github.com/Roshanjossey/first-contributions这一步告诉 Git在指定地址存在该项目的另一个版本我们称之为upstream上游并把它视为主版本来源。9.3 拉取上游最新内容git fetch upstreamgit fetch会把上游仓库的所有新提交拉到本地但不会自动合并到当前分支。9.4 变基合并到本地主分支git rebase upstream/mastergit rebase将你本地 master 分支的提交重放到上游最新提交之上使本地主分支与上游完全同步。9.5 推送本地主分支到你的 Forkgit push origin master注意这里 push 的是名为origin的远程你自己的 fork。推送完成后你 GitHub 上的 fork 主分支也同步到了最新状态。快捷方式如需一次性完成拉取并合并可直接执行git pull upstream main上游主分支名为main时。判断同步时机也很简单每当你的 fork 页面提示当前分支落后于上游若干提交a few commits behind时就应执行上述同步流程。9.6 删除已合并的功能分支同步完成后你的add-your-name分支使命已经完成可以清理掉。本地删除git branch -d add-your-name远程fork 上删除git push origin --delete add-your-name原文档特别说明删除分支并非强制但该分支的名称体现了它非常特定的用途生命周期本就应该短暂。十、使用其他工具完成相同流程如果你不习惯命令行原文档提供了完整的图形化工具教程矩阵覆盖同样完整的fork → clone → edit → pull request流程均可从仓库根目录路径访问工具教程路径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此外偏爱纯终端的开发者可以学习 github-cli-tutorial.md安装 GitHub CLI 后执行gh auth login登录用gh repo fork firstcontributions/first-contributions一键完成 fork 并选择同时 clone最后用gh pr create --repo firstcontributions/first-contributions直接从命令行发起 Pull Request全程无需打开浏览器。十一、进阶合并冲突与提交修订实战补充贡献者多了之后第 6.1 节提到的在文件中间插入名字恰恰是最容易引发合并冲突的场景。仓库为此准备了专门的进阶材料索引见 additional-material.md这里提炼与首次贡献最相关的两个主题11.1 解决合并冲突当两个分支改动了同一文件的同一行、或一方删除的文件另一方仍在修改时Git 无法自动合并会暂停并标记冲突文件。解决流程详见 resolving-merge-conflicts.mdgit status找出 Unmerged paths 下的冲突文件打开冲突文件定位 HEAD当前分支的改动、分隔线与 branch-name对方分支的改动三组标记手工决定保留哪边或合并两边内容并删除所有冲突标记对每个已解决的文件执行git add filename最后git commit -m Resolved merge conflicts完成合并。辅助命令git mergetool可启动图形化合并工具需预装 Meld、KDiff3 等git merge --abort可放弃本次合并养成git pull origin main及时同步、每个功能用独立分支的习惯可显著减少冲突。11.2 修改最近一次提交若 commit 信息写错或漏改了一行可执行git commit --amend -m 新的提交信息直接改写最近一次提交不加-m则会打开文本编辑器修改信息。若该提交已 push 到远程改写会导致本地与远程历史分叉此时需用git push --force覆盖远程历史——但这是危险操作会丢弃他人同时期的改动更安全的替代是git push --force-with-lease详见 amending-a-commit.md。11.3 撤销本地提交git reset可将暂存区重置到最近一次提交工作区改动保留可重新提交git reset file只把指定文件移出暂存区git reset --hard HEAD~2则会连同工作区改动一起回退两个提交、并从历史中移除这两次快照。切记git reset --hard只适用于尚未推送到共享仓库的本地提交详见 undoing-a-commit.md。十二、接下来做什么完成上述全部流程你就已经走完了一次标准的fork → clone → edit → pull request开源贡献闭环。如果想继续练习或寻找更多新手友好的开源任务可以阅读 how-to-contribute-to-open-source-projects.md 与 Useful-links-for-further-learning.md系统了解参与开源的通用方法论与学习资源对照 Translations.md 了解该项目覆盖的全部语言版本感受开源社区全球协作的氛围回到仓库根目录的 Contributors.md看看自己的名字是否已与其他数千名贡献者一起出现在列表中。结语本指南完整继承了 docs/translations/README.be.md 的全部技术步骤并以仓库内真实文件Contributors.md、README.md、进阶材料目录为佐证进行了逐层扩充。从 Fork 到 Pull Request再到合并后的 Fork 同步与分支清理这套工作流是参与任何开源项目都会反复使用的基本功。现在打开终端开始你的第一次贡献吧。赞分享文档教程开源治理【免费下载链接】first-contributions✨ Help beginners to contribute to open source projects项目地址https://gitcode.com/gh_mirrors/fi/first-contributions点击查看免费下载相关推荐first-contributions 实战指南从 fork 到 pull request 的首次开源贡献完整工作流first contributions 实战指南从 fork 到 pull request 的首次开源贡献完整工作流 本篇技术指南以开源教学仓库 first文档教程开源治理first-contributions 首次开源贡献实战指南从 Fork 到 Pull Request 的完整工作流first contributions 首次开源贡献实战指南从 Fork 到 Pull Request 的完整工作流 本文基于 first contribut文档教程开源治理first-contributions 首次开源贡献实战指南从 Fork 到 Pull Request 的完整 Git 工作流first contributions 首次开源贡献实战指南从 Fork 到 Pull Request 的完整 Git 工作流 导读 first contri文档教程开源治理创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考