本图文教程包含较旧的软件和硬件。截图用于解释流程,但菜单名称、价格、要求和服务可用性可能不同。请查阅链接的项目文档,以你所运行的版本为准。
如何 Fork 开源项目
如果刚接触开源软件,直接参与可能像跳进深水区。不过别担心,本指南会逐一解释整个过程。我们将以 Bitcoiner.Guide 为练习场,带你撰写文章,并提出把修改合并到主项目的请求。
第 1 步:创建 GitHub 账户并安装所需工具
必要步骤
先确保电脑上安装了所有必要工具。
-
GitHub 账户:Fork 项目和提交修改需要 GitHub 账户。如果还没有,请在 GitHub 创建。
-
Git:Git 是版本控制系统,让开发者追踪和管理代码变更,是使用 GitHub 的必备工具。许多电脑已预装 Git。打开终端并输入
git -v即可检查,安装后会返回 Git 版本;若未安装,请查看这篇 指南。 -
Visual Studio Code:这是多用途文本编辑器,内置功能可以简化 Git 操作。从 这里 下载。
对于历史上的 Jekyll 源码,应先安装受支持的 Ruby 环境和 Bundler,再安装仓库依赖。在 macOS 上,应使用 chruby、rbenv、asdf 或其他受支持版本管理器管理独立的 Ruby,不要依赖苹果系统自带的 Ruby。确认 ruby -v 后,在该环境中安装所需 gem,不要惯常使用 sudo。Windows 用户需要受支持的 RubyInstaller 和开发工具包。这些 Jekyll 步骤描述的是原始仓库,而不是静态 3.0 改版。
补充信息
打开终端的方法因操作系统而异。以下是三个常见桌面操作系统中的方法:
- Windows:
- 通过开始菜单:点击开始按钮或按 Windows 键,在搜索栏输入“cmd”或“Command Prompt”,再按回车。
- 通过运行对话框:按
Windows+R打开运行对话框,输入“cmd”,再按回车。
- macOS:
- 通过 Spotlight:按
Command+Space打开 Spotlight 搜索,输入“Terminal”,再按回车。 - 通过 Finder:打开 Finder 窗口,进入 Applications -> Utilities,双击 Terminal。
- 通过 Spotlight:按
- Linux:
- 通过应用列表:视发行版和桌面环境而定,通常可在应用列表或启动器中找到终端应用。
- 通过快捷键:在许多发行版中,可以按
Ctrl+Alt+T打开终端窗口。
无论使用哪种操作系统,在 Visual Studio Code 中都可以通过顶部菜单 View -> Terminal 打开终端。
第 2 步:Fork Bitcoiner.Guide
Fork 会在你自己的 GitHub 账户下创建仓库副本,让你可以修改而不影响原项目。
- 前往 https://github.com/BitcoinQnA/Bitcoiner.Guide。
- 点击页面右上角“Fork”按钮,在自己的账户中创建项目副本。
FIG. 01第 2 步:Fork Bitcoiner.Guide
第 3 步:将项目克隆到电脑
现在需要把项目副本下载到电脑,也就是“克隆”。
- 进入你 Fork 的项目,URL 应为
https://github.com/YOUR_GITHUB_USERNAME/Bitcoiner.Guide - 点击绿色“Code”按钮,再点击剪贴板图标复制 URL。
FIG. 02第 3 步:将项目克隆到电脑
- 打开 Visual Studio Code。
- 点击左侧面板的“Source Control”按钮。
- 点击“Clone Repository”。
- 在弹出的对话框中粘贴刚复制的 URL,再按回车。
FIG. 03第 3 步:将项目克隆到电脑
- 提示选择目录时,进入桌面并点击“Select Repository Location”。
FIG. 04第 3 步:将项目克隆到电脑
第 4 步:创建新分支
在包括开源项目在内的协作项目中,为修改创建新分支是良好做法。使用独立分支,可以将你的修改与主项目隔离开;主分支通常称为“main”或“master”。
- 点击屏幕左下角分支名称,应该为
master或main。 - 在弹出的对话框中选择
Create new branch。 - 为新分支输入名称,例如“foundation-devices”,再按回车。
FIG. 05第 4 步:创建新分支
随时可以点击左下角分支名称,从列表中选择主分支切换回去。
第 5 步:在本地配置项目
安装 Ruby 或 Bundler 前,应阅读当前 README、依赖锁定文件和贡献说明。把修改保留在功能分支上,运行项目文档规定的本地检查,再提出拉取请求。下方示例命令描述的是原始 Jekyll 项目,不是这个本地设计实验的构建说明。
接下来在你的电脑上运行 Bitcoiner.Guide。
- 在 Visual Studio Code 中打开终端,菜单为 View -> Terminal。
FIG. 06第 5 步:在本地配置项目
- 运行
bundle install,安装项目所需的 Ruby gem。 - 运行
bundle exec jekyll serve,启动本地服务器。 - 现在可以在
http://localhost:4000查看网站。
FIG. 07第 5 步:在本地配置项目
克隆这个历史 Jekyll 仓库后,应在包含 Gemfile 的目录运行 bundle install,再运行 bundle exec jekyll serve。只安装 Bundler 程序,并不会安装此仓库的依赖。依赖文件改变时,应重新运行 bundle install。
第 6 步:修改并提交
现在开始修改项目,我们将添加一篇名为“Foundation Devices”的文章:
- 在 Visual Studio Code 中创建新文件,格式为:
foundation-devices.md。
FIG. 08第 6 步:修改并提交
- 在文件顶部添加以下元数据:
---
layout: page
title: Foundation Devices
subtitle: Sovereign computing company
---
- 在元数据下方开始撰写文章,例如:
Foundation Devices 是一家硬件公司,打造以比特币为中心的工具,帮助你重新掌握数字主权。他们希望建立一家与众不同的硬件公司,重视开源和本地制造。从 Passport 和 Envoy 开始,但这只是起点!
Bitcoiner.Guide 的文章使用 Markdown 格式。Markdown 是一种轻量标记语言,用于创建带格式的文本。如果想学习加粗、创建列表等操作,这里有一份很好的 指南。
在文章中添加图片:
- 先把图片上传到项目的
assets > img目录。
FIG. 09第 6 步:修改并提交
- 然后使用以下语法插入图片:
<p align="center">
<img src="/assets/img/your-image-file-name.jpg" class="responsive" style="max-width: 100%; height: auto;" />
</p>
- 将
your-image-file-name.jpg替换成图片文件名。 - 使用
CMD+S或CTRL+S保存文件。 - 返回浏览器,前往
http://localhost:4000/foundation-devices
我们把原来的样子:
---
layout: page
title: Foundation Devices
subtitle: Sovereign computing company
---
Foundation Devices is a hardware company that builds Bitcoin-centric tools that empower you to reclaim your digital sovereignty. They aimed to build a different kind of hardware company with an emphasis on Open Source and local manufacturing. This starts with Passport and Envoy – but they are just getting started!
<p align="center">
<img src="/assets/img/foundation-devices-images.jpg" class="responsive" style="max-width: 100%; height: auto;" />
</p>
变成了:
FIG. 10第 6 步:修改并提交
查看项目中其他 .md 文章,可以更好地理解文章结构。尊重项目写作风格、保持一致性很重要。
第 7 步:将修改推送到 GitHub
接下来保存修改,并上传到 GitHub。
- 点击 Visual Studio Code 左侧的源代码管理图标。
- 应该能在“Changes”部分看到修改。点击文件旁的“+”图标,将修改加入暂存区。
FIG. 11第 7 步:将修改推送到 GitHub
- 在顶部文本框输入提交信息,例如“Added Foundation Devices article”,再按
Ctrl+Enter,Mac 上则按Cmd+Enter。 - 点击源代码管理视图顶部三点,选择“Push”,把修改上传到 GitHub。
FIG. 12第 7 步:将修改推送到 GitHub
FIG. 13第 7 步:将修改推送到 GitHub
第 8 步:创建拉取请求
最后,提出把修改合并到原项目的请求:
- 前往 https://github.com/YOUR_GITHUB_USERNAME/Bitcoiner.Guide
- 点击“Pull request”按钮。
- 点击“New pull request”或“Compare & pull request”。
FIG. 14第 8 步:创建拉取请求
- 确保“base repository”为 BitcoinQnA/Bitcoiner.Guide,“head repository”为 YOUR_GITHUB_USERNAME/Bitcoiner.Guide。
- 点击“Create pull request”。
- 为修改输入标题和说明。
- 再次点击“Create pull request”。
FIG. 15第 8 步:创建拉取请求
恭喜!你已成功 Fork Bitcoiner.Guide、作出贡献并创建拉取请求。项目维护者,在这里是 QnA,会审阅修改。他可能直接接受,也可能要求调整或与你讨论。
可选步骤
第 9 步:创建拉取请求后继续修改
创建拉取请求后,你可能发现还想改动一些内容,或维护者要求修改。无需创建新的拉取请求,就能完成这些操作,方法如下:
- 确保在 Visual Studio Code 中使用正确分支,也就是最初修改并创建拉取请求时使用的分支。
- 继续修改代码,并保存文件。
- 像第 6-7 步一样暂存并提交这些修改。
- 点击源代码管理视图顶部三点,选择“Push”。
新修改会自动更新到 GitHub 上已有的拉取请求,无需另建。如果想补充说明,可以进入 GitHub 上的拉取请求,在讨论中留言。
第 10 步:保持 Fork 更新
获取更新只能取得当时可用的仓库状态。后续更新仍须主动审查和应用;获取成功不保证部署会自动保持最新。
Fork 项目时,创建的是项目在某个时间点的快照。但原项目不会停止,其他贡献者的修改会让它不断发展。要让自己的 Fork 保持与原项目最新变更同步,请按照以下步骤操作:
- 将原项目添加为远程仓库:这一步告诉 Git 原项目在哪里,只需要执行一次。
- 打开 Visual Studio Code,并确保已打开 Bitcoiner.Guide 项目。
- 在 Visual Studio Code 中打开终端,菜单为 View -> Terminal。
- 输入
git remote add upstream https://github.com/BitcoinQnA/Bitcoiner.Guide.git并按回车。这条命令添加一个新的远程仓库,也就是原项目,并命名为“upstream”。
- 获取原项目的变更:这一步下载原项目的最新修改,但尚未将它们合并到你的项目。
- 在终端输入
git fetch upstream并按回车。
- 在终端输入
- 切换到主分支:应把变更合并到主分支,而不是你进行修改的功能分支。
- 在 Visual Studio Code 中点击屏幕左下角分支名称,此时应该是功能分支的名称。
- 在弹出的对话框中选择主分支,通常名为
main或master。
- 合并变更:这一步将原项目的修改合并到你的主分支。
- 在终端输入
git merge upstream/main或git merge upstream/master,取决于原项目的主分支名称,再按回车。
- 在终端输入
结语
参与 Bitcoiner.Guide 这样的开源项目,尤其对新手来说,可能令人望而却步。但这份完整指南提供了必要步骤和工具,帮助你有信心 Fork 项目、进行修改并提交拉取请求。
记住,开源贡献不仅是写代码,也包括协作、学习、分享和改进。第一次不顺利也不要气馁,随着练习,你会越来越熟悉流程。每一份贡献,无论多小,都有价值。
关于作者
你好,我是 Bitlevi!我通过撰写比特币和 FOSS 工具的文章,整理追求自主权过程中学到的知识。欢迎在 Twitter 给我留言,或访问我的 网站。如果喜欢这篇指南并愿意捐赠,这里是我的 PayNym!
