贡献开发

简介

Hugo 是一个开源项目，靠贡献者的工作而存在。我们有很多[开放问题][issues]，我们需要您的帮助使 Hugo 变得更加出色。您不需要成为 Go 大师就能为该项目的发展做出贡献。

假设

本贡献指南采用逐步的方法，希望能帮助新手。因此，我们只假设以下内容：

• 您是 Git 或开源项目的新手
• 您是 Hugo 的粉丝，并且热衷于为该项目做出贡献

安装 Go

安装 Go 应该只需几分钟。在您的计算机上有多个选择来运行 Go。

如果您在按照 Go 的安装指南进行安装时遇到问题，请查看[Go Bootcamp 页面，其中包含了各个平台的安装设置][gobootcamp]，或在 [Hugo 论坛][forums]与 Hugo 社区联系。

从源代码安装 Go

[下载最新稳定版本的 Go][godl] 并按照官方的[Go 安装指南][goinstall]进行操作。

安装完 Go 后，让我们确认一切是否正常工作。打开终端或在 Windows 下打开命令行，输入以下命令：

go version

您应该会在控制台上看到类似以下的信息。请注意，此版本反映了页面最后更新时 Go 的最新版本：

go version go1.12 darwin/amd64

接下来，请确保您按照[安装指南][setupgopath]设置了 GOPATH。

您可以使用 echo $GOPATH 命令来查看 GOPATH。您应该会看到一个非空字符串，其中包含指向 Go 工作区的有效路径，例如：

/Users/<yourusername>/Code/go

使用 Homebrew 安装 Go

如果您是 macOS 用户并且已在计算机上安装了 Homebrew，安装 Go 只需运行下面的命令：

brew install go

通过 GVM 安装 Go

更有经验的用户可以使用 [Go Version Manager][gvm] (GVM)。GVM 允许您在同一台计算机上切换不同的 Go 版本。如果您是初学者，您可能不需要此功能。然而，GVM 让您轻松升级到新发布的 Go 版本，只需几个命令即可。

如果您长时间关注 Hugo 的开发进展，GVM 尤其有用。以后的 Hugo 版本通常会使用最新版本的 Go 进行编译。如果您想跟上的话，早晚都得升级。

创建 GitHub 帐号

如果您要贡献代码，您需要在 GitHub 上拥有一个账户。请访问 www.github.com/join 并创建一个个人账户。

在系统上安装 Git

您需要在计算机上安装 Git 才能为 Hugo 开发做出贡献。教授 Git 的范围超出了 Hugo 文档的范围，但如果您不确定从哪里开始学习 Git 的基础知识，我们推荐您阅读 [Git 书籍][gitbook]。本文档中也包含了 Git 命令的简要解释。

Git 是一个版本控制系统，用于跟踪源代码的变化。Hugo 依赖于一些较小的第三方软件包来扩展功能。我们使用这些软件包是因为我们不想重复造轮子。

Go 附带了一个名为 get 的子命令，当我们设置工作环境时，它可以帮助我们下载这些软件包。这些软件包的源代码是通过 Git 跟踪的。get 将与软件包托管服务器的 Git 服务器进行交互，以获取所有依赖项。

返回终端并检查 Git 是否已安装。输入 git version 并按回车。如果命令返回一个版本号，您可以跳过本节的其余部分。否则，请下载最新版本的 Git，并按照此安装指南进行操作。

最后，请再次使用 git version 命令检查 Git 是否安装成功。

Git 图形界面工具

有几个图形界面客户端可帮助您操作 Git。并非所有的图形界面客户端都适用于所有操作系统，并且它们的使用方式可能不同。因此，我们将文档化如何使用命令行。因为无论在哪个操作系统上，命令都是相同的。

在您的系统上安装 Hub（可选）

Hub 是一个与 GitHub 协作的好工具。它的主要网站是 hub.github.com。请随意安装这个小巧的 Git 包装器。

在 Mac 上，您可以使用 Homebrew 安装 Hub：

brew install hub

现在，我们将在 Bash 中创建一个别名，这样输入 git 时实际上运行的是 Hub：

echo "alias git='hub'" >> ~/.bash_profile

确认安装：

git version 2.21.0
hub version 2.10.0

设置您的工作副本

在计算机上设置本地存储库的工作副本。您将编辑、编译和将更改推送回 GitHub 的文件的本地副本。主要步骤是克隆存储库并将您的 fork 设置为远程存储库。

克隆存储库

我们假设您已经设置了 GOPATH（如果您不确定，请查看上面的部分）。现在，您应将 Hugo 存储库复制到计算机上。这被称为“克隆存储库”。GitHub 的帮助页面给出了一个简短的解释：

我们将克隆主 Hugo 存储库。这似乎有些不合常理，因为您没有对其进行提交权限。但这是 Go 工作流程所要求的。您将在主存储库的副本上工作，并将您的更改推送到您在 GitHub 上的存储库。

因此，让我们创建一个新目录并克隆该主存储库：

mkdir $HOME/src
cd $HOME/src
git clone https://github.com/gohugoio/hugo.git

