文档教程开源治理【免费下载链接】first-contributions✨ Help beginners to contribute to open source projects项目地址https://gitcode.com/gh_mirrors/fi/first-contributions点击查看免费下载导读本文基于 first-contributions 仓库及其波斯语译本 README.fa.md 整理。first-contributions 是一个专为开源新手设计的练习仓库——你只需在 Contributors.md 中加上自己的名字并提交一个 Pull Request就能完整走通开源协作的标准流程。读完本文你将掌握fork → clone → branch → edit → commit → push → pull request这一套 GitHub 协作的核心链路并学会处理推送认证失败等常见问题为真正参与其他开源项目打好基础。一、项目定位为什么需要一个练习仓库开源项目的首次贡献往往卡在万事开头难不知道流程、怕改坏别人的代码、不熟悉git命令。first-contributions 正是为降低这个门槛而生——它把首次贡献变成了一个零风险、可反复练习的沙盒你要修改的只是一个纯文本名单文件 Contributors.md当前仓库中该文件已积累数千行贡献者名单不会涉及任何业务代码。该仓库本身没有可运行的源码或测试框架它的产品就是这份教程文档体系根目录 README.md 提供基于命令行CLI的英文教程docs/translations 目录收录了数十种语言的 README 译本其中就包括本文依据的 波斯语译本 README.fa.md方便全球新手用母语学习docs/additional-material 提供 Git 进阶技巧修改提交、解决冲突、合并提交等docs/gui-tool-tutorials 提供 GitHub Desktop、VS Code、GitKraken 等图形化工具的替代教程。二、前置准备安装 Git在开始之前请确认你的机器上已经安装了git。在终端中执行以下命令即可验证git --version如果尚未安装请根据你的操作系统选择安装方式Ubuntu/Debian参考 installing-git-ubuntu.zh-cn.mdArch Linux参考 installing-git-arch.zh-cn.md其他平台可参考仓库中 configuring-git.md 对 Git 全局配置的介绍安装完成后建议先配置用户名与邮箱git config --global user.name 你的名字 git config --global user.email 你的邮箱说明原教程中指向 Git 官方安装文档的链接为外部站点本文不再重复给出外部地址以上仓库内的安装文档均可直接查阅。三、第一步Fork派生这个仓库Fork 的作用是在你自己的 GitHub 账号下创建一份目标仓库的完整副本。它不会影响原仓库所有后续的改动都发生在你的副本上这正是开源协作先复制、再修改、后合并的基本模型。操作步骤打开 first-contributions 仓库页面点击页面右上角的Fork按钮稍等片刻你的账号下就会出现一个名为first-contributions的新仓库。此时你拥有的是上游upstream即原仓库的一个独立拷贝之后对它的任何操作都不会打扰原仓库。四、第二步Clone克隆到本地Fork 只是把仓库复制到了你的 GitHub 账号上要编辑文件还需要把它克隆到本地电脑。4.1 复制克隆地址进入你账号下的 fork 仓库页面点击绿色的Code按钮在弹出面板中选择协议HTTPS 或 SSH点击复制到剪贴板copy to clipboard图标得到克隆地址。4.2 执行克隆命令打开终端运行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文件夹中。4.3 进入仓库目录克隆完成后进入该目录如果当前不在其中cd first-contributions提示查看本地仓库与远端remote的对应关系可以随时执行git remote -v。它会列出origin你 fork 的仓库的 fetch/push 地址后续排查推送问题时会用到这个命令。五、第三步创建分支Branch开源协作的黄金准则是永远不要在主干分支上直接改代码而是为每次改动新建一个独立分支这样既便于并行开发也便于维护者审查。在仓库目录内执行git checkout -b your-new-branch-namegit checkout -b的含义是创建并切换到一个新分支其中your-new-branch-name换成你的分支名。例如git checkout -b add-alonzo-church分支命名约定教程建议分支名以add开头如add-你的名字。虽然这不是强制要求但当你本次贡献就是把自己的名字加入名单时这种命名能直观表达分支的用途属于开源社区的常见惯例。关于git switch的补充仓库英文版 README.md 中推荐使用较新的git switch -c语法两者等价例如git switch -c add-alonzo-church。如果你的 Git 版本较老执行git switch会报错switch is not a git command此时回退到git checkout -b即可。本文沿袭波斯语译本采用的git checkout -b写法兼容性最好。六、第四步做出修改并提交Commit6.1 修改 Contributors.md用任意文本编辑器打开仓库根目录下的 Contributors.md 文件把你的名字加入名单中。这里有三个注意事项不要把名字加在文件开头或末尾——刻意加在中间是为了模拟与别人的改动共存的真实协作场景同时锻炼你处理相邻改动冲突的能力保持与已有条目一致的格式一般形如- 你的名字保存文件。6.2 用 git status 查看改动在仓库目录执行git status你会看到Contributors.md出现在 Changes not staged for commit未暂存的改动列表中。git status是协作中最常用的体检命令它能随时告诉你当前在哪个分支、哪些文件被修改、哪些改动已暂存。6.3 用 git add 暂存改动git add Contributors.mdgit add会把指定文件的改动放入暂存区staging area。如果想一次性暂存全部改动也可以使用git add .但精确到文件名是更安全的习惯。6.4 用 git commit 提交git commit -m Add your-name to Contributors list把your-name替换为你的真实名字例如git commit -m Add Alonzo Church to Contributors list-m参数用于直接给出提交说明。一条清晰、有信息量的提交信息是开源协作的基本素养——维护者正是通过提交信息来理解你改了什么、为什么改。七、第五步推送Push到远端本地提交完成接下来把分支推送到你 fork 的远端仓库git push origin add-your-branch-name把add-your-branch-name替换为你之前创建的分支名例如add-alonzo-church。更推荐加上-u参数首次推送git push -u origin your-branch-name-u即--set-upstream会建立本地分支与远端分支的跟踪关系之后在本分支上只需git push即可无需再指定远端和分支名。7.1 推送报错怎么办认证问题排查推送失败是新手最常遇到的坑。仓库英文版 README.md 给出了典型的认证错误排查流程摘录如下。症状推送时出现类似下面的报错remote: Support for password authentication was removed on August 13, 2021. remote: Please use a personal access token instead. fatal: Authentication failed for https://github.com/your-username/first-contributions.git/原因GitHub 已不再接受账号密码方式推送代码需要改用 SSH 密钥或 Personal Access Token 认证。排查步骤先确认你的远端地址配置git remote -v如果输出形如origin https://github.com/your-username/your_repo.git (fetch) origin https://github.com/your-username/your_repo.git (push)说明当前使用的是 HTTPS 协议存在用户名/密码认证的兼容问题。可以改用 SSH 方式git remote set-url origin gitgithub.com:your-username/your_repo.git将你的 SSH 公钥添加到 GitHub 账号后重新推送。进阶阅读关于认证与凭据管理的更多细节仓库还提供了 storing-credentials.md其中也提示了凭据存储涉及安全问题请遵循你所在组织/学校的安全策略。八、第六步提交 Pull RequestPR推送成功后打开你 GitHub 账号下的 fork 仓库页面会看到页面顶部出现一个显眼的Compare pull request按钮点击它。随后你会进入 Pull Request 创建页面检查比较方向确保 base目标仓库分支是你想要合入的源仓库分支compare来源分支是你刚推送的分支填写标题与描述用一句话说清楚本次改动做了什么例如 Add my name to Contributors list点击Create pull request提交。提交之后项目维护者会看到你的 PR 并进行审查审查通过后会把你的改动合并进项目主分支原教程中表述为 master 分支。合并完成后你会收到一封通知邮件。至此你已经完整地走了一遍开源贡献的标准流程。九、接下来可以做什么9.1 庆祝并分享首次 PR 被合并后你可以在 firstcontributions 官方 Web 应用 中分享你的成果让朋友和关注者看到你的第一步。该地址为教程文档中提供的项目配套站点。9.2 继续深化 Git 技能首次提交后强烈建议阅读 additional-material.md中文版见 additional-material.zh-cn.md它汇总了协作中几乎一定会用到的进阶技巧包括场景文档修改最近一次提交amendamending-a-commit.md保持 fork 与上游仓库同步keeping-your-fork-synced-with-this-repository.md把提交移动到其他分支moving-a-commit-to-a-different-branch.md删除本地/远端分支delete-branch-locally.md解决合并冲突resolving-merge-conflicts.md撤销/回滚提交reverting-a-commit.md合并多个提交squashsquashing-commits.md查看提交日志check-commit-log.md其中保持 fork 同步尤其重要随着时间推移上游仓库会不断更新学会用git fetch upstream与git merge同步你的 fork是持续参与开源项目的必备能力。9.3 图形化工具替代方案如果你对命令行CLI不太适应仓库还提供了一套完整的图形化工具教程流程与本文完全等价工具教程GitHub Desktopgithub-desktop-tutorial.md中文版 github-desktop-tutorial.zh-cn.mdVisual Studio 2017github-windows-vs2017-tutorial.mdGitKrakengitkraken-tutorial.mdVisual Studio Codegithub-windows-vs-code-tutorial.md中文版 github-windows-vs-code-tutorial-zh_CN.mdAtlassian Sourcetreesourcetree-macos-tutorial.mdIntelliJ IDEAgithub-windows-intellij-tutorial.md9.4 开始真实项目贡献练习结束后就可以把同样的流程迁移到真实项目上了。官方 Web 应用维护着一个含易上手 issue 的项目清单即 firstcontributions.github.io 中的项目列表可以作为你挑选第一个真实贡献目标的起点。从练习仓库走向真实项目唯一不变的正是本文反复演练的这套 fork → clone → branch → commit → push → PR 工作流。十、总结回顾一下完整命令序列在仓库目录内依次执行# 1. 克隆你 fork 的仓库 git clone https://github.com/this-is-you/first-contributions.git cd first-contributions # 2. 创建并切换到新分支 git checkout -b add-your-name # 3. 编辑 Contributors.md加入你的名字 # 用编辑器修改文件 # 4. 查看改动 → 暂存 → 提交 git status git add Contributors.md git commit -m Add your-name to Contributors list # 5. 推送到远端 git push -u origin add-your-name之后回到 GitHub 页面点击Compare pull request提交 PR。这份流程你将在今后的每一次开源贡献中反复使用first-contributions 的价值就在于用最安全的练习环境让你在真正上战场之前就把每一步都走熟。祝你贡献愉快赞分享文档教程开源治理【免费下载链接】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 c文档教程开源治理first-contributions 新手实战从 fork 到 Pull Request 完成你的第一次开源贡献first contributions 新手实战从 fork 到 Pull Request 完成你的第一次开源贡献 本文以 first contributio文档教程开源治理first-contributions 开源入门实战从 Fork 到 Pull Request 完成你的第一次贡献first contributions 开源入门实战从 Fork 到 Pull Request 完成你的第一次贡献 本指南以 first contributi文档教程开源治理创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考