first-contributions 新手首次开源贡献完整实战指南从 Fork 到 Pull Request 的 Git 全流程【免费下载链接】first-contributions✨ Help beginners to contribute to open source projects项目地址: https://gitcode.com/gh_mirrors/fi/first-contributions本篇指南以 first-contributions 仓库的尼泊尔语教程 docs/translations/README.np.md 为骨架完整梳理新手完成第一次开源贡献所必经的Fork → Clone → Edit → Pull Request标准工作流并结合仓库内 docs/additional-material 系列进阶文档补充 Git 配置、分支同步、提交修正、冲突解决与提交压缩等实战细节。读完本文你将掌握在任何 GitHub 开源项目中提交首个 Pull Request 的完整能力并理解这些操作背后的 Git 原理。项目与教程定位first-contributions 是一个专门为开源新手设计的教学仓库其核心目标是简化并引导初学者完成他们的第一次贡献原文档表述。仓库的主体不是复杂代码而是一份可操作的贡献流程演示参与者通过向 Contributors.md 追加自己的名字走完一次真实的 PR 全流程。这个仓库本身同时作为练习场与教材存在——你提交的 PR 会被维护者合并进 master 分支从而完成一次真实、可验证的开源贡献。整个教程不需要任何编程基础只要安装了 Git 即可跟随操作。若你对命令行不熟悉仓库还提供了 GUI 工具教程GitHub Desktop、VS Code 等下文会一并说明。前置条件安装并配置 Git安装 Git如果电脑上尚未安装 Git请先完成安装。原文档指引在 docs/additional-material/git_workflow_scenarios/installing-git-ubuntu.mdUbuntu、docs/additional-material/git_workflow_scenarios/installing-git-arch.mdArch Linux等文档中提供了针对不同系统的安装说明。首次提交前的身份配置Git 在创建提交时必须知道你是谁。如果你未配置身份就执行git commit会看到如下提示$ git commit *** Please tell me who you are. Run git config --global user.email youexample.com git config --global user.name Your Name to set your accounts default identity. Omit --global to set the identity only in this repository.协作开发时团队需要根据提交记录追溯谁在何时修改了哪部分因此 Git 将每次提交与姓名、邮箱绑定。根据 configuring-git.md 的说明配置身份有三种作用域作用域命令适用场景全局配置Globalgit config --global user.email youexample.comgit config --global user.name Your Name系统内所有仓库生效多数场景的首选仓库级配置Repositorygit config user.email youalternate.comgit config user.name Your Name仅当前仓库生效例如用公司邮箱提交工作项目命令行配置Command-linegit -c user.nameYour Name -c user.emailyouexample.com commit -m msg仅本次命令生效优先级最高三种配置的优先级顺序为命令行 仓库级 全局。也就是说同一个变量在命令行与全局都有值时命令行值会胜出。除用户信息外Git 还提供其他常用配置项例如core.editor指定编写提交信息的编辑器commit.template指定系统上的某个文件作为提交信息模板color.ui布尔值控制 Git 输出是否使用颜色。第一步Fork 仓库进入 first-contributions 仓库页面点击页面顶部的Fork按钮即可将该仓库复制一份到你自己的 GitHub 账户下。Fork 的本质是在你的账户命名空间下创建一份独立的仓库副本后续所有修改都在这份副本上进行不会影响原仓库。第二步Clone 仓库到本地Fork 完成后进入你账户下的 fork 副本点击Code按钮再点击copy to clipboard图标复制仓库 URL。然后打开终端执行克隆命令git clone 你复制的URL示例git clone https://github.com/this-is-you/first-contributions.git将示例中的this-is-you替换为你的 GitHub 用户名。这条命令会把 GitHub 上first-contributions仓库的全部文件复制到你的电脑本地。第三步创建分支克隆完成后进入仓库目录若尚未进入cd first-contributions然后使用git switch命令创建并切换到新分支git switch -c 分支名例如git switch -c add-ram-regmi说明分支名中不强制包含add字样但推荐加上——因为这个分支的用途就是把你的名字添加到 Contributors 列表中命名能直观表达意图也是开源协作的良好习惯。兼容性提示如果执行git switch时出现 switchis not a git command 的错误说明你的 Git 版本较旧可以改用等价的git checkout命令git checkout -b 分支名第四步修改文件并提交现在用文本编辑器打开仓库根目录下的 Contributors.md把你的名字追加进去。原文档特别强调不要加在文件开头或结尾放在文件中间任意位置即可避免与其他人提交的内容产生行冲突。保存文件后回到项目目录执行git status你会看到Contributors.md出现在已修改文件列表中。接下来把修改加入暂存区git add Contributors.md然后提交git commit -m Add your-name to Contributors list将your-name替换为你的真实名字。至此修改已经落在你本地新创建的分支上。从源码结构看Contributors.md 是仓库中最活跃的文件其内容正是由历届新手贡献者的名字列表组成当前已累积数千行这正是把名字写进文件 → 提交 → 被合并这一教学闭环的落点。第五步推送分支到 GitHub使用git push把本地分支推送到你的 GitHub forkgit push -u origin 分支名将分支名替换为你第三步创建的分支名。例如git push -u origin add-ram-regmi其中-u--set-upstream的作用是建立本地分支与远程分支的跟踪关系后续再推送时只需git push即可。推送时的认证问题排查如果你使用 HTTPS 方式推送且遇到认证失败常见报错如下remote: Support for password authentication was removed on August 13, 2021. Please use a personal access token instead. remote: Please see https://github.blog/2020-12-15-token-authentication-requirements-for-git-operations/ for more information. fatal: Authentication failed for https://github.com/your-username/first-contributions.git/2021 年 8 月 13 日起GitHub 已移除对密码认证的支持必须改用 personal access token 或 SSH 密钥。解决方案为你的账户生成并配置 SSH key先用git remote -v检查远程地址若显示的是https://github.com/your-username/your_repo.git这类 HTTPS 地址将其切换为 SSH 地址git remote set-url origin gitgithub.com:your-username/your_repo.git否则仍会反复提示输入用户名和密码并最终认证失败。第六步提交 Pull Request推送成功后回到你的 GitHub fork 页面会看到一个Compare pull request按钮点击进入创建 PR 的界面然后提交 pull request。提交后维护者会把你的改动合并到项目的 master 分支合并完成后你会收到一封通知邮件。此时你的名字已经进入 Contributors.md 的贡献者列表——你的第一次开源贡献就完成了。进阶保持 Fork 与原仓库同步在你和其他人持续贡献的过程中原仓库会不断演进你的 fork 会落后于上游。根据 keeping-your-fork-synced-with-this-repository.md开源协作中存在三个仓库原公共仓库upstream、你的 GitHub forkorigin、你的本地仓库这一协作模型被称为三角工作流Triangle Workflow。完整同步流程如下确认当前在 main 分支git status第一行会显示当前分支若不在则切换git checkout main将原公共仓库添加为upstream远程只需执行一次git remote add upstream https://github.com/firstcontributions/first-contributions.git拉取上游最新代码git fetch upstream将上游 main 分支合并进本地 maingit rebase upstream/main推送本地 main 到你的 forkgit push origin main如果你希望一步完成拉取并合并上游变更也可以直接使用git pull upstream main建议每次 GitHub 提示你的 fork 落后于上游若干提交时都执行一次同步。进阶修正最近一次提交Amend如果你提交后才发现提交信息有拼写错误或漏改了一个词可以修正最近一次提交。根据 amending-a-commit.md分两种场景仅修改提交信息git commit --amend -m 新的提交信息 git push origin branch-name注意仅执行git commit --amend会打开文本编辑器让你修改信息加上-m参数则直接以内联方式指定新信息。修改后还遗漏了改动修改文件加入暂存区git add filename执行git commit --amend可在编辑器中保留或修改提交信息退出编辑器后推送git push origin branch-name。这样两次改动会合并为一个提交而不是产生一条多余的提交记录。已推送提交的强制更新若被修正的提交已经推送到远程amend 会产生新的提交并替换旧提交导致本地与远程历史分叉。此时需要覆盖远程分支历史git add 你的改动文件 git commit --amend -m 新的提交信息 git push --force警告强制推送会覆盖远程分支上的改动其他协作者在此期间推送的变更也会一并被丢弃。若不想误伤他人改动应优先使用更安全的git push --force-with-lease。进阶解决合并冲突当多人同时修改同一文件时可能触发合并冲突。根据 resolving-merge-conflicts.md常见触发场景包括两人编辑同一行、一人删除文件而另一人修改了它、不同分支把同一文件重命名为不同名字等。解决流程定位冲突文件合并后执行git status查看 Unmerged paths 下列出的文件打开冲突文件Git 用如下标记标出冲突区域 HEAD 你的改动 对方分支的改动 branch-name HEAD与之间是当前分支的改动与 branch-name之间是来自另一分支的改动手动解决决定保留哪边、或如何合并两边内容然后删除所有冲突标记、、标记为已解决对每个冲突文件执行git add filename完成合并git commit -m Resolved merge conflicts。辅助手段还包括git mergetool启动可视化的三方合并工具需预先安装 Meld、KDiff3、Beyond Compare 等git merge --abort取消本次合并恢复到合并前的状态。预防冲突的最佳实践是频繁从 main 分支拉取更新git pull origin main以及每个功能或修复都在独立的功能分支上进行git checkout -b feature-branch。进阶压缩提交Squash开源项目评审人经常要求把分支上的多个提交压缩成一个信息清晰的提交。根据 squashing-commits.md步骤为先用git log查看当前分支的提交历史进入交互式变基模式指定回溯深度。例如把最近 2 个提交合并git rebase -i HEAD~2编辑器会列出类似如下的待处理提交pick blablabla Changing test01.txt file pick blablabla2 Adding dummy01.txt file # Commands: # p, pick use commit # r, reword use commit, but edit the commit message # e, edit use commit, but stop for amending # s, squash use commit, but meld into previous commit # f, fixup like squash, but discard this commits log message # x, exec run command (the rest of the line) using shell把第二个提交前的pick改为squashpick blablabla Changing test01.txt file squash blablabla2 Adding dummy01.txt file保存退出后Git 会打开编辑器让你确认合并后的提交信息确认后退出即可。再次运行git log两个提交已合并为一个。使用 GUI 工具完成贡献如果你不习惯命令行仓库为多种图形化工具提供了完整教程可从 GUI 工具教程 列表中选择GitHub DesktopVisual Studio 2017GitKrakenVisual Studio CodeAtlassian SourcetreeIntelliJ IDEA完成之后的下一步祝贺你完成了标准贡献流程你已经在实践中走通了Fork → Clone → Edit → Pull Request——这是所有开源贡献者最常遇到的协作范式。接下来可以查看 附加材料其中汇总了本仓库全部进阶主题修改提交、同步 fork、删除分支、回退提交、回滚提交、压缩提交、撤销本地提交、创建 .gitignore 文件、凭证存储、合并冲突解决、移动提交到其他分支、重置分支等阅读 其他语言的翻译版获取以你熟悉语言撰写的教程将该流程迁移到其他开源项目开启持续贡献之路。附本指南涉及的仓库文件索引文件用途Contributors.md新手练习写入名字的目标文件docs/translations/README.np.md尼泊尔语版主教程本文骨架docs/additional-material/git_workflow_scenarios/additional-material.md进阶主题索引docs/additional-material/git_workflow_scenarios/configuring-git.mdGit 身份与配置详解docs/additional-material/git_workflow_scenarios/keeping-your-fork-synced-with-this-repository.mdFork 同步与三角工作流docs/additional-material/git_workflow_scenarios/amending-a-commit.md修正最近提交docs/additional-material/git_workflow_scenarios/resolving-merge-conflicts.md合并冲突解决docs/additional-material/git_workflow_scenarios/squashing-commits.md提交压缩【免费下载链接】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 的 Git 全流程
first-contributions 新手首次开源贡献完整实战指南从 Fork 到 Pull Request 的 Git 全流程【免费下载链接】first-contributions✨ Help beginners to contribute to open source projects项目地址: https://gitcode.com/gh_mirrors/fi/first-contributions本篇指南以 first-contributions 仓库的尼泊尔语教程 docs/translations/README.np.md 为骨架完整梳理新手完成第一次开源贡献所必经的Fork → Clone → Edit → Pull Request标准工作流并结合仓库内 docs/additional-material 系列进阶文档补充 Git 配置、分支同步、提交修正、冲突解决与提交压缩等实战细节。读完本文你将掌握在任何 GitHub 开源项目中提交首个 Pull Request 的完整能力并理解这些操作背后的 Git 原理。项目与教程定位first-contributions 是一个专门为开源新手设计的教学仓库其核心目标是简化并引导初学者完成他们的第一次贡献原文档表述。仓库的主体不是复杂代码而是一份可操作的贡献流程演示参与者通过向 Contributors.md 追加自己的名字走完一次真实的 PR 全流程。这个仓库本身同时作为练习场与教材存在——你提交的 PR 会被维护者合并进 master 分支从而完成一次真实、可验证的开源贡献。整个教程不需要任何编程基础只要安装了 Git 即可跟随操作。若你对命令行不熟悉仓库还提供了 GUI 工具教程GitHub Desktop、VS Code 等下文会一并说明。前置条件安装并配置 Git安装 Git如果电脑上尚未安装 Git请先完成安装。原文档指引在 docs/additional-material/git_workflow_scenarios/installing-git-ubuntu.mdUbuntu、docs/additional-material/git_workflow_scenarios/installing-git-arch.mdArch Linux等文档中提供了针对不同系统的安装说明。首次提交前的身份配置Git 在创建提交时必须知道你是谁。如果你未配置身份就执行git commit会看到如下提示$ git commit *** Please tell me who you are. Run git config --global user.email youexample.com git config --global user.name Your Name to set your accounts default identity. Omit --global to set the identity only in this repository.协作开发时团队需要根据提交记录追溯谁在何时修改了哪部分因此 Git 将每次提交与姓名、邮箱绑定。根据 configuring-git.md 的说明配置身份有三种作用域作用域命令适用场景全局配置Globalgit config --global user.email youexample.comgit config --global user.name Your Name系统内所有仓库生效多数场景的首选仓库级配置Repositorygit config user.email youalternate.comgit config user.name Your Name仅当前仓库生效例如用公司邮箱提交工作项目命令行配置Command-linegit -c user.nameYour Name -c user.emailyouexample.com commit -m msg仅本次命令生效优先级最高三种配置的优先级顺序为命令行 仓库级 全局。也就是说同一个变量在命令行与全局都有值时命令行值会胜出。除用户信息外Git 还提供其他常用配置项例如core.editor指定编写提交信息的编辑器commit.template指定系统上的某个文件作为提交信息模板color.ui布尔值控制 Git 输出是否使用颜色。第一步Fork 仓库进入 first-contributions 仓库页面点击页面顶部的Fork按钮即可将该仓库复制一份到你自己的 GitHub 账户下。Fork 的本质是在你的账户命名空间下创建一份独立的仓库副本后续所有修改都在这份副本上进行不会影响原仓库。第二步Clone 仓库到本地Fork 完成后进入你账户下的 fork 副本点击Code按钮再点击copy to clipboard图标复制仓库 URL。然后打开终端执行克隆命令git clone 你复制的URL示例git clone https://github.com/this-is-you/first-contributions.git将示例中的this-is-you替换为你的 GitHub 用户名。这条命令会把 GitHub 上first-contributions仓库的全部文件复制到你的电脑本地。第三步创建分支克隆完成后进入仓库目录若尚未进入cd first-contributions然后使用git switch命令创建并切换到新分支git switch -c 分支名例如git switch -c add-ram-regmi说明分支名中不强制包含add字样但推荐加上——因为这个分支的用途就是把你的名字添加到 Contributors 列表中命名能直观表达意图也是开源协作的良好习惯。兼容性提示如果执行git switch时出现 switchis not a git command 的错误说明你的 Git 版本较旧可以改用等价的git checkout命令git checkout -b 分支名第四步修改文件并提交现在用文本编辑器打开仓库根目录下的 Contributors.md把你的名字追加进去。原文档特别强调不要加在文件开头或结尾放在文件中间任意位置即可避免与其他人提交的内容产生行冲突。保存文件后回到项目目录执行git status你会看到Contributors.md出现在已修改文件列表中。接下来把修改加入暂存区git add Contributors.md然后提交git commit -m Add your-name to Contributors list将your-name替换为你的真实名字。至此修改已经落在你本地新创建的分支上。从源码结构看Contributors.md 是仓库中最活跃的文件其内容正是由历届新手贡献者的名字列表组成当前已累积数千行这正是把名字写进文件 → 提交 → 被合并这一教学闭环的落点。第五步推送分支到 GitHub使用git push把本地分支推送到你的 GitHub forkgit push -u origin 分支名将分支名替换为你第三步创建的分支名。例如git push -u origin add-ram-regmi其中-u--set-upstream的作用是建立本地分支与远程分支的跟踪关系后续再推送时只需git push即可。推送时的认证问题排查如果你使用 HTTPS 方式推送且遇到认证失败常见报错如下remote: Support for password authentication was removed on August 13, 2021. Please use a personal access token instead. remote: Please see https://github.blog/2020-12-15-token-authentication-requirements-for-git-operations/ for more information. fatal: Authentication failed for https://github.com/your-username/first-contributions.git/2021 年 8 月 13 日起GitHub 已移除对密码认证的支持必须改用 personal access token 或 SSH 密钥。解决方案为你的账户生成并配置 SSH key先用git remote -v检查远程地址若显示的是https://github.com/your-username/your_repo.git这类 HTTPS 地址将其切换为 SSH 地址git remote set-url origin gitgithub.com:your-username/your_repo.git否则仍会反复提示输入用户名和密码并最终认证失败。第六步提交 Pull Request推送成功后回到你的 GitHub fork 页面会看到一个Compare pull request按钮点击进入创建 PR 的界面然后提交 pull request。提交后维护者会把你的改动合并到项目的 master 分支合并完成后你会收到一封通知邮件。此时你的名字已经进入 Contributors.md 的贡献者列表——你的第一次开源贡献就完成了。进阶保持 Fork 与原仓库同步在你和其他人持续贡献的过程中原仓库会不断演进你的 fork 会落后于上游。根据 keeping-your-fork-synced-with-this-repository.md开源协作中存在三个仓库原公共仓库upstream、你的 GitHub forkorigin、你的本地仓库这一协作模型被称为三角工作流Triangle Workflow。完整同步流程如下确认当前在 main 分支git status第一行会显示当前分支若不在则切换git checkout main将原公共仓库添加为upstream远程只需执行一次git remote add upstream https://github.com/firstcontributions/first-contributions.git拉取上游最新代码git fetch upstream将上游 main 分支合并进本地 maingit rebase upstream/main推送本地 main 到你的 forkgit push origin main如果你希望一步完成拉取并合并上游变更也可以直接使用git pull upstream main建议每次 GitHub 提示你的 fork 落后于上游若干提交时都执行一次同步。进阶修正最近一次提交Amend如果你提交后才发现提交信息有拼写错误或漏改了一个词可以修正最近一次提交。根据 amending-a-commit.md分两种场景仅修改提交信息git commit --amend -m 新的提交信息 git push origin branch-name注意仅执行git commit --amend会打开文本编辑器让你修改信息加上-m参数则直接以内联方式指定新信息。修改后还遗漏了改动修改文件加入暂存区git add filename执行git commit --amend可在编辑器中保留或修改提交信息退出编辑器后推送git push origin branch-name。这样两次改动会合并为一个提交而不是产生一条多余的提交记录。已推送提交的强制更新若被修正的提交已经推送到远程amend 会产生新的提交并替换旧提交导致本地与远程历史分叉。此时需要覆盖远程分支历史git add 你的改动文件 git commit --amend -m 新的提交信息 git push --force警告强制推送会覆盖远程分支上的改动其他协作者在此期间推送的变更也会一并被丢弃。若不想误伤他人改动应优先使用更安全的git push --force-with-lease。进阶解决合并冲突当多人同时修改同一文件时可能触发合并冲突。根据 resolving-merge-conflicts.md常见触发场景包括两人编辑同一行、一人删除文件而另一人修改了它、不同分支把同一文件重命名为不同名字等。解决流程定位冲突文件合并后执行git status查看 Unmerged paths 下列出的文件打开冲突文件Git 用如下标记标出冲突区域 HEAD 你的改动 对方分支的改动 branch-name HEAD与之间是当前分支的改动与 branch-name之间是来自另一分支的改动手动解决决定保留哪边、或如何合并两边内容然后删除所有冲突标记、、标记为已解决对每个冲突文件执行git add filename完成合并git commit -m Resolved merge conflicts。辅助手段还包括git mergetool启动可视化的三方合并工具需预先安装 Meld、KDiff3、Beyond Compare 等git merge --abort取消本次合并恢复到合并前的状态。预防冲突的最佳实践是频繁从 main 分支拉取更新git pull origin main以及每个功能或修复都在独立的功能分支上进行git checkout -b feature-branch。进阶压缩提交Squash开源项目评审人经常要求把分支上的多个提交压缩成一个信息清晰的提交。根据 squashing-commits.md步骤为先用git log查看当前分支的提交历史进入交互式变基模式指定回溯深度。例如把最近 2 个提交合并git rebase -i HEAD~2编辑器会列出类似如下的待处理提交pick blablabla Changing test01.txt file pick blablabla2 Adding dummy01.txt file # Commands: # p, pick use commit # r, reword use commit, but edit the commit message # e, edit use commit, but stop for amending # s, squash use commit, but meld into previous commit # f, fixup like squash, but discard this commits log message # x, exec run command (the rest of the line) using shell把第二个提交前的pick改为squashpick blablabla Changing test01.txt file squash blablabla2 Adding dummy01.txt file保存退出后Git 会打开编辑器让你确认合并后的提交信息确认后退出即可。再次运行git log两个提交已合并为一个。使用 GUI 工具完成贡献如果你不习惯命令行仓库为多种图形化工具提供了完整教程可从 GUI 工具教程 列表中选择GitHub DesktopVisual Studio 2017GitKrakenVisual Studio CodeAtlassian SourcetreeIntelliJ IDEA完成之后的下一步祝贺你完成了标准贡献流程你已经在实践中走通了Fork → Clone → Edit → Pull Request——这是所有开源贡献者最常遇到的协作范式。接下来可以查看 附加材料其中汇总了本仓库全部进阶主题修改提交、同步 fork、删除分支、回退提交、回滚提交、压缩提交、撤销本地提交、创建 .gitignore 文件、凭证存储、合并冲突解决、移动提交到其他分支、重置分支等阅读 其他语言的翻译版获取以你熟悉语言撰写的教程将该流程迁移到其他开源项目开启持续贡献之路。附本指南涉及的仓库文件索引文件用途Contributors.md新手练习写入名字的目标文件docs/translations/README.np.md尼泊尔语版主教程本文骨架docs/additional-material/git_workflow_scenarios/additional-material.md进阶主题索引docs/additional-material/git_workflow_scenarios/configuring-git.mdGit 身份与配置详解docs/additional-material/git_workflow_scenarios/keeping-your-fork-synced-with-this-repository.mdFork 同步与三角工作流docs/additional-material/git_workflow_scenarios/amending-a-commit.md修正最近提交docs/additional-material/git_workflow_scenarios/resolving-merge-conflicts.md合并冲突解决docs/additional-material/git_workflow_scenarios/squashing-commits.md提交压缩【免费下载链接】first-contributions✨ Help beginners to contribute to open source projects项目地址: https://gitcode.com/gh_mirrors/fi/first-contributions创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考