Update and expand information about building Gitea

docs/content/doc/advanced/hacking-on-gitea.en-us.md

@@ -15,41 +15,280 @@ menu:
 
 # Hacking on Gitea
 
-Familiarity with the existing [installation instructions](https://golang.org/doc/install)
-is required for this section.
+## Installing go and setting the GOPATH
 
-To contribute to Gitea, fork the project and work on the `master` branch.
+You should [install go](https://golang.org/doc/install) and set up your go
+environment correctly. In particular, it is recommended to set the `$GOPATH`
+environment variable and to add the go bin directory or directories
+`${GOPATH//://bin:}/bin` to the `$PATH`. See the Go wiki entry for
+[GOPATH](https://github.com/golang/go/wiki/GOPATH).
 
-Some internal packages are referenced using their respective Github URL. This can
-become problematic. To "trick" the Go tool into thinking this is a clone from the
-official repository, download the source code using "go get" and follow these instructions.
+You will also need make.
+<a href='{{< relref "doc/advanced/make.en-us.md" >}}'>(See here how to get Make)</a>
 
-```
+**Note**: When executing make tasks that require external tools, like
+`make misspell-check`, Gitea will automatically download and build these as
+necessary. To be able to use these you must have the `"$GOPATH"/bin` directory
+on the executable path. If you don't add the go bin directory to the
+executable path you will have to manage this yourself.
+
+**Note 2**: Go version 1.9 or higher is required, however it is important
+to note that our continuous integration will check that the formatting of the
+source code is not changed by `gofmt` using `make fmt-check`. Unfortunately,
+the results of `gofmt` can differ by the version of `go` it is therefore
+recommended to install the version of go that our continuous integration is
+running. At the time of writing this is Go version 1.11, however this can be
+checked by looking at the
+[master `.drone.yml`](https://github.com/go-gitea/gitea/blob/master/.drone.yml)
+(At the time of writing
+[line 67](https://github.com/go-gitea/gitea/blob/8917d66571a95f3da232a0c27bc1300210d10fde/.drone.yml#L67)
+is the relevant line - however this may change.)
+
+## Downloading and cloning the Gitea source code
+
+Go is quite opinionated about where it expects its source code, and simply
+cloning the Gitea repository to an arbitrary path is likely to lead to
+problems - the fixing of which is out of scope for this document. Further some
+internal packages are referenced using their respective Github URL and at
+present we use `vendor/` directories.
+
+The recommended method of obtaining the source code is by using the `go get` command:
+
+```bash
 go get -d code.gitea.io/gitea
+cd "$GOPATH/src/code.gitea.io/gitea"
 ```
 
-Fork the [Gitea repository](https://github.com/go-gitea/gitea) on GitHub, it should
-then be possible to switch the source directory on the command line.
+This will clone the Gitea source code to: `"$GOPATH/src/code.gitea.io/gitea"`, or if `$GOPATH`
+is not set `"$HOME/go/src/code.gitea.io/gitea"`.
 
+## Forking Gitea
+
+As stated above, you cannot clone Gitea to an arbitrary path. Download the master Gitea source
+code as above. Then fork the [Gitea repository](https://github.com/go-gitea/gitea) on GitHub,
+and either switch the git remote origin for your fork or add your fork as another remote:
+
+```bash
+# Rename original Gitea origin to upstream
+cd "$GOPATH/src/code.gitea.io/gitea"
+git remote rename origin upstream
+git remote add origin "[email protected]:$GITHUB_USERNAME/gitea.git"
+git fetch --all --prune
 ```
-cd $GOPATH/src/code.gitea.io/gitea
+
+or:
+
+```bash
+# Add new remote for our fork
+cd "$GOPATH/src/code.gitea.io/gitea"
+git remote add "$FORK_NAME" "[email protected]:$GITHUB_USERNAME/gitea.git"
+git fetch --all --prune
 ```
 
 To be able to create pull requests, the forked repository should be added as a remote
 to the Gitea sources, otherwise changes can't be pushed.
 
+## Building Gitea (Basic)
+
+Take a look at our
+<a href='{{< relref "doc/installation/from-source.en-us.md" >}}'>instructions</a>
+for <a href='{{< relref "doc/installation/from-source.en-us.md" >}}'>building
+from source</a>.
+
+The simplest recommended way to build from source is:
+
+```bash
+TAGS="bindata sqlite sqlite_unlock_notify" make generate build
 ```
-git remote rename origin upstream
-git remote add origin [email protected]:<USERNAME>/gitea.git
-git fetch --all --prune
+
+However, there are a number of additional make tasks you should be aware of.
+These are documented below but you can look at our
+[`Makefile`](https://github.com/go-gitea/gitea/blob/master/Makefile) for more,
+and look at our
+[`.drone.yml`](https://github.com/go-gitea/gitea/blob/master/.drone.yml) to see
+how our continuous integration works.
+
+### Formatting, linting, vetting and spell-check
+
+Our continous integration will reject PRs that are not properly formatted, fail
+linting, vet or spell-check.
+
+You should format your code with `go fmt` using:
+
+```bash
+make fmt
+```
+
+and can test whether your changes would match the results with:
+
+```bash
+make fmt-check # which runs make fmt internally
+```
+
+**Note**: The results of `go fmt` are dependent on the version of `go` present.
+You should run the same version of go that is on the continuous integration
+server as mentioned above. `make fmt-check` will only check if your `go` would
+format differently - this may be different from the CI server version.
+
+You should lint, vet and spell-check with:
+
+```bash
+make vet lint misspell-check
+```
+
+### Updating the stylesheets
+
+At present we use [less](http://lesscss.org/) and [postcss](https://postcss.org) to generate our stylesheets. Do
+**not** edit the files in `public/css/` directly as they are generated from
+`lessc` from the files in `public/less/`.
+
+If you wish to work on the stylesheets you will need to install `lessc` the
+less compiler and `postcss`. The recommended way to do this is using `npm install`:
+
+```bash
+cd "$GOPATH/src/code.gitea.io/gitea"
+npm install
+```
+
+You can then edit the less stylesheets and regenerate the stylesheets using:
+
+```bash
+make generate-stylesheets
+```
+
+You should commit both the changes to the css and the less files when making
+PRs.
+
+### Updating the API
+
+When creating new API routes or modifying existing API routes you **MUST**
+update and/or create [Swagger](https://swagger.io/docs/specification/2-0/what-is-swagger/)
+documentation for these using [go-swagger](https://goswagger.io/) comments.
+The structure of these comments is described in the [specification](https://goswagger.io/use/spec.html#annotation-syntax).
+If you want more information about the Swagger structure you can look at the
+[Swagger 2.0 Documentation](https://swagger.io/docs/specification/2-0/basic-structure/)
+or compare with a previous PR adding a new API endpoint e.g. [PR #5483](https://github.com/go-gitea/gitea/pull/5843/files#diff-2e0a7b644cf31e1c8ef7d76b444fe3aaR20)
+
+You should be careful not to break the API for downstream users which depend
+on a stable API. In general this means additions are acceptable, but deletions
+or fundamental changes of API will be rejected.
+
+Once you have created or changed an API endpoint, please regenerate the Swagger
+documentation using:
+
+```bash
+make generate-swagger
+```
+
+You should validate your generated Swagger file and spell-check it with:
+
+```bash
+make swagger-validate mispell-check
+```
+
+You should commit the changed swagger JSON file. The continous integration
+server will check that this has been done using:
+
+```bash
+make swagger-check
+```
+
+**Note**: Please note you should use the Swagger 2.0 documentation, not the
+OpenAPI 3 documentation.
+
+### Creating new configuration options
+
+When creating new configuration options, it is not enough to add them to the
+`modules/setting` files. You should add information to `custom/conf/app.ini`
+and to the
+<a href='{{ relref "doc/advanced/config-cheat-sheet.en-us.md"}}'>configuration cheat sheet</a>
+found in `docs/content/doc/advanced/config-cheat-sheet.en-us.md`
+
+### Changing the logo
+
+When changing the Gitea logo svg. You will need to run and commit the results
+of:
+
+```bash
+make generate-images
+```
+
+This will create the necessary Gitea favicon and others.
+
+### Database Migrations
+
+If you make breaking changes to any of the database persisted structs in the
+`models/` directory you will need to make a new migration. These can be found
+in `models/migrations/`. You can ensure that your migrations work for the main
+database types using:
+
+```bash
+make test-sqlite-migration # with sqlite switched for the appropriate database
 ```
 
-This should provide a working development environment for Gitea. Take a look at
-the `Makefile` to get an overview about the available tasks. The most common tasks
-should be `make test` which will start our test environment and `make build` which
-will build a `gitea` binary into the working directory. Writing test cases is not
-mandatory to contribute, but it is highly encouraged and helps developers sleep
-at night.
+## Testing
+
+There are two types of test run by Gitea: Unit tests and Integration Tests.
+
+```bash
+TAGS="bindata sqlite sqlite_unlock_notify" make test # Runs the unit tests
+```
+
+Unit tests will not and cannot completely test Gitea alone. Therefore we
+have written integration tests, however, these are database dependent.
+
+```bash
+TAGS="bindata sqlite sqlite_unlock_notify" make generate build test-sqlite
+```
+
+Will run the integration tests in an sqlite environment. Other database tests
+are available however may need adjustment for local environment. 
+
+Look at
+[`integrations/README.md`](https://github.com/go-gitea/gitea/blob/master/integrations/README.md)
+for more information and how to run a single test.
+
+Our continuous integration will test the code passes its unit tests and that
+all supported databases will pass integration test in a docker environment.
+Migration from several recent versions of gitea will also be tested.
+
+Please submit your PR with additional tests and integration tests as
+appropriate.
+
+## Documentation for the website
+
+Documentation for the website is found in `docs/`. If you change this you
+can test your changes to ensure that they pass continuous integration using:
+
+```bash
+cd "$GOPATH/src/code.gitea.io/gitea/docs"
+make trans-copy clean build
+```
+
+You will require a copy of [Hugo](https://gohugo.io/) to run this task. Please
+note this may generate a number of untracked git objects which will need to
+be cleaned up.
+
+## Visual Studio Code
+
+A `launch.json` and `tasks.json` are provided within `contrib/ide/vscode` for
+Visual Studio Code. Look at
+[`contrib/ide/README.md`](https://github.com/go-gitea/gitea/blob/master/contrib/ide/README.md)
+for more information.
+
+## Submitting PRs
+
+Once you're happy with your changes, push them up and open a pull request. It
+is recommended that you allow Gitea Managers and Owners to modify your PR
+branches as we will need to update it to master before merging and/or may be
+able to help fix issues directly.
+
+Any PR requires two approvals from the Gitea maintainers and needs to pass the
+continous integration. Take a look at our
+[`CONTRIBUTING.md`](https://github.com/go-gitea/gitea/blob/master/CONTRIBUTING.md)
+document.
+
+If you need more help pop on to [Discord](https://discord.gg/gitea) #Develop
+and chat there.
 
-That's it! You are ready to hack on Gitea. Test changes, push them to the repository,
-and open a pull request.
+That's it! You are ready to hack on Gitea.