github.com/kristoff-it/hugo@v0.47.1/CONTRIBUTING.md (about) 1 # Contributing to Hugo 2 3 We welcome contributions to Hugo of any kind including documentation, themes, 4 organization, tutorials, blog posts, bug reports, issues, feature requests, 5 feature implementations, pull requests, answering questions on the forum, 6 helping to manage issues, etc. 7 8 The Hugo community and maintainers are [very active](https://github.com/gohugoio/hugo/pulse/monthly) and helpful, and the project benefits greatly from this activity. We created a [step by step guide](https://gohugo.io/tutorials/how-to-contribute-to-hugo/) if you're unfamiliar with GitHub or contributing to open source projects in general. 9 10 *Note that this repository only contains the actual source code of Hugo. For **only** documentation-related pull requests / issues please refer to the [hugoDocs](https://github.com/gohugoio/hugoDocs) repository.* 11 12 *Changes to the codebase **and** related documentation, e.g. for a new feature, should still use a single pull request.* 13 14 ## Table of Contents 15 16 * [Asking Support Questions](#asking-support-questions) 17 * [Reporting Issues](#reporting-issues) 18 * [Submitting Patches](#submitting-patches) 19 * [Code Contribution Guidelines](#code-contribution-guidelines) 20 * [Git Commit Message Guidelines](#git-commit-message-guidelines) 21 * [Vendored Dependencies](#vendored-dependencies) 22 * [Fetching the Sources From GitHub](#fetching-the-sources-from-github) 23 * [Using Git Remotes](#using-git-remotes) 24 * [Build Hugo with Your Changes](#build-hugo-with-your-changes) 25 * [Updating the Hugo Sources](#updating-the-hugo-sources) 26 27 ## Asking Support Questions 28 29 We have an active [discussion forum](https://discourse.gohugo.io) where users and developers can ask questions. 30 Please don't use the GitHub issue tracker to ask questions. 31 32 ## Reporting Issues 33 34 If you believe you have found a defect in Hugo or its documentation, use 35 the GitHub [issue tracker](https://github.com/gohugoio/hugo/issues) to report 36 the problem to the Hugo maintainers. If you're not sure if it's a bug or not, 37 start by asking in the [discussion forum](https://discourse.gohugo.io). 38 When reporting the issue, please provide the version of Hugo in use (`hugo 39 version`) and your operating system. 40 41 ## Code Contribution 42 43 Hugo has become a fully featured static site generator, so any new functionality must: 44 45 * be useful to many. 46 * fit naturally into _what Hugo does best._ 47 * strive not to break existing sites. 48 * close or update an open [Hugo issue](https://github.com/gohugoio/hugo/issues) 49 50 If it is of some complexity, the contributor is expected to maintain and support the new future (answer questions on the forum, fix any bugs etc.). 51 52 It is recommended to open up a discussion on the [Hugo Forum](https://discourse.gohugo.io/) to get feedback on your idea before you begin. If you are submitting a complex feature, create a small design proposal on the [Hugo issue tracker](https://github.com/gohugoio/hugo/issues) before you start. 53 54 55 **Bug fixes are, of course, always welcome.** 56 57 58 59 ## Submitting Patches 60 61 The Hugo project welcomes all contributors and contributions regardless of skill or experience level. If you are interested in helping with the project, we will help you with your contribution. 62 63 ### Code Contribution Guidelines 64 65 Because we want to create the best possible product for our users and the best contribution experience for our developers, we have a set of guidelines which ensure that all contributions are acceptable. The guidelines are not intended as a filter or barrier to participation. If you are unfamiliar with the contribution process, the Hugo team will help you and teach you how to bring your contribution in accordance with the guidelines. 66 67 To make the contribution process as seamless as possible, we ask for the following: 68 69 * Go ahead and fork the project and make your changes. We encourage pull requests to allow for review and discussion of code changes. 70 * When you’re ready to create a pull request, be sure to: 71 * Sign the [CLA](https://cla-assistant.io/gohugoio/hugo). 72 * Have test cases for the new code. If you have questions about how to do this, please ask in your pull request. 73 * Run `go fmt`. 74 * Add documentation if you are adding new features or changing functionality. The docs site lives in `/docs`. 75 * Squash your commits into a single commit. `git rebase -i`. It’s okay to force update your pull request with `git push -f`. 76 * Ensure that `mage check` succeeds. [Travis CI](https://travis-ci.org/gohugoio/hugo) (Linux and macOS) and [AppVeyor](https://ci.appveyor.com/project/gohugoio/hugo/branch/master) (Windows) will fail the build if `mage check` fails. 77 * Follow the **Git Commit Message Guidelines** below. 78 79 ### Git Commit Message Guidelines 80 81 This [blog article](http://chris.beams.io/posts/git-commit/) is a good resource for learning how to write good commit messages, 82 the most important part being that each commit message should have a title/subject in imperative mood starting with a capital letter and no trailing period: 83 *"Return error on wrong use of the Paginator"*, **NOT** *"returning some error."* 84 85 Also, if your commit references one or more GitHub issues, always end your commit message body with *See #1234* or *Fixes #1234*. 86 Replace *1234* with the GitHub issue ID. The last example will close the issue when the commit is merged into *master*. 87 88 Sometimes it makes sense to prefix the commit message with the package name (or docs folder) all lowercased ending with a colon. 89 That is fine, but the rest of the rules above apply. 90 So it is "tpl: Add emojify template func", not "tpl: add emojify template func.", and "docs: Document emoji", not "doc: document emoji." 91 92 Please use a short and descriptive branch name, e.g. **NOT** "patch-1". It's very common but creates a naming conflict each time when a submission is pulled for a review. 93 94 An example: 95 96 ```text 97 tpl: Add custom index function 98 99 Add a custom index template function that deviates from the stdlib simply by not 100 returning an "index out of range" error if an array, slice or string index is 101 out of range. Instead, we just return nil values. This should help make the 102 new default function more useful for Hugo users. 103 104 Fixes #1949 105 ``` 106 107 ### Fetching the Sources From GitHub 108 109 Due to the way Go handles package imports, the best approach for working on a 110 Hugo fork is to use Git Remotes. Here's a simple walk-through for getting 111 started: 112 113 1. Get the Hugo source: 114 115 ```bash 116 go get -u -v -d github.com/gohugoio/hugo 117 ``` 118 119 1. Install Mage: 120 121 ```bash 122 go get github.com/magefile/mage 123 ``` 124 125 1. Change to the Hugo source directory and fetch the dependencies: 126 127 ```bash 128 cd $HOME/go/src/github.com/gohugoio/hugo 129 mage vendor 130 ``` 131 132 Note that Hugo uses [Go Dep](https://github.com/golang/dep) to vendor dependencies, rather than a simple `go get`. We don't commit the vendored packages themselves to the Hugo git repository. The call to `mage vendor` takes care of all this for you. 133 134 1. Create a new branch for your changes (the branch name is arbitrary): 135 136 ```bash 137 git checkout -b iss1234 138 ``` 139 140 1. After making your changes, commit them to your new branch: 141 142 ```bash 143 git commit -a -v 144 ``` 145 146 1. Fork Hugo in GitHub. 147 148 1. Add your fork as a new remote (the remote name, "fork" in this example, is arbitrary): 149 150 ```bash 151 git remote add fork git://github.com/USERNAME/hugo.git 152 ``` 153 154 1. Push the changes to your new remote: 155 156 ```bash 157 git push --set-upstream fork iss1234 158 ``` 159 160 1. You're now ready to submit a PR based upon the new branch in your forked repository. 161 162 ### Building Hugo with Your Changes 163 164 Hugo uses [mage](https://github.com/magefile/mage) to sync vendor dependencies, build Hugo, run the test suite and other things. You must run mage from the Hugo directory. 165 166 ```bash 167 cd $HOME/go/src/github.com/gohugoio/hugo 168 ``` 169 170 To build Hugo: 171 172 ```bash 173 mage hugo 174 ``` 175 176 To install hugo in `$HOME/go/bin`: 177 178 ```bash 179 mage install 180 ``` 181 182 To run the tests: 183 184 ```bash 185 mage hugoRace 186 mage -v check 187 ``` 188 189 To list all available commands along with descriptions: 190 191 ```bash 192 mage -l 193 ``` 194 195 **Note:** From Hugo 0.43 we have added a build tag, `extended` that adds **SCSS support**. This needs a C compiler installed to build. You can enable this when building by: 196 197 ```bash 198 HUGO_BUILD_TAGS=extended mage install 199 ```` 200 201 ### Updating the Hugo Sources 202 203 If you want to stay in sync with the Hugo repository, you can easily pull down 204 the source changes, but you'll need to keep the vendored packages up-to-date as 205 well. 206 207 ```bash 208 git pull 209 mage vendor 210 ``` 211