phoenix/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2024-07-02 23:30:00 +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

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

@ -14,7 +14,7 @@ weight: 10
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 @@ The installation of Go should take only a few minutes. [Download](https://golang
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 @@ If you're going to contribute code, you'll need to have an account on GitHub. Go
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,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
@ -116,7 +126,7 @@ Switch back to the terminal and move into the directory of the cloned master rep
```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 @@ git remote add <YOUR-GITHUB-USERNAME> <COPIED REMOTE-URL>
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 @@ You can check on which branch your are with `git branch`. You should see a list
### 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,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):
@ -213,7 +225,7 @@ The commit message should describe what the commit does (e.g. add feature XYZ),
### 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 @@ squash 3502f2e Refactoring and typo fixes
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 @@ To push our commits to the fork on GitHub we need to speficy a destination. A de
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`.