github.com/graemephi/kahugo@v0.62.3-0.20211121071557-d78c0423784d/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    * [Fetching the Sources From GitHub](#fetching-the-sources-from-github)
    22    * [Building Hugo with Your Changes](#building-hugo-with-your-changes)
    23  
    24  ## Asking Support Questions
    25  
    26  We have an active [discussion forum](https://discourse.gohugo.io) where users and developers can ask questions.
    27  Please don't use the GitHub issue tracker to ask questions.
    28  
    29  ## Reporting Issues
    30  
    31  If you believe you have found a defect in Hugo or its documentation, use
    32  the GitHub issue tracker to report
    33  the problem to the Hugo maintainers. If you're not sure if it's a bug or not,
    34  start by asking in the [discussion forum](https://discourse.gohugo.io).
    35  When reporting the issue, please provide the version of Hugo in use (`hugo
    36  version`) and your operating system.
    37  
    38  - [Hugo Issues · gohugoio/hugo](https://github.com/gohugoio/hugo/issues)
    39  - [Hugo Documentation Issues · gohugoio/hugoDocs](https://github.com/gohugoio/hugoDocs/issues)
    40  - [Hugo Website Theme Issues · gohugoio/hugoThemesSite](https://github.com/gohugoio/hugoThemesSite/issues)
    41  
    42  ## Code Contribution
    43  
    44  Hugo has become a fully featured static site generator, so any new functionality must:
    45  
    46  * be useful to many.
    47  * fit naturally into _what Hugo does best._
    48  * strive not to break existing sites.
    49  * close or update an open [Hugo issue](https://github.com/gohugoio/hugo/issues)
    50  
    51  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.).
    52  
    53  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. 
    54  
    55  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.
    56  
    57  Note that we do not accept new features that require [CGO](https://github.com/golang/go/wiki/cgo).
    58  We have one exception to this rule which is LibSASS.
    59  
    60  **Bug fixes are, of course, always welcome.**
    61  
    62  ## Submitting Patches
    63  
    64  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.
    65  
    66  ### Code Contribution Guidelines
    67  
    68  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.
    69  
    70  To make the contribution process as seamless as possible, we ask for the following:
    71  
    72  * Go ahead and fork the project and make your changes.  We encourage pull requests to allow for review and discussion of code changes.
    73  * When you’re ready to create a pull request, be sure to:
    74      * Sign the [CLA](https://cla-assistant.io/gohugoio/hugo).
    75      * Have test cases for the new code. If you have questions about how to do this, please ask in your pull request.
    76      * Run `go fmt`.
    77      * Add documentation if you are adding new features or changing functionality.  The docs site lives in `/docs`.
    78      * Squash your commits into a single commit. `git rebase -i`. It’s okay to force update your pull request with `git push -f`.
    79      * 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.
    80      * Follow the **Git Commit Message Guidelines** below.
    81  
    82  ### Git Commit Message Guidelines
    83  
    84  This [blog article](http://chris.beams.io/posts/git-commit/) is a good resource for learning how to write good commit messages,
    85  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:
    86  *"Return error on wrong use of the Paginator"*, **NOT** *"returning some error."*
    87  
    88  Also, if your commit references one or more GitHub issues, always end your commit message body with *See #1234* or *Fixes #1234*.
    89  Replace *1234* with the GitHub issue ID. The last example will close the issue when the commit is merged into *master*.
    90  
    91  Sometimes it makes sense to prefix the commit message with the package name (or docs folder) all lowercased ending with a colon.
    92  That is fine, but the rest of the rules above apply.
    93  So it is "tpl: Add emojify template func", not "tpl: add emojify template func.", and "docs: Document emoji", not "doc: document emoji."
    94  
    95  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.
    96  
    97  An example:
    98  
    99  ```text
   100  tpl: Add custom index function
   101  
   102  Add a custom index template function that deviates from the stdlib simply by not
   103  returning an "index out of range" error if an array, slice or string index is
   104  out of range.  Instead, we just return nil values.  This should help make the
   105  new default function more useful for Hugo users.
   106  
   107  Fixes #1949
   108  ```
   109  
   110  ###  Fetching the Sources From GitHub
   111  
   112  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:
   113  
   114  ```bash
   115  mkdir $HOME/src
   116  cd $HOME/src
   117  git clone https://github.com/gohugoio/hugo.git
   118  cd hugo
   119  go install
   120  ```
   121  
   122  >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`.
   123  
   124  For some convenient build and test targets, you also will want to install Mage:
   125  
   126  ```bash
   127  go get github.com/magefile/mage
   128  ```
   129  
   130  Now, to make a change to Hugo's source:
   131  
   132  1. Create a new branch for your changes (the branch name is arbitrary):
   133  
   134      ```bash
   135      git checkout -b iss1234
   136      ```
   137  
   138  1. After making your changes, commit them to your new branch:
   139  
   140      ```bash
   141      git commit -a -v
   142      ```
   143  
   144  1. Fork Hugo in GitHub.
   145  
   146  1. Add your fork as a new remote (the remote name, "fork" in this example, is arbitrary):
   147  
   148      ```bash
   149      git remote add fork git@github.com:USERNAME/hugo.git
   150      ```
   151  
   152  1. Push the changes to your new remote:
   153  
   154      ```bash
   155      git push --set-upstream fork iss1234
   156      ```
   157  
   158  1. You're now ready to submit a PR based upon the new branch in your forked repository.
   159  
   160  ### Building Hugo with Your Changes
   161  
   162  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.
   163  
   164  ```bash
   165  cd $HOME/go/src/github.com/gohugoio/hugo
   166  ```
   167  
   168  To build Hugo:
   169  
   170  ```bash
   171  mage hugo
   172  ```
   173  
   174  To install hugo in `$HOME/go/bin`:
   175  
   176  ```bash
   177  mage install
   178  ```
   179  
   180  To run the tests:
   181  
   182  ```bash
   183  mage hugoRace
   184  mage -v check
   185  ```
   186  
   187  To list all available commands along with descriptions:
   188  
   189  ```bash
   190  mage -l
   191  ```
   192  
   193  **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:
   194  
   195  ```bash
   196  HUGO_BUILD_TAGS=extended mage install
   197  ````