first-contributions 仓库指南以 fork → clone → edit → 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.ks.md撰写完整呈现该项目面向初学者设计的标准贡献流程。读完本文你将掌握从 Fork 仓库、Clone 到本地、创建分支、修改 Contributors.md 并提交、Push 到远端、最终提交 Pull Request 的完整实操能力同时了解 Git 常见报错如旧版本switch命令不可用、push 认证失败的排查与解决方式为后续参与任意开源项目打下基础。项目背景为初学者降低第一次贡献的门槛first-contributions 的核心目标用文档原话说是「帮助初学者并指导他们使其能够轻松完成第一次开源贡献」。它把真实开源协作中最典型的一条路径拆解成可逐步照做的步骤让学习者通过真实提交而非观看教程来获得经验。文档强调过程越轻松学习效益越高。该仓库本身就是一个练习场——真正的修改目标只有一个把贡献者的名字加入根目录的 Contributors.md 名单。这个文件目前已积累数千行贡献者记录本身就是该项目「人人皆可贡献」理念的活证据。仓库采用 MIT 协议全部指导内容以文档形式组织在 docs 目录下并提供了数十种语言的翻译版本索引见 docs/translations/Translations.mdREADME.ks.md 正是其中面向克什米尔语使用者的完整译本。在开始之前请先确认本机已安装 Git。若尚未安装可参考 Git 官方提供的快速安装指引安装完成后可用git --version验证。步骤一Fork 本仓库在仓库页面右上角点击Fork按钮。该操作会在你自己的 GitHub 账号下生成一份本仓库的完整副本此后你对该副本拥有一切修改权限而不会影响原仓库。Fork 出来的副本就是你后续工作的基地。步骤二Clone 仓库到本地进入你账号下刚刚 Fork 出来的仓库页面点击绿色的Code按钮切换到SSH标签页点击复制按钮将仓库 URL 复制到剪贴板。随后打开终端执行克隆命令将占位符替换为刚复制的 URLgit clone url you just copied实际示例this-is-you替换为你的 GitHub 用户名git clone gitgithub.com:this-is-you/first-contributions.git执行后仓库内容会被完整下载到本地当前目录下。步骤三创建新的工作分支首先进入克隆下来的仓库目录cd first-contributions然后使用git switch命令创建并切换到一个新分支git switch -c your-new-branch-name示例分支名习惯以add-开头表示「添加某位贡献者」git switch -c add-alonzo-church旧版 Git 兼容提示如果执行git switch时出现错误信息Git: switch is not a git command. See git --help说明你使用的 Git 版本较旧此时请改用等价的git checkout命令git checkout -b your-new-branch-name为什么要单独建分支这是 Git 协作的标准做法在独立分支上开发可以避免直接污染main主分支也让后续的 Pull Request 对比更加清晰。步骤四修改文件并提交Commit用任意文本编辑器打开根目录的 Contributors.md将你的名字添加到文件中——文档特别建议不要加在文件开头或结尾而是加在中间任意位置这是为了引导初学者练习「编辑已有文件并处理潜在合并冲突」的能力保存文件。回到终端用git status查看工作区状态你会看到Contributors.md已被标记为修改git status将修改加入暂存区Staging Areagit add Contributors.md提交修改your-name替换为你的名字git commit -m Add your-name to Contributors list这里可以顺带说明 Git 三区模型在本次流程中的体现git status对应工作区与暂存区的差异检查git add将文件从工作区移入暂存区git commit则将暂存区内容固化为一次本地提交记录。步骤五将改动 Push 到 GitHub本地提交完成后需要把分支推送到你的 GitHub 远端仓库git push -u origin your-branch-name其中your-branch-name替换为第三步创建的分支名。-u即--set-upstream的作用是把本地分支与远端分支建立跟踪关系这样以后在该分支上只需执行git push即可。常见报错Authentication Error认证失败如果 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/your-username/first-contributions.git/说明你正在使用 HTTPS 地址配合账号密码认证而 GitHub 已不再支持密码方式。文档给出的排查与修复路径如下改用 SSH 认证按照 GitHub 官方教程生成 SSH 密钥并配置到账号检查当前远端地址git remote -v若输出形如https://github.com/your-username/your_repo.gitHTTPS 协议则将其改为 SSH 格式git remote set-url origin gitgithub.com:your-username/your_repo.git否则系统仍会提示输入用户名和密码并最终再次报认证错误。这一故障处理思路在仓库文档体系中得到了延续——关于凭据管理的进一步细节可参考 docs/additional-material/git_workflow_scenarios/storing-credentials.md该文档同时提示凭据存储涉及安全问题需遵循所在单位的安全规范。步骤六提交 Pull Request 供他人审阅Push 成功后回到你的 GitHub 仓库页面会出现一个醒目的Compare pull request按钮点击该按钮确认对比的基准分支base是原仓库的main目标分支compare是你刚才推送的分支填写说明后提交 Pull Request。提交后维护者会将你的改动合并进main分支合并完成时你会收到一封邮件通知。至此一次完整的贡献闭环就完成了。里程碑你已走通的标准贡献工作流祝贺正如文档所说你刚刚完整执行了开源贡献者最常遇到的标准工作流fork → clone → edit → pull request这是一条在任何开源项目中都通用的路径与具体项目无关因此具有极强的可迁移性。继续进阶仓库内的深入资源完成首次贡献后仓库还准备了循序渐进的进阶资料入口见 docs/additional-material/git_workflow_scenarios/additional-material.md覆盖真实协作中几乎一定会遇到的高频场景主题仓库文档路径适用场景同步 Fork 与上游仓库keeping-your-fork-synced-with-this-repository.md上游仓库有新提交提示「落后 N 个提交」时修改最近一次提交amending-a-commit.md提交信息有拼写错误或漏改了文件解决合并冲突resolving-merge-conflicts.mdPR 与他人改动冲突时合并多个提交Squashsquashing-commits.md评审者要求把多个 commit 合并成一个撤销本地/远端提交undoing-a-commit.md、reverting-a-commit.md提交后发现改错了配置 Git 用户信息configuring-git.md首次使用 Git 或需要调整身份信息创建 .gitignorecreating-a-gitignore-file.md排除缓存、日志、密钥等不需要入库的文件其中「保持 Fork 与上游同步」特别值得细读它讲解了开源协作中典型的三角工作流上游公共仓库 → 你的 GitHub Fork → 本地仓库核心命令为添加upstream远端、git fetch upstream后用git rebase upstream/main合并最后git push origin main同步到自己的 Fork也可用git pull upstream main一步完成「拉取并合并」。建议每次看到 GitHub 提示「落后若干提交」时执行一次该流程。此外docs/cli-tool-tutorials 与 docs/gui-tool-tutorials 目录下还提供了命令行扩展教程以及多款 GUI 工具的图文教程如 GitHub Desktop、Visual Studio Code、GitKraken、IntelliJ IDEA、Sourcetree 等不习惯命令行的初学者可以按需选用。若想继续练习仓库的翻译索引 docs/translations/Translations.md 也展示了该项目开放的协作姿态——翻译工作本身同样是一种低门槛的开源贡献方式。最后记住这句话第一次贡献的难度主要来自「不熟悉」而不是「不会」。按本文流程完整走一遍你收获的不只是一次合并通知而是对 Git 分支模型、远端协作与 PR 评审机制的亲身体验。【免费下载链接】first-contributions✨ Help beginners to contribute to open source projects项目地址: https://gitcode.com/gh_mirrors/fi/first-contributions创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考