phoenix/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2024-07-05 08:42:12 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Update contributing guides

Browse source 
Add vendoring and make targets.  Require Go 1.8+ and remove mention of
GOPATH (just assume $HOME/go).

Due to time contraints, the contributing tutorial was only slightly
updated to make obvious corrections.

Fixes #3153
This commit is contained in:
Cameron Moore 2017-03-14 17:03:49 -05:00 committed by digitalcraftsman
parent 638cc806d6
commit d6093aba4d
4 changed files with 95 additions and 64 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

51
CONTRIBUTING.md
View file

@ -14,9 +14,11 @@ The Hugo community and maintainers are [very active](https://github.com/spf13/hu
* [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 @@ To make the contribution process as seamless as possible, we ask for the followi
* 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 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 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,22 +84,31 @@ new default function more useful for Hugo users.
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
Hugo fork is to use Git Remotes. Here's a simple walk-through for getting
started:
1. Get the latest Hugo sources:
```
go get -u -t github.com/spf13/hugo/...
```
1. Fetch the Hugo sources as described above.
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 @@ started:
### 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` — all the “magic” above is already in the `Makefile`. :wink:
```
git pull
make vendor
```

33
docs/content/community/contributing.md
View file

@ -13,7 +13,7 @@ title: Contributing to Hugo
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 @@ When you're ready to create a pull request, be sure to:
* 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 @@ If everything looks fine, we are ready to commit your additions. For the sake of
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

29
docs/content/overview/installing.md
View file

@ -104,24 +104,31 @@ In any of the [Linux distributions that support snaps](http://snapcraft.io/docs/
### 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

26
docs/content/tutorials/how-to-contribute-to-hugo.md
View file

@ -82,7 +82,17 @@ hub version 2.2.2
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:
@ -90,10 +100,10 @@ We assume that you've set up your `GOPATH` (see the section above if you're unsu
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
@ -184,21 +194,23 @@ You can start Hugo's built-in server via `hugo server`. Browse the documentation
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
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):