From d6093aba4d0b74804378013c2326deb3cca58d7e Mon Sep 17 00:00:00 2001 From: Cameron Moore Date: Tue, 14 Mar 2017 17:03:49 -0500 Subject: [PATCH] docs: Update contributing guides 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 --- CONTRIBUTING.md | 51 +++++++++++-------- docs/content/community/contributing.md | 33 ++++++------ docs/content/overview/installing.md | 29 +++++++---- .../tutorials/how-to-contribute-to-hugo.md | 46 ++++++++++------- 4 files changed, 95 insertions(+), 64 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1228d6f0b..679a2d681 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 + ``` diff --git a/docs/content/community/contributing.md b/docs/content/community/contributing.md index e2da68f10..63675e39d 100644 --- a/docs/content/community/contributing.md +++ b/docs/content/community/contributing.md @@ -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 diff --git a/docs/content/overview/installing.md b/docs/content/overview/installing.md index c3c309fd0..71ca0d60c 100644 --- a/docs/content/overview/installing.md +++ b/docs/content/overview/installing.md @@ -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 diff --git a/docs/content/tutorials/how-to-contribute-to-hugo.md b/docs/content/tutorials/how-to-contribute-to-hugo.md index c034da8c0..bf3627f07 100644 --- a/docs/content/tutorials/how-to-contribute-to-hugo.md +++ b/docs/content/tutorials/how-to-contribute-to-hugo.md @@ -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 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 ``` -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`.