hugo

Fork of github.com/gohugoio/hugo with reverse pagination support

git clone git://git.shimmy1996.com/hugo.git

development.md (18655B)

    1 ---
    2 title: Contribute to Hugo Development
    3 linktitle: Development
    4 description: Hugo relies heavily on contributions from the open source community.
    5 date: 2017-02-01
    6 publishdate: 2017-02-01
    7 lastmod: 2017-02-01
    8 categories: [contribute]
    9 keywords: [dev,open source]
   10 authors: [digitalcraftsman]
   11 menu:
   12   docs:
   13     parent: "contribute"
   14     weight: 10
   15 weight: 10
   16 sections_weight: 10
   17 draft: false
   18 toc: true
   19 ---
   20 
   21 ## Introduction
   22 
   23 Hugo is an open-source project and lives by the work of its [contributors][]. There are plenty of [open issues][issues], and we need your help to make Hugo even more awesome. You don't need to be a Go guru to contribute to the project's development.
   24 
   25 ## Assumptions
   26 
   27 This contribution guide takes a step-by-step approach in hopes of helping newcomers. Therefore, we only assume the following:
   28 
   29 * You are new to Git or open-source projects in general
   30 * You are a fan of Hugo and enthusiastic about contributing to the project
   31 
   32 {{% note "Additional Questions?" %}}
   33 If you're struggling at any point in this contribution guide, reach out to the Hugo community in [Hugo's Discussion forum](https://discourse.gohugo.io).
   34 {{% /note %}}
   35 
   36 ## Install Go
   37 
   38 The installation of Go should take only a few minutes. You have more than one option to get Go up and running on your machine.
   39 
   40 If you are having trouble following the installation guides for Go, check out [Go Bootcamp, which contains setups for every platform][gobootcamp] or reach out to the Hugo community in the [Hugo Discussion Forums][forums].
   41 
   42 ### Install Go From Source
   43 
   44 [Download the latest stable version of Go][godl] and follow the official [Go installation guide][goinstall].
   45 
   46 Once you're finished installing Go, let's confirm everything is working correctly. Open a terminal---or command line under Windows--and type the following:
   47 
   48 ```
   49 go version
   50 ```
   51 
   52 You should see something similar to the following written to the console. Note that the version here reflects the most recent version of Go as of the last update for this page:
   53 
   54 ```
   55 go version go1.12 darwin/amd64
   56 ```
   57 
   58 Next, make sure that you set up your `GOPATH` [as described in the installation guide][setupgopath].
   59 
   60 You can print the `GOPATH` with `echo $GOPATH`. You should see a non-empty string containing a valid path to your Go workspace; for example:
   61 
   62 ```
   63 /Users/<yourusername>/Code/go
   64 ```
   65 
   66 ### Install Go with Homebrew
   67 
   68 If you are a MacOS user and have [Homebrew](https://brew.sh/) installed on your machine, installing Go is as simple as the following command:
   69 
   70 {{< code file="install-go.sh" >}}
   71 brew install go
   72 {{< /code >}}
   73 
   74 ### Install Go via GVM
   75 
   76 More experienced users can use the [Go Version Manager][gvm] (GVM). GVM allows you to switch between different Go versions *on the same machine*. If you're a beginner, you probably don't need this feature. However, GVM makes it easy to upgrade to a new released Go version with just a few commands.
   77 
   78 GVM comes in especially handy if you follow the development of Hugo over a longer period of time. Future versions of Hugo will usually be compiled with the latest version of Go. Sooner or later, you will have to upgrade if you want to keep up.
   79 
   80 ## Create a GitHub Account
   81 
   82 If you're going to contribute code, you'll need to have an account on GitHub. Go to [www.github.com/join](https://github.com/join) and set up a personal account.
   83 
   84 ## Install Git on Your System
   85 
   86 You will need to have Git installed on your computer to contribute to Hugo development. Teaching Git is outside the scope of the Hugo docs, but if you're looking for an excellent reference to learn the basics of Git, we recommend the [Git book][gitbook] if you are not sure where to begin. We will include short explanations of the Git commands in this document.
   87 
   88 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.
   89 
   90 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.
   91 
   92 Move back to the terminal and check if Git is already installed. Type in `git version` and press enter. You can skip the rest of this section if the command returned a version number. Otherwise [download](https://git-scm.com/downloads) the latest version of Git and follow this [installation guide](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git).
   93 
   94 Finally, check again with `git version` if Git was installed successfully.
   95 
   96 ### Git Graphical Front Ends
   97 
   98 There are several [GUI clients](https://git-scm.com/downloads/guis) that help you to operate Git. Not all are available for all operating systems and maybe differ in their usage. Because of this we will document how to use the command line, since the commands are the same everywhere.
   99 
  100 ### Install Hub on Your System (Optional)
  101 
  102 Hub is a great tool for working with GitHub. The main site for it is [hub.github.com](https://hub.github.com/). Feel free to install this little Git wrapper.
  103 
  104 On a Mac, you can install [Hub](https://github.com/github/hub) using [Homebrew](https://brew.sh):
  105 
  106 ```
  107 brew install hub
  108 ```
  109 
  110 Now we'll create an [alias in Bash](https://tldp.org/LDP/abs/html/aliases.html) so that typing `git` actually runs `Hub`:
  111 
  112 ```
  113 echo "alias git='hub'" >> ~/.bash_profile
  114 ```
  115 
  116 Confirm the installation:
  117 
  118 ```
  119 git version 2.21.0
  120 hub version 2.10.0
  121 ```
  122 
  123 ## Set up your working copy
  124 
  125 You set up the working copy of the repository locally on your computer. Your local copy of the files is 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.
  126 
  127 ### Clone the repository
  128 
  129 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:
  130 
  131 > When you create a repository on GitHub, it exists as a remote repository. You can create a local clone of your repository on your computer and sync between the two locations.
  132 
  133 We're going to clone the [master Hugo repository](https://github.com/gohugoio/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.
  134 
  135 So, let's make a new directory and clone that master repository:
  136 
  137 ```
  138 mkdir $HOME/src
  139 cd $HOME/src
  140 git clone https://github.com/gohugoio/hugo.git
  141 ```
  142 
  143 > Since Hugo 0.48, Hugo uses the Go Modules support built into Go 1.11 to build. 
  144 > The easiest is to clone Hugo in a directory outside of GOPATH
  145 
  146 And then, install dependencies of Hugo by running the following in the cloned directory:
  147 
  148 ```
  149 cd $HOME/src/hugo
  150 go install
  151 ```
  152 
  153 
  154 Hugo relies on [mage](https://github.com/magefile/mage) for some convenient build and test targets. If you don't already have it, get it:
  155 
  156 ```
  157 go install github.com/magefile/mage@latest
  158 ```
  159 
  160 ### Fork the repository
  161 
  162 If you're not familiar with this term, GitHub's [help pages](https://help.github.com/articles/fork-a-repo/) provide again a simple explanation:
  163 
  164 > A fork is a copy of a repository. Forking a repository allows you to freely experiment with changes without affecting the original project.
  165 
  166 #### Fork by hand
  167 
  168 Open the [Hugo repository](https://github.com/gohugoio/hugo) on GitHub and click on the "Fork" button in the top right.
  169 
  170 ![Fork button](/images/contribute/development/forking-a-repository.png)
  171 
  172 Now open your fork repository on GitHub and copy the remote url of your fork. You can choose between HTTPS and SSH as protocol that Git should use for the following operations. HTTPS works always [if you're not sure](https://help.github.com/articles/which-remote-url-should-i-use/).
  173 
  174 ![Copy remote url](/images/contribute/development/copy-remote-url.png)
  175 
  176 Switch back to the terminal and move into the directory of the cloned master repository from the last step.
  177 
  178 ```
  179 cd $HOME/src/hugo
  180 ```
  181 
  182 Now Git needs to know that our fork exists by adding the copied remote url:
  183 
  184 ```
  185 git remote add <YOUR-GITHUB-USERNAME> <COPIED REMOTE-URL>
  186 ```
  187 
  188 #### Fork with Hub
  189 
  190 Alternatively, you can use the Git wrapper Hub. Hub makes forking a repository easy:
  191 
  192 ```
  193 git fork
  194 ```
  195 
  196 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.
  197 
  198 #### Trust, but verify
  199 
  200 Let's check if everything went right by listing all known remotes:
  201 
  202 ```
  203 git remote -v
  204 ```
  205 
  206 The output should look similar:
  207 
  208 ```
  209 digitalcraftsman    git@github.com:digitalcraftsman/hugo.git (fetch)
  210 digitalcraftsman    git@github.com:digitalcraftsman/hugo.git (push)
  211 origin  https://github.com/gohugoio/hugo (fetch)
  212 origin  https://github.com/gohugoio/hugo (push)
  213 ```
  214 
  215 ## The Hugo Git Contribution Workflow
  216 
  217 ### Create a new branch
  218 
  219 You should never develop against the "master" branch. The development team will not accept a pull request against that branch. Instead, create a descriptive named branch and work on it.
  220 
  221 First, you should always pull the latest changes from the master repository:
  222 
  223 ```
  224 git checkout master
  225 git pull
  226 ```
  227 
  228 Now we can create a new branch for your additions:
  229 
  230 ```
  231 git checkout -b <BRANCH-NAME>
  232 ```
  233 
  234 You can check on which branch you are with `git branch`. You should see a list of all local branches. The current branch is indicated with a little asterisk.
  235 
  236 ### Contribute to Documentation
  237 
  238 Perhaps you want to start contributing to the Hugo docs. If so, you can ignore most of the following steps and focus on the `/docs` directory within your newly cloned repository. You can change directories into the Hugo docs using `cd docs`.
  239 
  240 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 whenever you change content.
  241 
  242 We have developed a [separate Hugo documentation contribution guide][docscontrib] for more information on how the Hugo docs are built, organized, and improved by the generosity of people like you.
  243 
  244 ### Build Hugo
  245 
  246 While making changes in the codebase it's a good idea to build the binary to test them:
  247 
  248 ```
  249 mage hugo
  250 ```
  251 
  252 This command generates the binary file at the root of the repository.
  253 
  254 If you want to install the binary in `$GOPATH/bin`, run
  255 
  256 ```
  257 mage install
  258 ```
  259 
  260 ### Test 
  261 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`.
  262 
  263 Make sure the commands 
  264 
  265 ```
  266 mage -v check
  267 ```
  268 
  269 passes.
  270 
  271 ### Formatting 
  272 The Go code styleguide maybe is opinionated 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:
  273 
  274 ```
  275 mage fmt
  276 ```
  277 
  278 Once you made your additions commit your changes. Make sure that you follow our [code contribution guidelines](https://github.com/gohugoio/hugo/blob/master/CONTRIBUTING.md):
  279 
  280 ```
  281 # Add all changed files
  282 git add --all
  283 git commit --message "YOUR COMMIT MESSAGE"
  284 ```
  285 
  286 The commit message should describe what the commit does (e.g. add feature XYZ), not how it is done.
  287 
  288 ### Modify commits
  289 
  290 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.
  291 
  292 If you are unsure what a command does leave the commit as it is. We can fix your commits later in the pull request.
  293 
  294 #### Modify the last commit
  295 
  296 Let's say you want to modify the last commit message. Run the following command and replace the current message:
  297 
  298 ```
  299 git commit --amend -m"YOUR NEW COMMIT MESSAGE"
  300 ```
  301 
  302 Take a look at the commit log to see the change:
  303 
  304 ```
  305 git log
  306 # Exit with q
  307 ```
  308 
  309 After making the last commit you may have forgot something. There is no need to create a new commit. Just add the latest changes and merge them into the intended commit:
  310 
  311 ```
  312 git add --all
  313 git commit --amend
  314 ```
  315 
  316 #### Modify multiple commits
  317 
  318 {{% warning "Be Careful Modifying Multiple Commits"%}}
  319 Modifications such as those described in this section can have serious unintended consequences. Skip this section if you're not sure!
  320 {{% /warning %}}
  321 
  322 This is a bit more advanced. Git allows you to [rebase](https://git-scm.com/docs/git-rebase) commits interactively. In other words: it allows you to rewrite the commit history.
  323 
  324 ```
  325 git rebase --interactive @~6
  326 ```
  327 
  328 The `6` at the end of the command represents the number of commits that should be modified. An editor should open and present a list of last six commit messages:
  329 
  330 ```
  331 pick 80d02a1 tpl: Add hasPrefix to the template funcs' "smoke test"
  332 pick aaee038 tpl: Sort the smoke tests
  333 pick f0dbf2c tpl: Add the other test case for hasPrefix
  334 pick 911c35b Add "How to contribute to Hugo" tutorial
  335 pick 33c8973 Begin workflow
  336 pick 3502f2e Refactoring and typo fixes
  337 ```
  338 
  339 In the case above we should merge the last two commits in the commit of this tutorial (`Add "How to contribute to Hugo" tutorial`). You can "squash" commits, i.e. merge two or more commits into a single one.
  340 
  341 All operations are written before the commit message. Replace "pick" with an operation. In this case `squash` or `s` for short:
  342 
  343 ```
  344 pick 80d02a1 tpl: Add hasPrefix to the template funcs' "smoke test"
  345 pick aaee038 tpl: Sort the smoke tests
  346 pick f0dbf2c tpl: Add the other test case for hasPrefix
  347 pick 911c35b Add "How to contribute to Hugo" tutorial
  348 squash 33c8973 Begin workflow
  349 squash 3502f2e Refactoring and typo fixes
  350 ```
  351 
  352 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).
  353 
  354 You should end up with a similar setup:
  355 
  356 ```
  357 pick 80d02a1 tpl: Add hasPrefix to the template funcs' "smoke test"
  358 pick aaee038 tpl: Sort the smoke tests
  359 pick f0dbf2c tpl: Add the other test case for hasPrefix
  360 reword 911c35b Add "How to contribute to Hugo" tutorial
  361 squash 33c8973 Begin workflow
  362 squash 3502f2e Refactoring and typo fixes
  363 ```
  364 
  365 Close the editor. It should open again with a new tab. A text is instructing you to define a new commit message for the last two commits that should be merged (aka "squashed"). Save the file with <kbd>CTRL</kbd>+<kbd>S</kbd> and close the editor again.
  366 
  367 A last time a new tab opens. Enter a new commit message and save again. Your terminal should contain a status message. Hopefully this one:
  368 
  369 ```
  370 Successfully rebased and updated refs/heads/<BRANCHNAME>.
  371 ```
  372 
  373 Check the commit log if everything looks as expected. Should an error occur you can abort this rebase with `git rebase --abort`.
  374 
  375 ### Push commits
  376 
  377 To push our commits to the fork on GitHub we need to specify a destination. A destination is defined by the remote and a branch name. Earlier, the defined that the remote url of our fork is the same as our GitHub handle, in my case `digitalcraftsman`. The branch should have the same as our local one. This makes it easy to identify corresponding branches.
  378 
  379 ```
  380 git push --set-upstream <YOUR-GITHUB-USERNAME> <BRANCHNAME>
  381 ```
  382 
  383 Now Git knows the destination. Next time when you to push commits you just need to enter `git push`.
  384 
  385 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`.
  386 
  387 ## Open a pull request
  388 
  389 We made a lot of progress. Good work. In this step we finally open a pull request to submit our additions. Open the [Hugo master repository](https://github.com/gohugoio/hugo/) on GitHub in your browser.
  390 
  391 You should find a green button labeled with "New pull request". But GitHub is clever and probably suggests you a pull request like in the beige box below:
  392 
  393 ![Open a pull request](/images/contribute/development/open-pull-request.png)
  394 
  395 The new page summaries the most important information of your pull request. Scroll down and you find the additions of all your commits. Make sure everything looks as expected and click on "Create pull request".
  396 
  397 ### Accept the contributor license agreement
  398 
  399 Last but not least you should accept the contributor license agreement (CLA). A new comment should be added automatically to your pull request. Click on the yellow badge, accept the agreement and authenticate yourself with your GitHub account. It just takes a few clicks and only needs to be done once.
  400 
  401 ![Accept the CLA](/images/contribute/development/accept-cla.png)
  402 
  403 ### Automatic builds
  404 
  405 We use a GitHub Actions workflow to build and test. This is a matrix build across combinations of operating system (masOS, Windows, and Ubuntu) and Go versions. The workflow is triggered by the submission of a pull request. If you are a first-time contributor, the workflow requires approval from a project maintainer.
  406 
  407 ## Where to start?
  408 
  409 Thank you for reading through this contribution guide. Hopefully, we will see you again soon on GitHub. There are plenty of [open issues][issues] for you to help with.
  410 
  411 Feel free to [open an issue][newissue] if you think you found a bug or you have a new idea to improve Hugo. We are happy to hear from you.
  412 
  413 ## Additional References for Learning Git and Go
  414 
  415 * [Codecademy's Free "Learn Git" Course][codecademy] (Free)
  416 * [Code School and GitHub's "Try Git" Tutorial][trygit] (Free)
  417 * [The Git Book][gitbook] (Free)
  418 * [Go Bootcamp][gobootcamp]
  419 
  420 
  421 [codecademy]: https://www.codecademy.com/learn/learn-git
  422 [contributors]: https://github.com/gohugoio/hugo/graphs/contributors
  423 [docscontrib]: /contribute/documentation/
  424 [forums]: https://discourse.gohugo.io
  425 [gitbook]: https://git-scm.com/
  426 [gobootcamp]: https://www.golangbootcamp.com/book/get_setup
  427 [godl]: https://golang.org/dl/
  428 [goinstall]: https://golang.org/doc/install
  429 [gvm]: https://github.com/moovweb/gvm
  430 [issues]: https://github.com/gohugoio/hugo/issues
  431 [newissue]: https://github.com/gohugoio/hugo/issues/new
  432 [releases]: /getting-started/
  433 [setupgopath]: https://golang.org/doc/code.html#Workspaces
  434 [trygit]: https://try.github.io/levels/1/challenges/1