zerica
/
hugo
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
hugo/CONTRIBUTING.md

164 lines
7.0 KiB
Markdown
Raw Normal View History

Add CONTRIBUTING.md Extracted from the current README.md
2016-02-05 04:35:42 +00:00
# Contributing to Hugo
hugo: Update contribution guidelines Refactor the contribution guidelines in the README and CONTRIBUTING files. Simplify the contribution guide in the README and move most of the complex stuff into CONTRIBUTING. Add an explicit commit message guidelines section to CONTRIBUTING. Keep all of the guidelines from Chris Beams except for the 72 character line limit (we don't follow that, nor does the Go team). Add three new guidelines: package prefix in subject, references in body, and encouragement of message body in general. Add a new section to CONTRIBUTING on using Git Remotes.
2016-03-12 23:35:06 +00:00
We welcome contributions to Hugo of any kind including documentation, themes,
organization, tutorials, blog posts, bug reports, issues, feature requests,
feature implementations, pull requests, answering questions on the forum,
helping to manage issues, etc.
Add CONTRIBUTING.md Extracted from the current README.md
2016-02-05 04:35:42 +00:00
Update links in CONTRIBUTING.md due to the org transition
2017-06-13 17:37:30 +00:00
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.
Add CONTRIBUTING.md Extracted from the current README.md
2016-02-05 04:35:42 +00:00
Add note about doc-related pull requests in contribution guide
2017-07-18 19:49:16 +00:00
*Note that this repository only contains the actual source code of Hugo. For documentation-related pull requests / issues please refer to the [hugoDocs](https://github.com/gohugoio/hugodocs) repository.*
hugo: Update contribution guidelines Refactor the contribution guidelines in the README and CONTRIBUTING files. Simplify the contribution guide in the README and move most of the complex stuff into CONTRIBUTING. Add an explicit commit message guidelines section to CONTRIBUTING. Keep all of the guidelines from Chris Beams except for the 72 character line limit (we don't follow that, nor does the Go team). Add three new guidelines: package prefix in subject, references in body, and encouragement of message body in general. Add a new section to CONTRIBUTING on using Git Remotes.
2016-03-12 23:35:06 +00:00
## Table of Contents
Add CONTRIBUTING.md Extracted from the current README.md
2016-02-05 04:35:42 +00:00
hugo: Update contribution guidelines Refactor the contribution guidelines in the README and CONTRIBUTING files. Simplify the contribution guide in the README and move most of the complex stuff into CONTRIBUTING. Add an explicit commit message guidelines section to CONTRIBUTING. Keep all of the guidelines from Chris Beams except for the 72 character line limit (we don't follow that, nor does the Go team). Add three new guidelines: package prefix in subject, references in body, and encouragement of message body in general. Add a new section to CONTRIBUTING on using Git Remotes.
2016-03-12 23:35:06 +00:00
* [Asking Support Questions](#asking-support-questions)
* [Reporting Issues](#reporting-issues)
* [Submitting Patches](#submitting-patches)
* [Code Contribution Guidelines](#code-contribution-guidelines)
* [Git Commit Message Guidelines](#git-commit-message-guidelines)
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
2017-03-14 22:03:49 +00:00
* [Vendored Dependencies](#vendored-dependencies)
* [Fetching the Sources From GitHub](#fetching-the-sources-from-github)
hugo: Update contribution guidelines Refactor the contribution guidelines in the README and CONTRIBUTING files. Simplify the contribution guide in the README and move most of the complex stuff into CONTRIBUTING. Add an explicit commit message guidelines section to CONTRIBUTING. Keep all of the guidelines from Chris Beams except for the 72 character line limit (we don't follow that, nor does the Go team). Add three new guidelines: package prefix in subject, references in body, and encouragement of message body in general. Add a new section to CONTRIBUTING on using Git Remotes.
2016-03-12 23:35:06 +00:00
* [Using Git Remotes](#using-git-remotes)
* [Build Hugo with Your Changes](#build-hugo-with-your-changes)
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
2017-03-14 22:03:49 +00:00
* [Updating the Hugo Sources](#updating-the-hugo-sources)
Add CONTRIBUTING.md Extracted from the current README.md
2016-02-05 04:35:42 +00:00
hugo: Update contribution guidelines Refactor the contribution guidelines in the README and CONTRIBUTING files. Simplify the contribution guide in the README and move most of the complex stuff into CONTRIBUTING. Add an explicit commit message guidelines section to CONTRIBUTING. Keep all of the guidelines from Chris Beams except for the 72 character line limit (we don't follow that, nor does the Go team). Add three new guidelines: package prefix in subject, references in body, and encouragement of message body in general. Add a new section to CONTRIBUTING on using Git Remotes.
2016-03-12 23:35:06 +00:00
## Asking Support Questions
Add CONTRIBUTING.md Extracted from the current README.md
2016-02-05 04:35:42 +00:00
Update links to new discuss URL
2017-06-17 08:06:49 +00:00
We have an active [discussion forum](https://discourse.gohugo.io) where users and developers can ask questions.
docs: Properly capitalize GitHub
2017-04-05 16:41:23 +00:00
Please don't use the GitHub issue tracker to ask questions.
hugo: Update contribution guidelines Refactor the contribution guidelines in the README and CONTRIBUTING files. Simplify the contribution guide in the README and move most of the complex stuff into CONTRIBUTING. Add an explicit commit message guidelines section to CONTRIBUTING. Keep all of the guidelines from Chris Beams except for the 72 character line limit (we don't follow that, nor does the Go team). Add three new guidelines: package prefix in subject, references in body, and encouragement of message body in general. Add a new section to CONTRIBUTING on using Git Remotes.
2016-03-12 23:35:06 +00:00
## Reporting Issues
If you believe you have found a defect in Hugo or its documentation, use
Update links in CONTRIBUTING.md due to the org transition
2017-06-13 17:37:30 +00:00
the GitHub [issue tracker](https://github.com/gohugoio/hugo/issues) to report the problem to the Hugo maintainers.
Update links to new discuss URL
2017-06-17 08:06:49 +00:00
If you're not sure if it's a bug or not, start by asking in the [discussion forum](https://discourse.gohugo.io).
hugo: Update contribution guidelines Refactor the contribution guidelines in the README and CONTRIBUTING files. Simplify the contribution guide in the README and move most of the complex stuff into CONTRIBUTING. Add an explicit commit message guidelines section to CONTRIBUTING. Keep all of the guidelines from Chris Beams except for the 72 character line limit (we don't follow that, nor does the Go team). Add three new guidelines: package prefix in subject, references in body, and encouragement of message body in general. Add a new section to CONTRIBUTING on using Git Remotes.
2016-03-12 23:35:06 +00:00
When reporting the issue, please provide the version of Hugo in use (`hugo version`) and your operating system.
## Submitting Patches
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.
Hugo is a very active project with many contributions happening daily.
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.
### Code Contribution Guidelines
To make the contribution process as seamless as possible, we ask for the following:
* Go ahead and fork the project and make your changes. We encourage pull requests to allow for review and discussion of code changes.
Add CONTRIBUTING.md Extracted from the current README.md
2016-02-05 04:35:42 +00:00
* When you’re ready to create a pull request, be sure to:
Update links in CONTRIBUTING.md due to the org transition
2017-06-13 17:37:30 +00:00
* Sign the [CLA](https://cla-assistant.io/gohugoio/hugo).
hugo: Update contribution guidelines Refactor the contribution guidelines in the README and CONTRIBUTING files. Simplify the contribution guide in the README and move most of the complex stuff into CONTRIBUTING. Add an explicit commit message guidelines section to CONTRIBUTING. Keep all of the guidelines from Chris Beams except for the 72 character line limit (we don't follow that, nor does the Go team). Add three new guidelines: package prefix in subject, references in body, and encouragement of message body in general. Add a new section to CONTRIBUTING on using Git Remotes.
2016-03-12 23:35:06 +00:00
* Have test cases for the new code. If you have questions about how to do this, please ask in your pull request.
* 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`.
Update links in CONTRIBUTING.md due to the org transition
2017-06-13 17:37:30 +00:00
* Ensure that `make 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 `make check` fails.
hugo: Update contribution guidelines Refactor the contribution guidelines in the README and CONTRIBUTING files. Simplify the contribution guide in the README and move most of the complex stuff into CONTRIBUTING. Add an explicit commit message guidelines section to CONTRIBUTING. Keep all of the guidelines from Chris Beams except for the 72 character line limit (we don't follow that, nor does the Go team). Add three new guidelines: package prefix in subject, references in body, and encouragement of message body in general. Add a new section to CONTRIBUTING on using Git Remotes.
2016-03-12 23:35:06 +00:00
* Follow the **Git Commit Message Guidelines** below.
### Git Commit Message Guidelines
hugo: Revert git commit message guidelines
2016-06-17 13:23:43 +00:00
This [blog article](http://chris.beams.io/posts/git-commit/) is a good resource for learning how to write good commit messages,
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:
*"Return error on wrong use of the Paginator"*, **NOT** *"returning some error."*
Enhance commit message guidelines
2016-11-04 18:37:41 +00:00
hugo: Revert git commit message guidelines
2016-06-17 13:23:43 +00:00
Also, if your commit references one or more GitHub issues, always end your commit message body with *See #1234* or *Fixes #1234*.
Replace *1234* with the GitHub issue ID. The last example will close the issue when the commit is merged into *master*.
Enhance commit message guidelines
2016-11-04 18:37:41 +00:00
hugo: Revert git commit message guidelines
2016-06-17 13:23:43 +00:00
Sometimes it makes sense to prefix the commit message with the packagename (or docs folder) all lowercased ending with a colon.
That is fine, but the rest of the rules above apply.
So it is "tpl: Add emojify template func", not "tpl: add emojify template func.", and "docs: Document emoji", not "doc: document emoji."
hugo: Update contribution guidelines Refactor the contribution guidelines in the README and CONTRIBUTING files. Simplify the contribution guide in the README and move most of the complex stuff into CONTRIBUTING. Add an explicit commit message guidelines section to CONTRIBUTING. Keep all of the guidelines from Chris Beams except for the 72 character line limit (we don't follow that, nor does the Go team). Add three new guidelines: package prefix in subject, references in body, and encouragement of message body in general. Add a new section to CONTRIBUTING on using Git Remotes.
2016-03-12 23:35:06 +00:00
Enhance commit message guidelines
2016-11-04 18:37:41 +00:00
Please consider to 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.
hugo: Update contribution guidelines Refactor the contribution guidelines in the README and CONTRIBUTING files. Simplify the contribution guide in the README and move most of the complex stuff into CONTRIBUTING. Add an explicit commit message guidelines section to CONTRIBUTING. Keep all of the guidelines from Chris Beams except for the 72 character line limit (we don't follow that, nor does the Go team). Add three new guidelines: package prefix in subject, references in body, and encouragement of message body in general. Add a new section to CONTRIBUTING on using Git Remotes.
2016-03-12 23:35:06 +00:00
An example:
```text
tpl: Add custom index function
Add a custom index template function that deviates from the stdlib simply by not
returning an "index out of range" error if an array, slice or string index is
out of range. Instead, we just return nil values. This should help make the
new default function more useful for Hugo users.
Fixes #1949
```
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
2017-03-14 22:03:49 +00:00
### 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
docs: Fix CONTRIBUTING.md
2017-03-15 08:27:02 +00:00
```
go get github.com/kardianos/govendor
Update links in CONTRIBUTING.md due to the org transition
2017-06-13 17:37:30 +00:00
govendor get github.com/gohugoio/hugo
docs: Fix CONTRIBUTING.md
2017-03-15 08:27:02 +00:00
```
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
2017-03-14 22:03:49 +00:00
hugo: Update contribution guidelines Refactor the contribution guidelines in the README and CONTRIBUTING files. Simplify the contribution guide in the README and move most of the complex stuff into CONTRIBUTING. Add an explicit commit message guidelines section to CONTRIBUTING. Keep all of the guidelines from Chris Beams except for the 72 character line limit (we don't follow that, nor does the Go team). Add three new guidelines: package prefix in subject, references in body, and encouragement of message body in general. Add a new section to CONTRIBUTING on using Git Remotes.
2016-03-12 23:35:06 +00:00
### 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:
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
2017-03-14 22:03:49 +00:00
1. Fetch the Hugo sources as described above.
hugo: Update contribution guidelines Refactor the contribution guidelines in the README and CONTRIBUTING files. Simplify the contribution guide in the README and move most of the complex stuff into CONTRIBUTING. Add an explicit commit message guidelines section to CONTRIBUTING. Keep all of the guidelines from Chris Beams except for the 72 character line limit (we don't follow that, nor does the Go team). Add three new guidelines: package prefix in subject, references in body, and encouragement of message body in general. Add a new section to CONTRIBUTING on using Git Remotes.
2016-03-12 23:35:06 +00:00
1. Change to the Hugo source directory:
```
Update links in CONTRIBUTING.md due to the org transition
2017-06-13 17:37:30 +00:00
cd $HOME/go/src/github.com/gohugoio/hugo
hugo: Update contribution guidelines Refactor the contribution guidelines in the README and CONTRIBUTING files. Simplify the contribution guide in the README and move most of the complex stuff into CONTRIBUTING. Add an explicit commit message guidelines section to CONTRIBUTING. Keep all of the guidelines from Chris Beams except for the 72 character line limit (we don't follow that, nor does the Go team). Add three new guidelines: package prefix in subject, references in body, and encouragement of message body in general. Add a new section to CONTRIBUTING on using Git Remotes.
2016-03-12 23:35:06 +00:00
```
1. Create a new branch for your changes (the branch name is arbitrary):
```
git checkout -b iss1234
```
1. After making your changes, commit them to your new branch:
```
git commit -a -v
```
docs: Properly capitalize GitHub
2017-04-05 16:41:23 +00:00
1. Fork Hugo in GitHub.
hugo: Update contribution guidelines Refactor the contribution guidelines in the README and CONTRIBUTING files. Simplify the contribution guide in the README and move most of the complex stuff into CONTRIBUTING. Add an explicit commit message guidelines section to CONTRIBUTING. Keep all of the guidelines from Chris Beams except for the 72 character line limit (we don't follow that, nor does the Go team). Add three new guidelines: package prefix in subject, references in body, and encouragement of message body in general. Add a new section to CONTRIBUTING on using Git Remotes.
2016-03-12 23:35:06 +00:00
1. Add your fork as a new remote (the remote name, "fork" in this example, is arbitrary):
```
git remote add fork git://github.com/USERNAME/hugo.git
```
1. Push the changes to your new remote:
```
git push --set-upstream fork iss1234
```
1. You're now ready to submit a PR based upon the new branch in your forked repository.
### Build Hugo with Your Changes
```bash
Update links in CONTRIBUTING.md due to the org transition
2017-06-13 17:37:30 +00:00
cd $HOME/go/src/github.com/gohugoio/hugo
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
2017-03-14 22:03:49 +00:00
make hugo
# or to install in $HOME/go/bin:
make install
hugo: Update contribution guidelines Refactor the contribution guidelines in the README and CONTRIBUTING files. Simplify the contribution guide in the README and move most of the complex stuff into CONTRIBUTING. Add an explicit commit message guidelines section to CONTRIBUTING. Keep all of the guidelines from Chris Beams except for the 72 character line limit (we don't follow that, nor does the Go team). Add three new guidelines: package prefix in subject, references in body, and encouragement of message body in general. Add a new section to CONTRIBUTING on using Git Remotes.
2016-03-12 23:35:06 +00:00
```
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
2017-03-14 22:03:49 +00:00
### Updating the Hugo Sources
hugo: Update contribution guidelines Refactor the contribution guidelines in the README and CONTRIBUTING files. Simplify the contribution guide in the README and move most of the complex stuff into CONTRIBUTING. Add an explicit commit message guidelines section to CONTRIBUTING. Keep all of the guidelines from Chris Beams except for the 72 character line limit (we don't follow that, nor does the Go team). Add three new guidelines: package prefix in subject, references in body, and encouragement of message body in general. Add a new section to CONTRIBUTING on using Git Remotes.
2016-03-12 23:35:06 +00:00
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
2017-03-14 22:03:49 +00:00
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.
hugo: Update contribution guidelines Refactor the contribution guidelines in the README and CONTRIBUTING files. Simplify the contribution guide in the README and move most of the complex stuff into CONTRIBUTING. Add an explicit commit message guidelines section to CONTRIBUTING. Keep all of the guidelines from Chris Beams except for the 72 character line limit (we don't follow that, nor does the Go team). Add three new guidelines: package prefix in subject, references in body, and encouragement of message body in general. Add a new section to CONTRIBUTING on using Git Remotes.
2016-03-12 23:35:06 +00:00
docs: Fix CONTRIBUTING.md
2017-03-15 08:27:02 +00:00
```
git pull
make vendor
```
hugo: Update contribution guidelines Refactor the contribution guidelines in the README and CONTRIBUTING files. Simplify the contribution guide in the README and move most of the complex stuff into CONTRIBUTING. Add an explicit commit message guidelines section to CONTRIBUTING. Keep all of the guidelines from Chris Beams except for the 72 character line limit (we don't follow that, nor does the Go team). Add three new guidelines: package prefix in subject, references in body, and encouragement of message body in general. Add a new section to CONTRIBUTING on using Git Remotes.
2016-03-12 23:35:06 +00:00