- ---
- date: "2016-12-01T16:00:00+02:00"
- title: "Hacking on Gitea"
- slug: "hacking-on-gitea"
- weight: 10
- toc: false
- draft: false
- menu:
- sidebar:
- parent: "advanced"
- name: "Hacking on Gitea"
- weight: 10
- identifier: "hacking-on-gitea"
- ---
-
- # Hacking on Gitea
-
- ## Installing go and setting the GOPATH
-
- 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).
-
- 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.11 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.12; 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 - but 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"
- ```
-
- 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 "git@github.com:$GITHUB_USERNAME/gitea.git"
- git fetch --all --prune
- ```
-
- or:
-
- ```bash
- # Add new remote for our fork
- cd "$GOPATH/src/code.gitea.io/gitea"
- git remote add "$FORK_NAME" "git@github.com:$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
- ```
-
- 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 CSS
-
- To generate the CSS, you will need [Node.js](https://nodejs.org/) 8.0 or greater with npm. At present we use [less](http://lesscss.org/) and [postcss](https://postcss.org) to generate our CSS. Do **not** edit the files in `public/css` directly, as they are generated from `lessc` from the files in `public/less`.
-
- Edit files in `public/less`, run the linter, regenerate the CSS and commit all changed files:
-
- ```bash
- make css
- ```
-
- ### Updating JS
-
- To run the JavaScript linter you will need [Node.js](https://nodejs.org/) 8.0 or greater with npm. Edit files in `public/js` and run the linter:
-
- ```bash
- make js
- ```
-
- ### 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 to the 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
- ```
-
- ## 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 but may need adjustment to the 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.
|