CONTRIBUTING.md (9121B)
1 # Contributing to Hugo
2
3 **Note March 16th 2022:** We are currently very constrained on human resources to do code reviews, so we currently require any new Pull Requests to be limited to bug fixes closing an existing issue. Also, we have updated to Go 1.18, but we will currently not accept any generic rewrites, "interface{} to any" replacements and similar.
4
5 We welcome contributions to Hugo of any kind including documentation, themes,
6 organization, tutorials, blog posts, bug reports, issues, feature requests,
7 feature implementations, pull requests, answering questions on the forum,
8 helping to manage issues, etc.
9
10 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.
11
12 *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.*
13
14 *Changes to the codebase **and** related documentation, e.g. for a new feature, should still use a single pull request.*
15
16 ## Table of Contents
17
18 * [Asking Support Questions](#asking-support-questions)
19 * [Reporting Issues](#reporting-issues)
20 * [Submitting Patches](#submitting-patches)
21 * [Code Contribution Guidelines](#code-contribution-guidelines)
22 * [Git Commit Message Guidelines](#git-commit-message-guidelines)
23 * [Fetching the Sources From GitHub](#fetching-the-sources-from-github)
24 * [Building Hugo with Your Changes](#building-hugo-with-your-changes)
25
26 ## Asking Support Questions
27
28 We have an active [discussion forum](https://discourse.gohugo.io) where users and developers can ask questions.
29 Please don't use the GitHub issue tracker to ask questions.
30
31 ## Reporting Issues
32
33 If you believe you have found a defect in Hugo or its documentation, use
34 the GitHub issue tracker to report
35 the problem to the Hugo maintainers. If you're not sure if it's a bug or not,
36 start by asking in the [discussion forum](https://discourse.gohugo.io).
37 When reporting the issue, please provide the version of Hugo in use (`hugo
38 version`) and your operating system.
39
40 - [Hugo Issues · gohugoio/hugo](https://github.com/gohugoio/hugo/issues)
41 - [Hugo Documentation Issues · gohugoio/hugoDocs](https://github.com/gohugoio/hugoDocs/issues)
42 - [Hugo Website Theme Issues · gohugoio/hugoThemesSite](https://github.com/gohugoio/hugoThemesSite/issues)
43
44 ## Code Contribution
45
46 Hugo has become a fully featured static site generator, so any new functionality must:
47
48 * be useful to many.
49 * fit naturally into _what Hugo does best._
50 * strive not to break existing sites.
51 * close or update an open [Hugo issue](https://github.com/gohugoio/hugo/issues)
52
53 If it is of some complexity, the contributor is expected to maintain and support the new feature in the future (answer questions on the forum, fix any bugs etc.).
54
55 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.
56
57 Any non-trivial code change needs to update an open [issue](https://github.com/gohugoio/hugo/issues). A non-trivial code change without an issue reference with one of the labels `bug` or `enhancement` will not be merged.
58
59 Note that we do not accept new features that require [CGO](https://github.com/golang/go/wiki/cgo).
60 We have one exception to this rule which is LibSASS.
61
62 **Bug fixes are, of course, always welcome.**
63
64 ## Submitting Patches
65
66 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.
67
68 ### Code Contribution Guidelines
69
70 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.
71
72 To make the contribution process as seamless as possible, we ask for the following:
73
74 * Go ahead and fork the project and make your changes. We encourage pull requests to allow for review and discussion of code changes.
75 * When you’re ready to create a pull request, be sure to:
76 * Sign the [CLA](https://cla-assistant.io/gohugoio/hugo).
77 * Have test cases for the new code. If you have questions about how to do this, please ask in your pull request.
78 * Run `go fmt`.
79 * Add documentation if you are adding new features or changing functionality. The docs site lives in `/docs`.
80 * Squash your commits into a single commit. `git rebase -i`. It’s okay to force update your pull request with `git push -f`.
81 * Ensure that `mage check` succeeds. [Travis CI](https://travis-ci.org/gohugoio/hugo) (Windows, Linux and macOS) will fail the build if `mage check` fails.
82 * Follow the **Git Commit Message Guidelines** below.
83
84 ### Git Commit Message Guidelines
85
86 This [blog article](https://cbea.ms/git-commit/) is a good resource for learning how to write good commit messages,
87 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:
88 *"js: Return error when option x is not set"*, **NOT** *"returning some error."*
89
90 Most title/subjects should have a lower-cased prefix with a colon and one whitespace. The prefix can be:
91
92 * The name of the package where (most of) the changes are made (e.g. `media: Add text/calendar`)
93 * If the package name is deeply nested/long, try to shorten it from the left side, e.g. `markup/goldmark` is OK, `resources/resource_transformers/js` can be shortened to `js`.
94 * If this commit touches several packages with a common functional topic, use that as a prefix, e.g. `errors: Resolve correct line numbers`)
95 * If this commit touches many packages without a common functional topic, prefix with `all:` (e.g. `all: Reformat Go code`)
96 * If this is a documentation update, prefix with `docs:`.
97 * If nothing of the above applies, just leave the prefix out.
98
99 Also, if your commit references one or more GitHub issues, always end your commit message body with *See #1234* or *Fixes #1234*.
100 Replace *1234* with the GitHub issue ID. The last example will close the issue when the commit is merged into *master*.
101
102 An example:
103
104 ```text
105 tpl: Add custom index function
106
107 Add a custom index template function that deviates from the stdlib simply by not
108 returning an "index out of range" error if an array, slice or string index is
109 out of range. Instead, we just return nil values. This should help make the
110 new default function more useful for Hugo users.
111
112 Fixes #1949
113 ```
114
115 ### Fetching the Sources From GitHub
116
117 Since Hugo 0.48, Hugo uses the Go Modules support built into Go 1.11 to build. The easiest is to clone Hugo in a directory outside of `GOPATH`, as in the following example:
118
119 ```bash
120 mkdir $HOME/src
121 cd $HOME/src
122 git clone https://github.com/gohugoio/hugo.git
123 cd hugo
124 go install
125 ```
126
127 >Note: Some Go tools may not be fully updated to support Go Modules yet. One example would be LiteIDE. Follow [this workaround](https://github.com/visualfc/liteide/issues/986#issuecomment-428117702) for how to continue to work with Hugo below `GOPATH`.
128
129 For some convenient build and test targets, you also will want to install Mage:
130
131 ```bash
132 go install github.com/magefile/mage
133 ```
134
135 Now, to make a change to Hugo's source:
136
137 1. Create a new branch for your changes (the branch name is arbitrary):
138
139 ```bash
140 git checkout -b iss1234
141 ```
142
143 1. After making your changes, commit them to your new branch:
144
145 ```bash
146 git commit -a -v
147 ```
148
149 1. Fork Hugo in GitHub.
150
151 1. Add your fork as a new remote (the remote name, "fork" in this example, is arbitrary):
152
153 ```bash
154 git remote add fork git@github.com:USERNAME/hugo.git
155 ```
156
157 1. Push the changes to your new remote:
158
159 ```bash
160 git push --set-upstream fork iss1234
161 ```
162
163 1. You're now ready to submit a PR based upon the new branch in your forked repository.
164
165 ### Building Hugo with Your Changes
166
167 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.
168
169 ```bash
170 cd $HOME/go/src/github.com/gohugoio/hugo
171 ```
172
173 To build Hugo:
174
175 ```bash
176 mage hugo
177 ```
178
179 To install hugo in `$HOME/go/bin`:
180
181 ```bash
182 mage install
183 ```
184
185 To run the tests:
186
187 ```bash
188 mage hugoRace
189 mage -v check
190 ```
191
192 To list all available commands along with descriptions:
193
194 ```bash
195 mage -l
196 ```
197
198 **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:
199
200 ```bash
201 HUGO_BUILD_TAGS=extended mage install
202 ````