自 Hugo 0.48 版起，Hugo 使用内置于 Go 1.11 的 Go Modules 支持进行构建。最简单的方法是在 GOPATH 之外的目录中克隆 Hugo。

然后，通过在克隆的目录中运行以下命令来安装 Hugo 的依赖项：

cd $HOME/src/hugo
go install

Hugo 依赖于 mage 来进行一些方便的构建和测试操作。如果您还没有安装 mage，请获取：

go install github.com/magefile/mage@latest

Fork 存储库

如果您对这个术语不熟悉，GitHub 的帮助页面提供了一个简单的解释：

手动派生

在 GitHub 上打开Hugo 存储库，然后单击右上角的“Fork”按钮。

现在在 GitHub 上打开您的 fork 存储库，并复制您的 fork 的远程 URL。您可以选择使用 HTTPS 或 SSH 作为 Git 在下面的操作中使用的协议。如果不确定，始终选择 HTTPS （如此页面所述）。

切换回终端并进入最后一步的克隆主存储库的此目录下：

cd $HOME/src/hugo

现在，需要让 Git 知道我们的 fork 存在，方法是添加复制的远程 URL：

git remote add <YOUR-GITHUB-USERNAME> <COPIED REMOTE-URL>

使用 Hub 派生

或者，您可以使用 Git 包装器 Hub。Hub 让派生存储库变得简单：

git fork

该命令将使用您的帐户登录到 GitHub，为您当前工作的存储库创建一个 fork，并将其添加为工作副本的一个远程分支。

信任，但要核实

让我们通过列出所有已知的远程存储库来检查是否一切顺利：

git remote -v

输出应该类似于以下内容：

digitalcraftsman    git@github.com:digitalcraftsman/hugo.git (fetch)
digitalcraftsman    git@github.com:digitalcraftsman/hugo.git (push)
origin  https://github.com/gohugoio/hugo (fetch)
origin  https://github.com/gohugoio/hugo (push)

Hugo Git 贡献工作流程

创建新分支

您不应该针对“master”分支进行开发。开发团队不会接受针对该分支的拉取请求。相反，请创建一个具有描述性命名的分支并在其上工作。

首先，您应始终从主存储库拉取最新的更改：

git checkout master
git pull

现在我们可以为您的添加创建一个新分支：

git checkout -b <BRANCH-NAME>

您可以使用 git branch 命令检查您目前所在的分支。您应该能够看到所有本地分支的列表。当前分支会在前面用一个小星号表示。

贡献文档

也许您想开始为 Hugo 文档做出贡献。如果是这样，请忽略下面的大部分步骤，将专注于新克隆存储库中的 /docs 目录。您可以使用 cd docs 命令切换到 Hugo 文档所在的目录。

您可以使用 hugo server 启动 Hugo 的内置服务器。通过在浏览器的地址栏中输入 http://localhost:1313 来浏览文档。服务器会在您更改内容时自动更新页面。

我们为“Hugo 文档贡献指南”开发了[单独的 Hugo 文档贡献指南页面][docscontrib]，以获取关于 Hugo 文档的构建、组织和改进的更多信息，感谢您的慷慨帮助。

构建 Hugo

在对代码库进行更改时，构建二进制文件以进行测试是个好主意：

mage hugo

此命令会在存储库的根目录生成二进制文件。

如果您想将二进制文件安装到 $GOPATH/bin 中，请运行：

mage install

测试

有时，对代码库的更改可能会导致意外的副作用。或者它们不按预期工作。大多数函数都有自己的测试用例，您可以在以 _test.go 结尾的文件中找到它们。

确保以下命令的结果正常：

mage -v check

格式化

Go 代码风格指南可能带有个人观点，但它确保代码库的外观是相同的，不管是谁在编写代码。Go 自带有自己的格式化工具。让我们将风格指南应用到我们的改动中：

mage fmt

一旦完成了您的添加，请提交更改。请确保遵循我们的代码贡献指南：

# 添加所有已更改的文件
git add --all
git commit --message "YOUR COMMIT MESSAGE"

提交消息应该描述该提交的内容（例如添加功能 XYZ），而不是如何完成。

修改提交记录

您可能注意到有些提交消息不符合代码贡献指南，或者您忘记添加某些文件？没问题。Git 提供了必要的工具来解决这些问题。接下来的两种方法覆盖了所有常见情况。

如果您不确定某个命令的作用，请保留提交。我们可以稍后在拉取请求中修复您的提交。

修改上一条提交记录

假设您要修改上一条提交消息。执行以下命令，并替换当前的消息：

git commit --amend -m"YOUR NEW COMMIT MESSAGE"

通过查看提交日志，可以查看更改：

git log
# 用 q 退出

完成最后一次提交后，您可能忘记了一些东西。无需创建新的提交。只需添加最新更改并将其合并到预期的提交中：

git add --all
git commit --amend

修改多个提交记录

这需要更多的经验。Git 允许您以交互方式重新排序提交。换句话说：它允许您重写提交历史记录。

git rebase --interactive @~6

命令的末尾的 6 代表应该修改的提交数。应该