shithub: hugo

--- a/CONTRIBUTING.md

+++ b/CONTRIBUTING.md

@@ -14,9 +14,11 @@

 * [Submitting Patches](#submitting-patches)

   * [Code Contribution Guidelines](#code-contribution-guidelines)

   * [Git Commit Message Guidelines](#git-commit-message-guidelines)

+  * [Vendored Dependencies](#vendored-dependencies)

+  * [Fetching the Sources From GitHub](#fetching-the-sources-from-github)

   * [Using Git Remotes](#using-git-remotes)

   * [Build Hugo with Your Changes](#build-hugo-with-your-changes)

-  * [Add Compile Information to Hugo](#add-compile-information-to-hugo)

+  * [Updating the Hugo Sources](#updating-the-hugo-sources)

 ## Asking Support Questions

@@ -51,7 +53,7 @@

     * Run `go fmt`.

     * Add documentation if you are adding new features or changing functionality.  The docs site lives in `/docs`.

     * Squash your commits into a single commit. `git rebase -i`. It’s okay to force update your pull request with `git push -f`.

-    * Make sure `go test ./...` passes, and `go build` completes. [Travis CI](https://travis-ci.org/spf13/hugo) (Linux and OS&nbsp;X) and [AppVeyor](https://ci.appveyor.com/project/spf13/hugo/branch/master) (Windows) will catch most things that are missing.

+    * Ensure that `make check` succeeds. [Travis CI](https://travis-ci.org/spf13/hugo) (Linux and OS&nbsp;X) and [AppVeyor](https://ci.appveyor.com/project/spf13/hugo/branch/master) (Windows) will fail the build if `make check` fails.

     * Follow the **Git Commit Message Guidelines** below.

 ### Git Commit Message Guidelines

@@ -82,6 +84,19 @@

 Fixes #1949

```

+### Vendored Dependencies

+Hugo uses [govendor](https://github.com/kardianos/govendor) to vendor dependencies, but we don't commit the vendored packages themselves to the Hugo git repository.

+Therefore, a simple `go get` is not supported since `go get` is not vendor-aware.

+You **must use govendor** to fetch and manage Hugo's dependencies.

+### Fetch the Sources From GitHub

+    ```

+    go get github.com/kardianos/govendor

+    govendor get github.com/spf13/hugo

+    ```

 ### Using Git Remotes

 Due to the way Go handles package imports, the best approach for working on a

@@ -88,16 +103,12 @@

 Hugo fork is to use Git Remotes.  Here's a simple walk-through for getting

 started:

-1. Get the latest Hugo sources:

+1. Fetch the Hugo sources as described above.

-    ```

-    go get -u -t github.com/spf13/hugo/...

-    ```

 1. Change to the Hugo source directory:

```

-    cd $GOPATH/src/github.com/spf13/hugo

+    cd $HOME/go/src/github.com/spf13/hugo

```

 1. Create a new branch for your changes (the branch name is arbitrary):

@@ -131,20 +142,20 @@

 ### Build Hugo with Your Changes

 ```bash

-cd $GOPATH/src/github.com/spf13/hugo

-go build

-mv hugo /usr/local/bin/

+cd $HOME/go/src/github.com/spf13/hugo

+make hugo

+# or to install in $HOME/go/bin:

+make install

```

-### Add Compile Information to Hugo

+### Updating the Hugo Sources

-To add compile information to Hugo, replace the `go build` command with the following *(replace `/path/to/hugo` with the actual path)*:

+If you want to stay in sync with the Hugo repository, you can easily pull down

+the source changes, but you'll need to keep the vendored packages up-to-date as

+well.

-    go build -ldflags "-X /path/to/hugo/hugolib.CommitHash=`git rev-parse --short HEAD 2>/dev/null` -X github.com/spf13/hugo/hugolib.BuildDate=`date +%FT%T%z`"

-This will result in `hugo version` output that looks similar to:

-    Hugo Static Site Generator v0.13-DEV-8042E77 buildDate: 2014-12-25T03:25:57-07:00

-Alternatively, just run `make` &mdash; all the “magic” above is already in the `Makefile`.  :wink:

+    ```

+    git pull

+    make vendor

+    ```

--- a/docs/content/community/contributing.md

+++ b/docs/content/community/contributing.md

@@ -13,7 +13,7 @@

 weight: 30

---

-All contributions to Hugo are welcome. Whether you want to scratch an itch or simply contribute to the project, feel free to pick something from the [roadmap]({{< relref "meta/roadmap.md" >}}) or contact [spf13](http://spf13.com/) about what may make sense to do next.

+All contributions to Hugo are welcome. Whether you want to scratch an itch or simply contribute to the project, feel free to pick something from the [roadmap]({{< relref "meta/roadmap.md" >}}) or contact the dev team via the [Forums](https://discuss.gohugo.io/) or [Gitter](https://gitter.im/spf13/hugo) about what may make sense to do next.

 You should fork the project and make your changes.  *We encourage pull requests to discuss code changes.*

@@ -23,38 +23,37 @@

   * Have test cases for the new code.  If you have questions about how to do it, please ask in your pull request.

   * Run `go fmt`.

   * Squash your commits into a single commit.  `git rebase -i`.  It's okay to force update your pull request.

-  * Make sure `go test ./...` passes, and `go build` completes.  Our [Travis CI loop](https://travis-ci.org/spf13/hugo) will catch most things that are missing.  The exception: Windows.  We run on Windows from time to time, but if you have access, please check on a Windows machine too.

+  * Run `make check` and ensure it succeeds.  [Travis CI](https://travis-ci.org/spf13/hugo) and [Appveyor](https://ci.appveyor.com/project/spf13/hugo) will runs these checks and fail the build if `make check` fails.

 ## Contribution Overview

 We wrote a [detailed guide]({{< relref "tutorials/how-to-contribute-to-hugo.md" >}}) for newcomers that guides you step by step to your first contribution. If you are more experienced, follow the guide below.

 # Building from source

-## Clone locally (for contributors):

+## Vendored Dependencies

-    git clone https://github.com/spf13/hugo

-    cd hugo

-    go get

+Hugo uses [govendor][] to vendor dependencies, but we don't commit the vendored packages themselves to the Hugo git repository.

+Therefore, a simple `go get` is not supported since `go get` is not vendor-aware.

+You **must use govendor** to fetch Hugo's dependencies.

-Because Go expects all of your libraries to be found in either

-`$GOROOT` or `$GOPATH`, it's helpful to symlink the project to one

-of the following paths:

+## Fetch the Sources

- * `ln -s /path/to/your/hugo $GOPATH/src/github.com/spf13/hugo`

- * `ln -s /path/to/your/hugo $GOROOT/src/pkg/github.com/spf13/hugo`

+    go get github.com/kardianos/govendor

+    govendor get github.com/spf13/hugo

 ## Running Hugo

-    cd /path/to/hugo

-    go install github.com/spf13/hugo/hugo

+    cd $HOME/go/src/github.com/spf13/hugo

     go run main.go

 ## Building Hugo

-    cd /path/to/hugo

-    go build -o hugo main.go

-    mv hugo /usr/local/bin/

+    cd $HOME/go/src/github.com/spf13/hugo

+    make build

+    # or to install to $HOME/go/bin:

+    make install

 # Showcase additions

@@ -108,3 +107,5 @@

 Last but not least, we're ready to create a [pull request](https://github.com/spf13/hugo/compare).

 Don't forget to accept the contributor license agreement. Click on the yellow badge in the automatically added comment in the pull request.

+[govendor]: https://github.com/kardianos/govendor

--- a/docs/content/overview/installing.md

+++ b/docs/content/overview/installing.md

@@ -104,24 +104,31 @@

 ### Prerequisite tools for downloading and building source code

 * [Git](http://git-scm.com/)

-* [Go][] 1.5+

+* [Go][] 1.8+

+* [govendor][]

-### Get directly from GitHub

+### Vendored Dependencies

-    $ export GOPATH=$HOME/go

-    $ go get -v github.com/spf13/hugo

+Hugo uses [govendor][] to vendor dependencies, but we don't commit the vendored packages themselves to the Hugo git repository.

+Therefore, a simple `go get` is not supported since `go get` is not vendor-aware.

+You **must use govendor** to fetch Hugo's dependencies.

-`go get` will then fetch Hugo and all its dependent libraries to your

-`$GOPATH/src` directory, and compile everything into the final `hugo`

-(or `hugo.exe`) executable, which you will find sitting in the

-`$GOPATH/bin/` directory, all ready to go!

+### Fetch from GitHub

-You may run `go get` with the `-u` option to update Hugo's dependencies:

+    go get github.com/kardianos/govendor

+    govendor get github.com/spf13/hugo

-    $ go get -u -v github.com/spf13/hugo

+`govendor get` will fetch Hugo and all its dependent libraries to

+`$HOME/go/src/github.com/spf13/hugo`, and compile everything into a final `hugo`

+(or `hugo.exe`) executable, which you will find sitting inside

+`$HOME/go/bin/`, all ready to go!

+*Windows users: where you see the `$HOME` environment variable above, replace it with `%USERPROFILE%`.*

 ## Contributing

-Please see the [contributing guide](/doc/contributing/).

+Please see the [contributing guide](/doc/contributing/) if you are interested in

+working with the Hugo source or contributing to the project in any way.

 [Go]: http://golang.org/

+[govendor]: https://github.com/kardianos/govendor

--- a/docs/content/tutorials/how-to-contribute-to-hugo.md

+++ b/docs/content/tutorials/how-to-contribute-to-hugo.md

@@ -14,7 +14,7 @@

 Hugo is an open source project and lives by the work of its [contributors](https://github.com/spf13/hugo/graphs/contributors). Help to make Hugo even more awesome. There are plenty of [open issues](https://github.com/spf13/hugo/issues) on GitHub and we need your help.

-This tutorial is intended for people who are new to Git, GitHub or open source projects in general. It should help to overcome most of the barriers that newcomers encounter. It describes step by step what you need to do.

+This tutorial is intended for people who are new to Git, GitHub or open source projects in general. It should help to overcome most of the barriers that newcomers encounter. It describes step by step what you need to do.

 For any kind of questions please take a look at our [forum](https://discuss.gohugo.io/).

@@ -24,7 +24,7 @@

 Let's confirm the correct installation of Go. Open a terminal (or command line under Windows). Execute `go version` and you should see the version number of your Go installation. Next, make sure that you setup the `GOPATH` as described in the installation guide.

-You can print the `GOPATH` with `echo $GOPATH`. You should see a non-empty string containing a valid path to your Go workspace.

+You can print the `GOPATH` with `echo $GOPATH`. You should see a non-empty string containing a valid path to your Go workspace.

 ### GVM as alternative

@@ -42,7 +42,7 @@

 You will need to install Git. This tutorial assumes basic knowledge about Git. Refer to this excellent [Git book](https://git-scm.com/) if you are not sure where to begin. The used terminology will be explained with annotations.

-Git is a [version control system](https://en.wikipedia.org/wiki/Version_control) to track the changes of source code. Hugo depends on smaller third-party packages that are used to extend the functionality. We use them because we don't want to reinvent the wheel.

+Git is a [version control system](https://en.wikipedia.org/wiki/Version_control) to track the changes of source code. Hugo depends on smaller third-party packages that are used to extend the functionality. We use them because we don't want to reinvent the wheel.

 Go ships with a sub-command called `get` that will download these packages for us when we setup our working environment. The source code of the packages is tracked with Git. `get` will interact with the Git servers of the package hosters in order to fetch all dependencies.

@@ -82,8 +82,18 @@

 The working copy is set up locally on your computer. It's what you'll edit, compile, and end up pushing back to GitHub. The main steps are cloning the repository and creating your fork as a remote.

-### Clone the repository

+### Vendored Dependencies

+Hugo uses [govendor](https://github.com/kardianos/govendor) to vendor dependencies, but we don't commit the vendored packages themselves to the Hugo git repository.

+Therefore, a simple `go get` is not supported since `go get` is not vendor-aware.

+You **must use govendor** to fetch and manage Hugo's dependencies.

+```sh

+go get -v -u github.com/kardianos/govendor

+```

+### Fetch the Sources from GitHub

 We assume that you've set up your `GOPATH` (see the section above if you're unsure about this). You should now copy the Hugo repository down to your computer. You'll hear this called "clone the repo". GitHub's [help pages](https://help.github.com/articles/cloning-a-repository/) give us a short explanation:

 > When you create a repository on GitHub, it exists as a remote repository. You can create a local clone of your repository on your computer and sync between the two locations.

@@ -90,10 +100,10 @@

 We're going to clone the [master Hugo repository](https://github.com/spf13/hugo). That seems counter-intuitive, since you won't have commit rights on it. But it's required for the Go workflow. You'll work on a copy of the master and push your changes to your own repository on GitHub.

-So, let's clone that master repository:

+So, let's clone that master repository with govendor:

 ```sh

-go get -v -u github.com/spf13/hugo

+govendor get -v github.com/spf13/hugo

```

 ### Fork the repository

@@ -116,7 +126,7 @@

 ```sh

 cd $GOPATH/src/github.com/spf13/hugo

-```

+```

 Now Git needs to know that our fork exists by adding the copied remote url:

@@ -128,11 +138,11 @@

 Alternatively, you can use the Git wrapper Hub. Hub makes forking a repository easy:

-```sh

+```sh

 git fork

```

-That command will log in to GitHub using your account, create a fork of the repository that you're currently working in, and add it as a remote to your working copy.

+That command will log in to GitHub using your account, create a fork of the repository that you're currently working in, and add it as a remote to your working copy.

 #### Trust, but verify

@@ -175,7 +185,7 @@

 ### Contributing to the documentation

-Perhaps you want to start contributing to the docs. Then you can ignore most of the following steps. You can find the documentation within the cloned repository in the subfolder `docs`. Change the directory with `cd docs`. Install the [latest release]({{< relref "overview/installing.md" >}}). Or read on and build Hugo from source.

+Perhaps you want to start contributing to the docs. Then you can ignore most of the following steps. You can find the documentation within the cloned repository in the subfolder `docs`. Change the directory with `cd docs`. Install the [latest release]({{< relref "overview/installing.md" >}}). Or read on and build Hugo from source.

 You can start Hugo's built-in server via `hugo server`. Browse the documentation by entering [http://localhost:1313](http://localhost:1313) in the address bar of your browser. The server automatically updates the page if you change its content.

@@ -184,7 +194,7 @@

 While making changes in the codebase it's a good idea to build the binary to test them:

 ```sh

-go build -o hugo main.go

+make hugo

```

 ### Testing

@@ -191,14 +201,16 @@

 Sometimes changes on the codebase can cause unintended side effects. Or they don't work as expected. Most functions have their own test cases. You can find them in files ending with `_test.go`.

-Make sure the commands `go test ./...` passes, and `go build` completes.

+```sh

+make check

+```

 ### Formatting

-The Go code styleguide maybe is opiniated but it ensures that the codebase looks the same, regardless who wrote the code. Go comes with its own formatting tool. Let's apply the styleguide to our addtions:

+The Go code styleguide maybe is opiniated but it ensures that the codebase looks the same, regardless who wrote the code. Go comes with its own formatting tool. Let's apply the styleguide to our additions:

 ```sh

-go fmt ./...

+govendor fmt +local

```

 Once you made your additions commit your changes. Make sure that you follow our [code contribution guidelines](https://github.com/spf13/hugo/blob/master/CONTRIBUTING.md):

@@ -213,7 +225,7 @@

 ### Modify commits

-You noticed some commit messages don't fulfill the code contribution guidelines or you just forget something to add some files? No problem. Git provides the necessary tools to fix such problems. The next two methods cover all common cases.

+You noticed some commit messages don't fulfill the code contribution guidelines or you just forget something to add some files? No problem. Git provides the necessary tools to fix such problems. The next two methods cover all common cases.

 If you are unsure what a command does leave the commit as it is. We can fix your commits later in the pull request.

@@ -274,7 +286,7 @@

 We also want to rewrite the commits message of the third last commit. We forgot "docs:" as prefix according to the code contribution guidelines. The operation to rewrite a commit is called `reword` (or `r` as shortcut).

-You should end up with a similar setup:

+You should end up with a similar setup:

 ```sh

 pick 80d02a1 tpl: Add hasPrefix to the template funcs' "smoke test"

@@ -303,7 +315,7 @@

 git push --set-upstream <YOUR-GITHUB-USERNAME> <BRANCHNAME>

```

-Now Git knows the destination. Next time when you to push commits you just need to enter `git push`.

+Now Git knows the destination. Next time when you to push commits you just need to enter `git push`.

 If you modified your commit history in the last step GitHub will reject your try to push. This is a safety-feature because the commit history isn't the same and new commits can't be appended as usual. You can enforce this push explicitly with `git push --force`.