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 的祖鲁语isiZulu翻译版教程 README.zul.md 为骨架系统讲解初学者如何通过fork → clone → edit → pull request四步标准流程完成第一次开源贡献。本指南覆盖 Git 环境准备、分支管理、提交与推送、Pull Request 提交以及合并冲突、提交修正、fork 同步等进阶 Git 操作阅读后你将具备独立向任意开源项目提交代码贡献的完整实战能力。项目背景与本教程的定位first-contributions 项目的定位非常明确帮助开源新手迈出贡献的第一步。项目根目录的 README.md 用一句话点明了核心目标This project aims to simplify and guide the way beginners make their first contribution简化并引导初学者完成第一次贡献。为了让不同语言背景的开发者都能无障碍学习项目在 docs/translations 目录下维护了上百种语言的翻译版本README.zul.md 就是面向祖鲁语使用者的完整教程。与其他翻译版一样它完整保留了英文原版的全部操作步骤与命令示例——这意味着这套工作流是经过项目长期验证、可以直接照做的标准流程。本教程的实操产物是向仓库根目录的 Contributors.md 贡献者名单文件追加自己的名字。该文件目前已有数千行条目累计超过 5900 行正是由一代代新手通过本文描述的流程累积而成的是这套流程真实可用的直接证据。环境准备确保本机已安装 Git动手之前先确认你的电脑上是否安装了 Git。在终端执行git --version如果系统提示找不到该命令说明尚未安装。不同操作系统有对应的安装方式可参考仓库中整理的安装指南Ubuntu 系installing-git-ubuntu.mdArch 系installing-git-arch.md如果你对命令行完全不熟悉也可以跳过本节直接使用文末列出的 GUI 工具教程如 GitHub Desktop效果相同。第一步Fork 本仓库Fork复刻是 GitHub 提供的一种仓库复制机制。点击仓库页面右上角的 Fork 按钮GitHub 就会在你自己的账户下生成一份该仓库的完整副本。这一操作的关键意义在于Fork 出来的副本归你所有你可以在上面任意修改、创建分支、推送代码而不会影响原始仓库上游仓库的任何内容。后续所有操作都基于你的这份 Fork而不是原始仓库——请务必记住这一点因为它决定了整套工作流的合法性你只能从自己的 Fork 发起 Pull Request。第二步Clone 克隆仓库到本地Fork 完成后进入你自己账户下的 first-contributions 仓库页面点击页面上的 Code 按钮复制仓库 URL 到剪贴板打开终端执行 clone 命令git clone url you just copied其中url you just copied替换为你刚才复制的地址去掉引号。例如假设你的 GitHub 用户名为this-is-yougit clone https://github.com/this-is-you/first-contributions.git这条命令会把 GitHub 上的仓库内容完整下载到本地电脑形成一份与远程仓库完全一致的工作副本。从此你就有了一套远程 Fork 本地仓库的双重操作空间。第三步创建专属分支Clone 完成后先进入仓库目录cd first-contributions然后创建一个属于本次贡献的分支。教程中推荐使用git checkout命令git checkout -b add-你的名字例如贡献者名为 Adam Kowalski可以创建git checkout -b add-adam-kowalski关于分支命名教程特别给出了两条实用建议分支名不强制包含add前缀但加上add是合理的习惯因为该分支的使命就是把你的名字添加到贡献者列表见名知意。需要说明的是较新版本的 Git2.23提供了语义更清晰的新命令git switch根目录 README.md 的英文原版教程即采用git switch -c 新分支名的写法。两条命令等价若你的 Git 版本较旧、执行git switch报错就退回使用git checkout -b。第四步修改文件并提交用任意文本编辑器打开仓库根目录的 Contributors.md把你的名字添加进去。教程给出了三条纪律不要把名字加在文件开头或结尾放在文件中间任意位置即可添加后保存文件。建议照抄仓库中已有的条目格式- 名字例如- [Antonio Campello](https://github.com/antoniocampello)便于维护者审阅。保存后在仓库目录下执行git status检查工作区状态你会看到Contributors.md显示为已修改modified状态。接下来把改动加入暂存区git add Contributors.md然后提交提交信息中把你的名字替换为真实姓名git commit -m Add your-name to Contributors list例如git commit -m Add Adam Kowalski to Contributors list至此你的改动已作为一条本地提交记录挂在刚才创建的add-adam-kowalski分支上。第五步推送改动到 GitHub将本地分支推送到你自己的远程 Forkgit push origin add-your-branch-name把add-your-branch-name替换为之前创建的分支名例如git push origin add-adam-kowalski推送失败认证错误的排查与修复新手推送时最常见的错误是认证失败。如果你看到类似下面的报错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/your-username/first-contributions.git/说明你在使用已被 GitHub 停用的密码认证方式GitHub 已全面转向 token / SSH 密钥认证。此时应改用 SSH 方式连接。先检查当前远程地址配置git remote -v如果输出显示远程地址是 HTTPS 形式origin https://github.com/your-username/your_repo.git (fetch) origin https://github.com/your-username/your_repo.git (push)需要将远程地址切换为 SSH 形式git remote set-url origin gitgithub.com:your-username/your_repo.git同时为本机配置好 SSH 公钥并添加到 GitHub 账户生成与配置步骤参见仓库内的 storing-credentials.md 及英文 README 中引用的 GitHub 官方文档。否则推送时仍会被要求输入用户名和密码导致同样的认证错误。第六步提交 Pull Request推送成功后回到 GitHub 上你自己的 Fork 页面页面顶部会出现一个醒目的Compare pull request按钮点击它确认对比范围base 仓库为原始仓库的 main 分支compare 分支为你刚推送的分支点击Create pull request填写标题与描述后正式提交。提交后仓库维护者会收到通知并将你的改动合并进 main 分支。合并成功后你会收到一封邮件通知。至此一次完整的开源贡献闭环完成。第七步后续进阶——让 Fork 与上游保持同步完成第一次贡献后你必然会遇到一个问题上游仓库持续有新的提交你的 Fork 和本地仓库会逐渐落后。仓库在 keeping-your-fork-synced-with-this-repository.md 中详细讲解了这一场景。开源协作中典型的三角工作流Triangle Workflows涉及三个仓库上游公共仓库本项目的原始仓库你在 GitHub 上的 Fork你本地的仓库。同步的核心思路是先让本地仓库与上游对齐再把本地仓库推送到你的 Fork。首先确保本地处于 main 分支git status # 查看当前所在分支第一行输出 git checkout main # 若不在 main 分支则切换然后把上游仓库添加为名为upstream的远程git remote add upstream https://github.com/firstcontributions/first-contributions.git拉取上游最新内容git fetch upstream将上游 main 分支的更新合并到本地 main教程采用 rebase 方式git rebase upstream/main最后把同步后的本地 main 推送到你的 Fork远程名为origingit push origin main如果想一步完成拉取并合并两个动作可以直接使用git pull upstream main建议在 GitHub 提示你的 Fork 落后于上游若干提交时就执行一次上述同步流程。更多进阶 Git 场景围绕首次贡献可能遇到的各种 Git 操作仓库在 docs/additional-material/git_workflow_scenarios 目录下提供了系统化的专题文档入口为 additional-material.md。几个与贡献者高度相关的场景修正最近一次提交amending-a-commit.md如果提交信息有拼写错误或忘了把某个改动包含进最近一次提交可以执行git commit --amend -m 新的提交信息若该提交已推送远程则需在 amend 后用git push --force覆盖远程历史。文档特别警告force push 会覆盖远程上他人的改动若仅想安全更新自己分支优先使用--force-with-lease。解决合并冲突resolving-merge-conflicts.md当多个贡献者修改同一文件的同一行、或一人删除文件另一人继续修改时Git 无法自动合并会在文件中插入 HEAD、、 branch-name三类冲突标记。处理流程为用git status找出处于 Unmerged paths 下的文件 → 手动编辑取舍 → 删除冲突标记 →git add 文件名标记已解决 →git commit完成合并。压缩提交squashing-commits.md当维护者在 PR 评审中要求把多个提交合并为一个信息完整的提交时可使用交互式 rebase 完成。撤销提交undoing-a-commit.md、reverting-a-commit.md分别面向本地未推送提交的撤销与已推送提交的回滚场景。删除文件与分支removing-a-file.md、removing-branch-from-your-repository.md覆盖提交前删除文件、PR 合并后清理分支的常规操作。.gitignore 与凭证管理creating-a-gitignore-file.md、storing-credentials.md前者保证只提交必要文件后者讲解凭据安全存储需遵循所在机构的安防策略。不习惯命令行试试 GUI 工具教程README.zul.md 明确提示如果不习惯命令行可以使用 GUI 工具完成同样流程。仓库在 docs/gui-tool-tutorials 目录下为六大主流工具提供了图文教程操作路径与命令行版完全对应fork → clone → 建分支 → 改文件 → PR工具教程适用平台GitHub Desktopgithub-desktop-tutorial.mdWindows / macOSVisual Studio 2017github-windows-vs2017-tutorial.mdWindowsGitKrakengitkraken-tutorial.md跨平台Visual Studio Codegithub-windows-vs-code-tutorial.md跨平台Atlassian Sourcetreesourcetree-macos-tutorial.mdWindows / macOSIntelliJ IDEAgithub-windows-intellij-tutorial.md跨平台以 GitHub Desktop 教程为例其核心提示与命令行版一致DO NOT CLONE THE ORIGINAL REPO. Go to your fork and clone it不要克隆原始仓库去你的 Fork 克隆进一步印证了一切操作基于自己的 Fork这条贯穿全流程的核心原则。总结一次贡献一生受用的标准工作流本教程表面上只教你往贡献者名单里加一个名字但正如 README.zul.md 结尾所言你完成的是fork → clone → edit → pull request这一贡献者日后会反复遇到的标准工作流。它涵盖了 Git 分支隔离、暂存提交、远程推送、PR 评审协作的全部核心环节——掌握它就等于拿到了进入任何开源项目的入场券。完成第一次贡献后你可以通过仓库整理的项目清单寻找更多带 easy 标签的入门 Issue把这套流程持续实践下去。【免费下载链接】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 的完整流程完成你的第一次开源贡献
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 的祖鲁语isiZulu翻译版教程 README.zul.md 为骨架系统讲解初学者如何通过fork → clone → edit → pull request四步标准流程完成第一次开源贡献。本指南覆盖 Git 环境准备、分支管理、提交与推送、Pull Request 提交以及合并冲突、提交修正、fork 同步等进阶 Git 操作阅读后你将具备独立向任意开源项目提交代码贡献的完整实战能力。项目背景与本教程的定位first-contributions 项目的定位非常明确帮助开源新手迈出贡献的第一步。项目根目录的 README.md 用一句话点明了核心目标This project aims to simplify and guide the way beginners make their first contribution简化并引导初学者完成第一次贡献。为了让不同语言背景的开发者都能无障碍学习项目在 docs/translations 目录下维护了上百种语言的翻译版本README.zul.md 就是面向祖鲁语使用者的完整教程。与其他翻译版一样它完整保留了英文原版的全部操作步骤与命令示例——这意味着这套工作流是经过项目长期验证、可以直接照做的标准流程。本教程的实操产物是向仓库根目录的 Contributors.md 贡献者名单文件追加自己的名字。该文件目前已有数千行条目累计超过 5900 行正是由一代代新手通过本文描述的流程累积而成的是这套流程真实可用的直接证据。环境准备确保本机已安装 Git动手之前先确认你的电脑上是否安装了 Git。在终端执行git --version如果系统提示找不到该命令说明尚未安装。不同操作系统有对应的安装方式可参考仓库中整理的安装指南Ubuntu 系installing-git-ubuntu.mdArch 系installing-git-arch.md如果你对命令行完全不熟悉也可以跳过本节直接使用文末列出的 GUI 工具教程如 GitHub Desktop效果相同。第一步Fork 本仓库Fork复刻是 GitHub 提供的一种仓库复制机制。点击仓库页面右上角的 Fork 按钮GitHub 就会在你自己的账户下生成一份该仓库的完整副本。这一操作的关键意义在于Fork 出来的副本归你所有你可以在上面任意修改、创建分支、推送代码而不会影响原始仓库上游仓库的任何内容。后续所有操作都基于你的这份 Fork而不是原始仓库——请务必记住这一点因为它决定了整套工作流的合法性你只能从自己的 Fork 发起 Pull Request。第二步Clone 克隆仓库到本地Fork 完成后进入你自己账户下的 first-contributions 仓库页面点击页面上的 Code 按钮复制仓库 URL 到剪贴板打开终端执行 clone 命令git clone url you just copied其中url you just copied替换为你刚才复制的地址去掉引号。例如假设你的 GitHub 用户名为this-is-yougit clone https://github.com/this-is-you/first-contributions.git这条命令会把 GitHub 上的仓库内容完整下载到本地电脑形成一份与远程仓库完全一致的工作副本。从此你就有了一套远程 Fork 本地仓库的双重操作空间。第三步创建专属分支Clone 完成后先进入仓库目录cd first-contributions然后创建一个属于本次贡献的分支。教程中推荐使用git checkout命令git checkout -b add-你的名字例如贡献者名为 Adam Kowalski可以创建git checkout -b add-adam-kowalski关于分支命名教程特别给出了两条实用建议分支名不强制包含add前缀但加上add是合理的习惯因为该分支的使命就是把你的名字添加到贡献者列表见名知意。需要说明的是较新版本的 Git2.23提供了语义更清晰的新命令git switch根目录 README.md 的英文原版教程即采用git switch -c 新分支名的写法。两条命令等价若你的 Git 版本较旧、执行git switch报错就退回使用git checkout -b。第四步修改文件并提交用任意文本编辑器打开仓库根目录的 Contributors.md把你的名字添加进去。教程给出了三条纪律不要把名字加在文件开头或结尾放在文件中间任意位置即可添加后保存文件。建议照抄仓库中已有的条目格式- 名字例如- [Antonio Campello](https://github.com/antoniocampello)便于维护者审阅。保存后在仓库目录下执行git status检查工作区状态你会看到Contributors.md显示为已修改modified状态。接下来把改动加入暂存区git add Contributors.md然后提交提交信息中把你的名字替换为真实姓名git commit -m Add your-name to Contributors list例如git commit -m Add Adam Kowalski to Contributors list至此你的改动已作为一条本地提交记录挂在刚才创建的add-adam-kowalski分支上。第五步推送改动到 GitHub将本地分支推送到你自己的远程 Forkgit push origin add-your-branch-name把add-your-branch-name替换为之前创建的分支名例如git push origin add-adam-kowalski推送失败认证错误的排查与修复新手推送时最常见的错误是认证失败。如果你看到类似下面的报错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/your-username/first-contributions.git/说明你在使用已被 GitHub 停用的密码认证方式GitHub 已全面转向 token / SSH 密钥认证。此时应改用 SSH 方式连接。先检查当前远程地址配置git remote -v如果输出显示远程地址是 HTTPS 形式origin https://github.com/your-username/your_repo.git (fetch) origin https://github.com/your-username/your_repo.git (push)需要将远程地址切换为 SSH 形式git remote set-url origin gitgithub.com:your-username/your_repo.git同时为本机配置好 SSH 公钥并添加到 GitHub 账户生成与配置步骤参见仓库内的 storing-credentials.md 及英文 README 中引用的 GitHub 官方文档。否则推送时仍会被要求输入用户名和密码导致同样的认证错误。第六步提交 Pull Request推送成功后回到 GitHub 上你自己的 Fork 页面页面顶部会出现一个醒目的Compare pull request按钮点击它确认对比范围base 仓库为原始仓库的 main 分支compare 分支为你刚推送的分支点击Create pull request填写标题与描述后正式提交。提交后仓库维护者会收到通知并将你的改动合并进 main 分支。合并成功后你会收到一封邮件通知。至此一次完整的开源贡献闭环完成。第七步后续进阶——让 Fork 与上游保持同步完成第一次贡献后你必然会遇到一个问题上游仓库持续有新的提交你的 Fork 和本地仓库会逐渐落后。仓库在 keeping-your-fork-synced-with-this-repository.md 中详细讲解了这一场景。开源协作中典型的三角工作流Triangle Workflows涉及三个仓库上游公共仓库本项目的原始仓库你在 GitHub 上的 Fork你本地的仓库。同步的核心思路是先让本地仓库与上游对齐再把本地仓库推送到你的 Fork。首先确保本地处于 main 分支git status # 查看当前所在分支第一行输出 git checkout main # 若不在 main 分支则切换然后把上游仓库添加为名为upstream的远程git remote add upstream https://github.com/firstcontributions/first-contributions.git拉取上游最新内容git fetch upstream将上游 main 分支的更新合并到本地 main教程采用 rebase 方式git rebase upstream/main最后把同步后的本地 main 推送到你的 Fork远程名为origingit push origin main如果想一步完成拉取并合并两个动作可以直接使用git pull upstream main建议在 GitHub 提示你的 Fork 落后于上游若干提交时就执行一次上述同步流程。更多进阶 Git 场景围绕首次贡献可能遇到的各种 Git 操作仓库在 docs/additional-material/git_workflow_scenarios 目录下提供了系统化的专题文档入口为 additional-material.md。几个与贡献者高度相关的场景修正最近一次提交amending-a-commit.md如果提交信息有拼写错误或忘了把某个改动包含进最近一次提交可以执行git commit --amend -m 新的提交信息若该提交已推送远程则需在 amend 后用git push --force覆盖远程历史。文档特别警告force push 会覆盖远程上他人的改动若仅想安全更新自己分支优先使用--force-with-lease。解决合并冲突resolving-merge-conflicts.md当多个贡献者修改同一文件的同一行、或一人删除文件另一人继续修改时Git 无法自动合并会在文件中插入 HEAD、、 branch-name三类冲突标记。处理流程为用git status找出处于 Unmerged paths 下的文件 → 手动编辑取舍 → 删除冲突标记 →git add 文件名标记已解决 →git commit完成合并。压缩提交squashing-commits.md当维护者在 PR 评审中要求把多个提交合并为一个信息完整的提交时可使用交互式 rebase 完成。撤销提交undoing-a-commit.md、reverting-a-commit.md分别面向本地未推送提交的撤销与已推送提交的回滚场景。删除文件与分支removing-a-file.md、removing-branch-from-your-repository.md覆盖提交前删除文件、PR 合并后清理分支的常规操作。.gitignore 与凭证管理creating-a-gitignore-file.md、storing-credentials.md前者保证只提交必要文件后者讲解凭据安全存储需遵循所在机构的安防策略。不习惯命令行试试 GUI 工具教程README.zul.md 明确提示如果不习惯命令行可以使用 GUI 工具完成同样流程。仓库在 docs/gui-tool-tutorials 目录下为六大主流工具提供了图文教程操作路径与命令行版完全对应fork → clone → 建分支 → 改文件 → PR工具教程适用平台GitHub Desktopgithub-desktop-tutorial.mdWindows / macOSVisual Studio 2017github-windows-vs2017-tutorial.mdWindowsGitKrakengitkraken-tutorial.md跨平台Visual Studio Codegithub-windows-vs-code-tutorial.md跨平台Atlassian Sourcetreesourcetree-macos-tutorial.mdWindows / macOSIntelliJ IDEAgithub-windows-intellij-tutorial.md跨平台以 GitHub Desktop 教程为例其核心提示与命令行版一致DO NOT CLONE THE ORIGINAL REPO. Go to your fork and clone it不要克隆原始仓库去你的 Fork 克隆进一步印证了一切操作基于自己的 Fork这条贯穿全流程的核心原则。总结一次贡献一生受用的标准工作流本教程表面上只教你往贡献者名单里加一个名字但正如 README.zul.md 结尾所言你完成的是fork → clone → edit → pull request这一贡献者日后会反复遇到的标准工作流。它涵盖了 Git 分支隔离、暂存提交、远程推送、PR 评审协作的全部核心环节——掌握它就等于拿到了进入任何开源项目的入场券。完成第一次贡献后你可以通过仓库整理的项目清单寻找更多带 easy 标签的入门 Issue把这套流程持续实践下去。【免费下载链接】first-contributions✨ Help beginners to contribute to open source projects项目地址: https://gitcode.com/gh_mirrors/fi/first-contributions创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考