2017-11-26 21:44:32 +00:00
---
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
2019-02-12 16:22:01 +00:00
## Installing go and setting the GOPATH
2017-11-26 21:44:32 +00:00
2019-02-12 16:22:01 +00:00
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 ).
2018-01-08 22:48:42 +00:00
2019-12-05 03:41:38 +00:00
Next, [install Node.js with npm ](https://nodejs.org/en/download/ ) which is
required to build the JavaScript and CSS files. The minimum supported Node.js
2020-03-05 22:36:22 +00:00
version is {{< min-node-version > }} and the latest LTS version is recommended.
2019-12-05 03:41:38 +00:00
2019-02-12 16:22:01 +00:00
You will also need make.
< a href = '{{< relref "doc/advanced/make.en-us.md" >}}' > (See here how to get Make)< / a >
2017-11-26 21:44:32 +00:00
2019-02-12 16:22:01 +00:00
**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.
2020-03-05 00:37:19 +00:00
**Note 2**: Go version {{< min-go-version > }} or higher is required; however, it is important
2019-02-12 16:22:01 +00:00
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,
2019-03-09 21:15:45 +00:00
the results of `gofmt` can differ by the version of `go` . It is therefore
2020-03-05 00:37:19 +00:00
recommended to install the version of Go that our continuous integration is
running. As of last update, it should be Go version {{< go-version > }}.
2019-02-12 16:22:01 +00:00
## Downloading and cloning the Gitea source code
2020-01-29 02:30:02 +00:00
The recommended method of obtaining the source code is by using `git clone` .
2019-02-12 16:22:01 +00:00
```bash
2020-01-29 02:30:02 +00:00
git clone https://github.com/go-gitea/gitea
2017-11-26 21:44:32 +00:00
```
2020-01-29 02:30:02 +00:00
(Since the advent of go modules, it is no longer necessary to build go projects
from within the `$GOPATH` , hence the `go get` approach is no longer recommended.)
2017-11-26 21:44:32 +00:00
2019-02-12 16:22:01 +00:00
## Forking Gitea
2020-01-29 02:30:02 +00:00
Download the master Gitea source code as above. Then, fork the
[Gitea repository ](https://github.com/go-gitea/gitea ) on GitHub,
2019-02-12 16:22:01 +00:00
and either switch the git remote origin for your fork or add your fork as another remote:
```bash
# Rename original Gitea origin to upstream
git remote rename origin upstream
git remote add origin "git@github.com:$GITHUB_USERNAME/gitea.git"
git fetch --all --prune
2017-11-26 21:44:32 +00:00
```
2019-02-12 16:22:01 +00:00
or:
```bash
# Add new remote for our fork
git remote add "$FORK_NAME" "git@github.com:$GITHUB_USERNAME/gitea.git"
git fetch --all --prune
2017-11-26 21:44:32 +00:00
```
2018-01-08 22:48:42 +00:00
To be able to create pull requests, the forked repository should be added as a remote
2019-03-09 21:15:45 +00:00
to the Gitea sources. Otherwise, changes can't be pushed.
2017-11-26 21:44:32 +00:00
2019-02-12 16:22:01 +00:00
## 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
2019-12-05 03:41:38 +00:00
TAGS="bindata sqlite sqlite_unlock_notify" make build
2017-11-26 21:44:32 +00:00
```
2019-02-12 16:22:01 +00:00
2020-05-09 22:11:30 +00:00
See `make help` for all available `make` tasks. Also see [`.drone.yml` ](https://github.com/go-gitea/gitea/blob/master/.drone.yml ) to see how our continuous integration works.
2019-02-12 16:22:01 +00:00
2019-09-29 20:36:52 +00:00
### Formatting, code analysis and spell check
2019-02-12 16:22:01 +00:00
2020-01-29 02:30:02 +00:00
Our continuous integration will reject PRs that are not properly formatted, fail
2019-09-29 20:36:52 +00:00
code analysis or spell check.
2019-02-12 16:22:01 +00:00
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.
2019-09-29 20:36:52 +00:00
You should run revive, vet and spell-check on the code with:
2019-02-12 16:22:01 +00:00
```bash
2019-09-29 20:36:52 +00:00
make revive vet misspell-check
2019-02-12 16:22:01 +00:00
```
2020-01-28 07:30:39 +00:00
### Working on JS and CSS
2019-05-16 05:57:47 +00:00
2020-04-12 03:50:59 +00:00
For simple changes, edit files in `web_src` , run the build and start the server to test:
2019-02-12 16:22:01 +00:00
```bash
2020-04-12 03:50:59 +00:00
make build & & ./gitea
```
2020-05-09 22:11:30 +00:00
`make build` runs both `make frontend` and `make backend` which can be run individually as well as long as the `bindata` tag is not used (which compiles frontend files into the binary).
For more involved changes use the `watch-frontend` task to continuously rebuild files when their sources change. The `bindata` tag must be absent. First, build and run the backend:
2020-04-12 03:50:59 +00:00
```bash
make backend & & ./gitea
```
With the backend running, open another terminal and run:
```bash
make watch-frontend
```
Before committing, make sure the linters pass:
```bash
make lint-frontend
2019-02-12 16:22:01 +00:00
```
2020-05-09 22:11:30 +00:00
Note: When working on frontend code, set `USE_SERVICE_WORKER` to `false` in `app.ini` to prevent undesirable caching of frontend assets.
2019-05-16 05:57:47 +00:00
2020-07-12 09:10:56 +00:00
### Building and adding SVGs
SVG icons are built using the `make svg` target which compiles the icon sources defined in `build/generate-svg.js` into the output directory `public/img/svg` . Custom icons can be added in the `web_src/svg` directory.
2020-01-28 07:30:39 +00:00
### Building Images
2019-05-16 05:57:47 +00:00
2020-01-28 07:30:39 +00:00
To build the images, ImageMagick, `inkscape` and `zopflipng` binaries must be available in
your `PATH` to run `make generate-images` .
2019-11-21 20:06:23 +00:00
2019-02-12 16:22:01 +00:00
### Updating the API
2019-03-09 21:15:45 +00:00
When creating new API routes or modifying existing API routes, you **MUST**
2019-02-12 16:22:01 +00:00
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 ).
2019-03-09 21:15:45 +00:00
If you want more information about the Swagger structure, you can look at the
2019-02-12 16:22:01 +00:00
[Swagger 2.0 Documentation ](https://swagger.io/docs/specification/2-0/basic-structure/ )
2019-03-09 21:15:45 +00:00
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 )
2019-02-12 16:22:01 +00:00
You should be careful not to break the API for downstream users which depend
2019-03-09 21:15:45 +00:00
on a stable API. In general, this means additions are acceptable, but deletions
or fundamental changes to the API will be rejected.
2019-02-12 16:22:01 +00:00
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
2019-09-24 18:29:11 +00:00
make swagger-validate misspell-check
2019-02-12 16:22:01 +00:00
```
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
2019-06-18 02:57:48 +00:00
< a href = '{{< relref "doc/advanced/config-cheat-sheet.en-us.md" >}}' > configuration cheat sheet< / a >
2019-02-12 16:22:01 +00:00
found in `docs/content/doc/advanced/config-cheat-sheet.en-us.md`
### Changing the logo
2019-03-09 21:15:45 +00:00
When changing the Gitea logo SVG, you will need to run and commit the results
2019-02-12 16:22:01 +00:00
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
2019-03-09 21:15:45 +00:00
`models/` directory, you will need to make a new migration. These can be found
2019-02-12 16:22:01 +00:00
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
2017-11-26 21:44:32 +00:00
```
2019-02-12 16:22:01 +00:00
## 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
```
2019-03-09 21:15:45 +00:00
Unit tests will not and cannot completely test Gitea alone. Therefore, we
have written integration tests; however, these are database dependent.
2019-02-12 16:22:01 +00:00
```bash
2019-12-05 03:41:38 +00:00
TAGS="bindata sqlite sqlite_unlock_notify" make build test-sqlite
2019-02-12 16:22:01 +00:00
```
2020-01-29 02:30:02 +00:00
will run the integration tests in an sqlite environment. Integration tests
require `git lfs` to be installed. Other database tests are available but
may need adjustment to the local environment.
2019-02-12 16:22:01 +00:00
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
2019-03-09 21:15:45 +00:00
all supported databases will pass integration test in a Docker environment.
Migration from several recent versions of Gitea will also be tested.
2019-02-12 16:22:01 +00:00
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
2020-01-29 02:30:02 +00:00
# from the docs directory within Gitea
2019-02-12 16:22:01 +00:00
make trans-copy clean build
```
You will require a copy of [Hugo ](https://gohugo.io/ ) to run this task. Please
2019-03-09 21:15:45 +00:00
note: this may generate a number of untracked git objects, which will need to
2019-02-12 16:22:01 +00:00
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.
2017-11-26 21:44:32 +00:00
2019-02-12 16:22:01 +00:00
That's it! You are ready to hack on Gitea.