first-contributions 仓库实战从 Fork 到 Pull Request 的首次开源贡献完整指南Fork → Clone → Edit → PR 工作流【免费下载链接】first-contributions✨ Help beginners to contribute to open source projects项目地址: https://gitcode.com/gh_mirrors/fi/first-contributions导读本文基于开源仓库 first-contributions 的西班牙语墨西哥官方翻译文档 README.mx.md系统讲解初学者完成第一次开源贡献的标准路径Fork → Clone → 创建分支 → 修改并提交 → Push → 提交 Pull Request。读完本文你将掌握这套在几乎所有开源项目中都会遇到的协作工作流学会用git switch、git add、git commit、git push完成一次真实贡献并了解后续进阶的 Git 技巧与图形化工具路线。一、项目背景为什么需要第一次贡献实战任何事情的第一次都很难尤其是当你开始与他人协作时犯错总让人不愉快。first-contributions 项目的核心目标正如仓库根目录 README.md 所描述的那样simplify and guide the way beginners make their first contribution简化并引导初学者完成第一次贡献。读文章、看教程固然有帮助但有什么比在一个安全的练习环境里真刀真枪做一遍更好呢该项目提供的就是这样一个演练场——你不需要理解复杂的项目业务只需要按照步骤走完一遍完整流程就能在本地把整套协作机制跑通。本项目以 MIT 协议开源见 LICENSE仓库结构非常简单核心资产有两块Contributors.md贡献者名单本文实战中要修改的文件目前已有数千行贡献者记录docs涵盖 Git 工作流进阶文档、CLI 教程 和图形化工具教程 的完整学习体系。而本文依据的 README.mx.md 正是这份入门教程的西班牙语墨西哥版本与仓库根目录 README.md 内容结构一一对应供西语社区的初学者使用。二、准备工作安装 Git 并配置身份在开始之前请确认本地机器已安装 Git。如果还没有安装需要先完成 Git 的安装与环境配置。Git 在设计上要求每次提交都必须关联一个名字和邮箱——在协作场景中只有这样才能明确谁在什么时候改动了项目的哪部分。仓库的进阶文档 configuring-git.md 详细介绍了三种配置身份的方式1. 全局配置Global Config存储在全局配置中的内容对当前系统上所有仓库生效这是最常用、也最推荐的方式git config --global user.email youexample.com git config --global user.name Your Name2. 仓库级配置Repository Config仅对当前仓库生效。例如你在公司项目里需要用公司邮箱提交时可以省略--global标志git config user.email youalternate.com git config user.name Your Name3. 命令行级配置Command-line Config只对当前这一条命令生效。所有 Git 命令都支持用-c参数在动作动词之前注入临时配置git -c user.nameYour Name -c user.emailyouexample.com commit -m Your commit message优先级说明三种方式的优先级为命令行级 仓库级 全局。也就是说如果同一个变量在命令行和全局都配置了命令行里的值会优先生效。除用户信息外Git 配置还支持许多其他选项例如core.editor指定编写提交信息的编辑器、commit.template指定提交信息模板文件、color.ui控制输出是否使用颜色等。三、第一步Fork 仓库Fork分叉是开源协作的起点。在仓库页面右上角点击Fork按钮即可把该仓库复制一份到你自己的 GitHub 账户下。这一步的意义在于普通用户对公共仓库没有写入权限但对自己账户下的副本拥有完全控制权。你后续的所有修改都发生在自己的副本上通过 Pull Request 再把改动提交回原仓库。小提示如果你暂时不想登录 GitHub只想先在本地预览本仓库内容也可以直接克隆本仓库的镜像git clone https://gitcode.com/gh_mirrors/fi/first-contributions。但正式的贡献流程需要从你自己的 Fork 开始。四、第二步Clone 克隆仓库到本地进入你自己的 GitHub 账户打开刚才 Fork 出来的仓库点击Code按钮复制仓库地址可切换 SSH 或 HTTPS 方式然后在终端执行git clone 你复制的仓库地址其中你复制的仓库地址不含双引号就是你 Fork 出来的仓库 URL。例如如果你的 GitHub 用户名是usuarioGitHubgit clone https://github.com/usuarioGitHub/first-contributions.git这条命令会把 GitHub 上 first-contributions 仓库的全部内容复制到你的电脑上。五、第三步创建分支Branch克隆完成后进入仓库目录cd first-contributions接下来用git switch命令创建并切换到一个新分支git switch -c 你的名字例如git switch -c add-juan-perez分支名不一定包含add这个词但加上它是合理的——因为这条分支的目的就是把你的名字加入名单。仓库根目录 README.md 还给出了一个兼容性提示如果遇到git switch不可用的错误提示 switch is not a git command说明本地 Git 版本较旧改用git checkout即可git checkout -b add-juan-perez为什么一定要新建分支因为开源协作要求功能隔离每个分支只承载一个明确的改动主分支main保持稳定便于维护者审查和合并。六、第四步修改文件并提交Commit现在打开仓库根目录下的 Contributors.md 文件用文本编辑器把你的名字加进去。注意不要加在文件开头或结尾加在中间任意位置即可。保存文件。回到终端在项目目录执行git status可以看到改动已被 Git 识别。接着把改动加入暂存区git add Contributors.md然后提交这些改动git commit -m Add 你的名字 to Contributors list把你的名字替换成你的真实名字即可。这一步对应着 Git 工作区的三个状态工作区修改git status可见→ 暂存区git add之后→ 本地仓库git commit之后。git commit会在本地生成一条带唯一哈希值、作者信息和时间的提交记录正如 check-commit-log.md 展示的提交日志那样$ git log commit e3fabb30ab536bd5876461d8a749301a321e714f (HEAD - main, upstream/main, origin/main) Author: Dan Yunheum Seol yunheum.seolmail.mcgill.ca Date: Tue Jun 4 01:07:25 2024 -0400 Add dan-seol to Contributors list (#84962)七、第五步Push 推送改动到 GitHubgit commit只把改动保存在本地仓库要让 GitHub 上的 Fork 副本同步这些改动需要执行git push origin 分支名把分支名替换为你之前创建的分支名称例如add-juan-perez。根目录 README.md 还建议在首次推送时加上-u参数建立本地分支与远程分支的跟踪关系git push -u origin your-branch-name这样后续推送可以省略分支参数。推送报错怎么办仓库文档记录了两种常见问题认证错误Authentication Error如果提示 Support for password authentication was removed说明你的远程地址仍是 HTTPS 形式可通过git remote -v查看此时需要改用 SSH 地址git remote set-url origin gitgithub.com:你的用户名/你的仓库.gitgit switch不可用见上文改用git checkout -b 分支名。八、第六步提交 Pull RequestPR回到你的 GitHub 仓库页面此时会看到一个绿色的Compare pull request按钮点击它。GitHub 会展示你的分支与原仓库 main 分支的差异对比确认无误后填写标题与描述点击提交即完成了一次 Pull Request。提交之后仓库维护者会审查你的改动并执行合并merge。合并完成后你会收到一封邮件通知。此时再回头看你推送过的分支可以用 removing-branch-from-your-repository.md 中介绍的方法在 PR 合并后清理本地与远程分支。九、完整的协作全景理解三角工作流完成一次 PR 只是开始。在真实开源项目中你会长期面临一个场景上游公共仓库不断有新提交你的 Fork 会落后。仓库文档 keeping-your-fork-synced-with-this-repository.md 将这种协作模式称为Triangle Workflows三角工作流涉及三个仓库仓库角色上游公共仓库upstream项目权威版本维护者在此合并 PR你的 GitHub Forkorigin你账户下的副本PR 只能从这里发起本地仓库你实际编写代码的地方同步流程分三步# 1. 回到 main 分支用 git status 第一行确认当前分支 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 到你的 Fork git push origin main如果你希望拉取并合并一步完成可以直接执行git pull upstream main养成习惯每当 GitHub 提示你的 Fork 落后几个提交a few commits behind时就执行一次上述同步。十、后续进阶从第一次贡献到熟练贡献者恭喜你刚刚走完了贡献者最常遇到的fork → clone → edit → pull request标准工作流。之后你可以庆祝并分享这次贡献社交分享入口位于项目的 Web 应用页面继续练习在 Web 应用中浏览由项目维护者整理的、带有简单 issue 的开源项目列表开始向其他项目贡献深入学习 Git 进阶技巧——仓库的 additional-material.md 是整套进阶文档的索引覆盖了贡献者后续几乎必然遇到的场景进阶主题文档适用场景修改最近一次提交amending-a-commit.md提交信息有笔误、漏改了内容撤销已推送的提交reverting-a-commit.md需要回滚已经推到远程的提交撤销本地提交undoing-a-commit.md本地仓库改乱了想重置压缩多个提交squashing-commits.md评审者要求把多个提交合并为一个解决合并冲突resolving-merge-conflicts.md合并时出现冲突移动提交到其他分支moving-a-commit-to-a-different-branch.md提交放错了分支删除文件removing-a-file.md提交前需要移除文件同步 Forkkeeping-your-fork-synced-with-this-repository.md本地仓库落后于上游查看提交历史check-commit-log.md排查谁改了什么配置 Gitconfiguring-git.md配置身份、编辑器等创建 .gitignorecreating-a-gitignore-file.md只提交必要文件存储凭据storing-credentials.md免密推送注意安全策略以修改最近一次提交为例仓库文档 amending-a-commit.md 给出了两种典型场景只改提交信息不打开编辑器git commit --amend -m 新的提交信息 git push origin 分支名补充遗漏的改动并合并进上一次提交先修改文件再git add 文件名然后执行git commit --amend会打开编辑器让你确认信息最后推送。警告如果该提交已经推送到远程amend 会导致本地历史与远程分叉需要强制推送覆盖远程git push --force。但强制推送会覆盖远程上其他人期间的改动更安全的做法是用git push --force-with-lease它会在覆盖前检查远程分支是否有他人新提交避免误伤。十一、不习惯命令行图形化工具路线README.mx.md 开头特别说明如果你不习惯使用命令行可以直接走图形化工具路线。仓库在 docs/gui-tool-tutorials 下为每种主流 GUI 工具提供了完整教程覆盖与本文完全相同的 Fork→Clone→Edit→PR 流程GitHub Desktop 教程Visual Studio 2017 教程GitKraken 教程Visual Studio Code 教程Atlassian Sourcetree 教程IntelliJ IDEA 教程此外docs/cli-tool-tutorials/github-cli-tutorial.md 还提供了基于 GitHub CLIgh命令的完整流程教程适合偏好终端但想少记命令的开发者。十二、多语言学习资源first-contributions 是一个高度国际化的项目根目录 README.md 顶部通过国旗图标链接到几十种语言的翻译版本完整的语言索引见 docs/translations/Translations.md。本文所依据的 README.mx.md 正是其中Español de México墨西哥西班牙语版本与 README.es.md西班牙语、README.zh-cn.md简体中文等其他翻译同属一个体系方便不同语言背景的学习者对照阅读。小结从 Fork 到 Pull Request本文完整还原了首次开源贡献的六个核心步骤并结合仓库的 进阶文档 补充了身份配置、分支管理、提交修正、Fork 同步、冲突解决等真实协作中高频使用的技巧。把这套流程亲手走一遍你就迈出了成为开源贡献者的第一步。【免费下载链接】first-contributions✨ Help beginners to contribute to open source projects项目地址: https://gitcode.com/gh_mirrors/fi/first-contributions创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
first-contributions 仓库实战：从 Fork 到 Pull Request 的首次开源贡献完整指南（Fork → Clone → Edit → PR 工作流）
first-contributions 仓库实战从 Fork 到 Pull Request 的首次开源贡献完整指南Fork → Clone → Edit → PR 工作流【免费下载链接】first-contributions✨ Help beginners to contribute to open source projects项目地址: https://gitcode.com/gh_mirrors/fi/first-contributions导读本文基于开源仓库 first-contributions 的西班牙语墨西哥官方翻译文档 README.mx.md系统讲解初学者完成第一次开源贡献的标准路径Fork → Clone → 创建分支 → 修改并提交 → Push → 提交 Pull Request。读完本文你将掌握这套在几乎所有开源项目中都会遇到的协作工作流学会用git switch、git add、git commit、git push完成一次真实贡献并了解后续进阶的 Git 技巧与图形化工具路线。一、项目背景为什么需要第一次贡献实战任何事情的第一次都很难尤其是当你开始与他人协作时犯错总让人不愉快。first-contributions 项目的核心目标正如仓库根目录 README.md 所描述的那样simplify and guide the way beginners make their first contribution简化并引导初学者完成第一次贡献。读文章、看教程固然有帮助但有什么比在一个安全的练习环境里真刀真枪做一遍更好呢该项目提供的就是这样一个演练场——你不需要理解复杂的项目业务只需要按照步骤走完一遍完整流程就能在本地把整套协作机制跑通。本项目以 MIT 协议开源见 LICENSE仓库结构非常简单核心资产有两块Contributors.md贡献者名单本文实战中要修改的文件目前已有数千行贡献者记录docs涵盖 Git 工作流进阶文档、CLI 教程 和图形化工具教程 的完整学习体系。而本文依据的 README.mx.md 正是这份入门教程的西班牙语墨西哥版本与仓库根目录 README.md 内容结构一一对应供西语社区的初学者使用。二、准备工作安装 Git 并配置身份在开始之前请确认本地机器已安装 Git。如果还没有安装需要先完成 Git 的安装与环境配置。Git 在设计上要求每次提交都必须关联一个名字和邮箱——在协作场景中只有这样才能明确谁在什么时候改动了项目的哪部分。仓库的进阶文档 configuring-git.md 详细介绍了三种配置身份的方式1. 全局配置Global Config存储在全局配置中的内容对当前系统上所有仓库生效这是最常用、也最推荐的方式git config --global user.email youexample.com git config --global user.name Your Name2. 仓库级配置Repository Config仅对当前仓库生效。例如你在公司项目里需要用公司邮箱提交时可以省略--global标志git config user.email youalternate.com git config user.name Your Name3. 命令行级配置Command-line Config只对当前这一条命令生效。所有 Git 命令都支持用-c参数在动作动词之前注入临时配置git -c user.nameYour Name -c user.emailyouexample.com commit -m Your commit message优先级说明三种方式的优先级为命令行级 仓库级 全局。也就是说如果同一个变量在命令行和全局都配置了命令行里的值会优先生效。除用户信息外Git 配置还支持许多其他选项例如core.editor指定编写提交信息的编辑器、commit.template指定提交信息模板文件、color.ui控制输出是否使用颜色等。三、第一步Fork 仓库Fork分叉是开源协作的起点。在仓库页面右上角点击Fork按钮即可把该仓库复制一份到你自己的 GitHub 账户下。这一步的意义在于普通用户对公共仓库没有写入权限但对自己账户下的副本拥有完全控制权。你后续的所有修改都发生在自己的副本上通过 Pull Request 再把改动提交回原仓库。小提示如果你暂时不想登录 GitHub只想先在本地预览本仓库内容也可以直接克隆本仓库的镜像git clone https://gitcode.com/gh_mirrors/fi/first-contributions。但正式的贡献流程需要从你自己的 Fork 开始。四、第二步Clone 克隆仓库到本地进入你自己的 GitHub 账户打开刚才 Fork 出来的仓库点击Code按钮复制仓库地址可切换 SSH 或 HTTPS 方式然后在终端执行git clone 你复制的仓库地址其中你复制的仓库地址不含双引号就是你 Fork 出来的仓库 URL。例如如果你的 GitHub 用户名是usuarioGitHubgit clone https://github.com/usuarioGitHub/first-contributions.git这条命令会把 GitHub 上 first-contributions 仓库的全部内容复制到你的电脑上。五、第三步创建分支Branch克隆完成后进入仓库目录cd first-contributions接下来用git switch命令创建并切换到一个新分支git switch -c 你的名字例如git switch -c add-juan-perez分支名不一定包含add这个词但加上它是合理的——因为这条分支的目的就是把你的名字加入名单。仓库根目录 README.md 还给出了一个兼容性提示如果遇到git switch不可用的错误提示 switch is not a git command说明本地 Git 版本较旧改用git checkout即可git checkout -b add-juan-perez为什么一定要新建分支因为开源协作要求功能隔离每个分支只承载一个明确的改动主分支main保持稳定便于维护者审查和合并。六、第四步修改文件并提交Commit现在打开仓库根目录下的 Contributors.md 文件用文本编辑器把你的名字加进去。注意不要加在文件开头或结尾加在中间任意位置即可。保存文件。回到终端在项目目录执行git status可以看到改动已被 Git 识别。接着把改动加入暂存区git add Contributors.md然后提交这些改动git commit -m Add 你的名字 to Contributors list把你的名字替换成你的真实名字即可。这一步对应着 Git 工作区的三个状态工作区修改git status可见→ 暂存区git add之后→ 本地仓库git commit之后。git commit会在本地生成一条带唯一哈希值、作者信息和时间的提交记录正如 check-commit-log.md 展示的提交日志那样$ git log commit e3fabb30ab536bd5876461d8a749301a321e714f (HEAD - main, upstream/main, origin/main) Author: Dan Yunheum Seol yunheum.seolmail.mcgill.ca Date: Tue Jun 4 01:07:25 2024 -0400 Add dan-seol to Contributors list (#84962)七、第五步Push 推送改动到 GitHubgit commit只把改动保存在本地仓库要让 GitHub 上的 Fork 副本同步这些改动需要执行git push origin 分支名把分支名替换为你之前创建的分支名称例如add-juan-perez。根目录 README.md 还建议在首次推送时加上-u参数建立本地分支与远程分支的跟踪关系git push -u origin your-branch-name这样后续推送可以省略分支参数。推送报错怎么办仓库文档记录了两种常见问题认证错误Authentication Error如果提示 Support for password authentication was removed说明你的远程地址仍是 HTTPS 形式可通过git remote -v查看此时需要改用 SSH 地址git remote set-url origin gitgithub.com:你的用户名/你的仓库.gitgit switch不可用见上文改用git checkout -b 分支名。八、第六步提交 Pull RequestPR回到你的 GitHub 仓库页面此时会看到一个绿色的Compare pull request按钮点击它。GitHub 会展示你的分支与原仓库 main 分支的差异对比确认无误后填写标题与描述点击提交即完成了一次 Pull Request。提交之后仓库维护者会审查你的改动并执行合并merge。合并完成后你会收到一封邮件通知。此时再回头看你推送过的分支可以用 removing-branch-from-your-repository.md 中介绍的方法在 PR 合并后清理本地与远程分支。九、完整的协作全景理解三角工作流完成一次 PR 只是开始。在真实开源项目中你会长期面临一个场景上游公共仓库不断有新提交你的 Fork 会落后。仓库文档 keeping-your-fork-synced-with-this-repository.md 将这种协作模式称为Triangle Workflows三角工作流涉及三个仓库仓库角色上游公共仓库upstream项目权威版本维护者在此合并 PR你的 GitHub Forkorigin你账户下的副本PR 只能从这里发起本地仓库你实际编写代码的地方同步流程分三步# 1. 回到 main 分支用 git status 第一行确认当前分支 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 到你的 Fork git push origin main如果你希望拉取并合并一步完成可以直接执行git pull upstream main养成习惯每当 GitHub 提示你的 Fork 落后几个提交a few commits behind时就执行一次上述同步。十、后续进阶从第一次贡献到熟练贡献者恭喜你刚刚走完了贡献者最常遇到的fork → clone → edit → pull request标准工作流。之后你可以庆祝并分享这次贡献社交分享入口位于项目的 Web 应用页面继续练习在 Web 应用中浏览由项目维护者整理的、带有简单 issue 的开源项目列表开始向其他项目贡献深入学习 Git 进阶技巧——仓库的 additional-material.md 是整套进阶文档的索引覆盖了贡献者后续几乎必然遇到的场景进阶主题文档适用场景修改最近一次提交amending-a-commit.md提交信息有笔误、漏改了内容撤销已推送的提交reverting-a-commit.md需要回滚已经推到远程的提交撤销本地提交undoing-a-commit.md本地仓库改乱了想重置压缩多个提交squashing-commits.md评审者要求把多个提交合并为一个解决合并冲突resolving-merge-conflicts.md合并时出现冲突移动提交到其他分支moving-a-commit-to-a-different-branch.md提交放错了分支删除文件removing-a-file.md提交前需要移除文件同步 Forkkeeping-your-fork-synced-with-this-repository.md本地仓库落后于上游查看提交历史check-commit-log.md排查谁改了什么配置 Gitconfiguring-git.md配置身份、编辑器等创建 .gitignorecreating-a-gitignore-file.md只提交必要文件存储凭据storing-credentials.md免密推送注意安全策略以修改最近一次提交为例仓库文档 amending-a-commit.md 给出了两种典型场景只改提交信息不打开编辑器git commit --amend -m 新的提交信息 git push origin 分支名补充遗漏的改动并合并进上一次提交先修改文件再git add 文件名然后执行git commit --amend会打开编辑器让你确认信息最后推送。警告如果该提交已经推送到远程amend 会导致本地历史与远程分叉需要强制推送覆盖远程git push --force。但强制推送会覆盖远程上其他人期间的改动更安全的做法是用git push --force-with-lease它会在覆盖前检查远程分支是否有他人新提交避免误伤。十一、不习惯命令行图形化工具路线README.mx.md 开头特别说明如果你不习惯使用命令行可以直接走图形化工具路线。仓库在 docs/gui-tool-tutorials 下为每种主流 GUI 工具提供了完整教程覆盖与本文完全相同的 Fork→Clone→Edit→PR 流程GitHub Desktop 教程Visual Studio 2017 教程GitKraken 教程Visual Studio Code 教程Atlassian Sourcetree 教程IntelliJ IDEA 教程此外docs/cli-tool-tutorials/github-cli-tutorial.md 还提供了基于 GitHub CLIgh命令的完整流程教程适合偏好终端但想少记命令的开发者。十二、多语言学习资源first-contributions 是一个高度国际化的项目根目录 README.md 顶部通过国旗图标链接到几十种语言的翻译版本完整的语言索引见 docs/translations/Translations.md。本文所依据的 README.mx.md 正是其中Español de México墨西哥西班牙语版本与 README.es.md西班牙语、README.zh-cn.md简体中文等其他翻译同属一个体系方便不同语言背景的学习者对照阅读。小结从 Fork 到 Pull Request本文完整还原了首次开源贡献的六个核心步骤并结合仓库的 进阶文档 补充了身份配置、分支管理、提交修正、Fork 同步、冲突解决等真实协作中高频使用的技巧。把这套流程亲手走一遍你就迈出了成为开源贡献者的第一步。【免费下载链接】first-contributions✨ Help beginners to contribute to open source projects项目地址: https://gitcode.com/gh_mirrors/fi/first-contributions创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考