2017-11-26 14:44:32 -07:00
---
date: "2016-12-01T16:00:00+02:00"
title: "Hacking on Gitea"
slug: "hacking-on-gitea"
2023-07-25 22:53:13 -06:00
sidebar_position: 10
2017-11-26 14:44:32 -07:00
toc: false
draft: false
Refactor docs (#23752)
This was intended to be a small followup for
https://github.com/go-gitea/gitea/pull/23712, but...here we are.
1. Our docs currently use `slug` as the entire URL, which makes
refactoring tricky (see https://github.com/go-gitea/gitea/pull/23712).
Instead, this PR attempts to make future refactoring easier by using
slugs as an extension of the section. (Hugo terminology)
- What the above boils down to is this PR attempts to use directory
organization as URL management. e.g. `usage/comparison.en-us.md` ->
`en-us/usage/comparison/`, `usage/packages/overview.en-us.md` ->
`en-us/usage/packages/overview/`
- Technically we could even remove `slug`, as Hugo defaults to using
filename, however at least with this PR it means `slug` only needs to be
the name for the **current file** rather than an entire URL
2. This PR adds appropriate aliases (redirects) for pages, so anything
on the internet that links to our docs should hopefully not break.
3. A minor nit I've had for a while, renaming `seek-help` to `support`.
It's a minor thing, but `seek-help` has a strange connotation to it.
4. The commits are split such that you can review the first which is the
"actual" change, and the second is added redirects so that the first
doesn't break links elsewhere.
---------
Signed-off-by: jolheiser <john.olheiser@gmail.com>
2023-04-27 21:33:41 -06:00
aliases:
- /en-us/hacking-on-gitea
2017-11-26 14:44:32 -07:00
menu:
sidebar:
2023-03-23 09:18:24 -06:00
parent: "development"
2017-11-26 14:44:32 -07:00
name: "Hacking on Gitea"
2023-07-25 22:53:13 -06:00
sidebar_position: 10
2017-11-26 14:44:32 -07:00
identifier: "hacking-on-gitea"
---
# Hacking on Gitea
2022-10-12 10:17:04 -06:00
## Quickstart
To get a quick working development environment you could use Gitpod.
2022-10-17 19:55:57 -06:00
[![Open in Gitpod ](/open-in-gitpod.svg )](https://gitpod.io/#https://github.com/go-gitea/gitea)
2022-10-12 10:17:04 -06:00
2020-09-03 04:11:23 -06:00
## Installing go
2017-11-26 14:44:32 -07:00
2019-02-12 09:22:01 -07:00
You should [install go ](https://golang.org/doc/install ) and set up your go
2020-09-03 04:11:23 -06:00
environment correctly.
2018-01-08 15:48:42 -07:00
2019-12-04 20:41:38 -07: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
2023-07-25 22:53:13 -06:00
version is @minNodeVersion @ and the latest LTS version is recommended.
2019-12-04 20:41:38 -07:00
2019-02-12 09:22:01 -07:00
**Note**: When executing make tasks that require external tools, like
2022-01-12 19:58:46 -07:00
`make watch-backend` , Gitea will automatically download and build these as
2019-02-12 09:22:01 -07:00
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.
2023-07-25 22:53:13 -06:00
**Note 2**: Go version @minGoVersion @ or higher is required.
2022-07-27 19:22:47 -06:00
Gitea uses `gofmt` to format source code. However, the results of
2022-01-12 19:58:46 -07:00
`gofmt` can differ by the version of `go` . Therefore it is
2020-03-04 17:37:19 -07:00
recommended to install the version of Go that our continuous integration is
2023-07-25 22:53:13 -06:00
running. As of last update, the Go version should be @goVersion @.
2019-02-12 09:22:01 -07:00
2023-06-14 12:17:58 -06:00
To lint the template files, ensure [Python ](https://www.python.org/ ) and
[Poetry ](https://python-poetry.org/ ) are installed.
2020-10-23 09:59:45 -06:00
## Installing Make
Gitea makes heavy use of Make to automate tasks and improve development. This
guide covers how to install Make.
2020-12-07 21:52:26 -07:00
### On Linux
2020-10-23 09:59:45 -06:00
Install with the package manager.
On Ubuntu/Debian:
```bash
sudo apt-get install make
```
On Fedora/RHEL/CentOS:
```bash
sudo yum install make
```
2020-12-07 21:52:26 -07:00
### On Windows
2020-10-23 09:59:45 -06:00
One of these three distributions of Make will run on Windows:
- [Single binary build ](http://www.equation.com/servlet/equation.cmd?fa=make ). Copy somewhere and add to `PATH` .
2021-12-26 08:27:18 -07:00
- [32-bits version ](http://www.equation.com/ftpdir/make/32/make.exe )
- [64-bits version ](http://www.equation.com/ftpdir/make/64/make.exe )
- [MinGW-w64 ](https://www.mingw-w64.org ) / [MSYS2 ](https://www.msys2.org/ ).
2022-07-27 19:22:47 -06:00
- MSYS2 is a collection of tools and libraries providing you with an easy-to-use environment for building, installing and running native Windows software, it includes MinGW-w64.
2021-12-26 08:27:18 -07:00
- In MingGW-w64, the binary is called `mingw32-make.exe` instead of `make.exe` . Add the `bin` folder to `PATH` .
- In MSYS2, you can use `make` directly. See [MSYS2 Porting ](https://www.msys2.org/wiki/Porting/ ).
2021-12-31 07:21:11 -07:00
- To compile Gitea with CGO_ENABLED (eg: SQLite3), you might need to use [tdm-gcc ](https://jmeubank.github.io/tdm-gcc/ ) instead of MSYS2 gcc, because MSYS2 gcc headers lack some Windows-only CRT functions like `_beginthread` .
2020-10-23 09:59:45 -06:00
- [Chocolatey package ](https://chocolatey.org/packages/make ). Run `choco install make`
2021-12-23 20:56:57 -07:00
**Note**: If you are attempting to build using make with Windows Command Prompt, you may run into issues. The above prompts (Git bash, or MinGW) are recommended, however if you only have command prompt (or potentially PowerShell) you can set environment variables using the [set ](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/set_1 ) command, e.g. `set TAGS=bindata` .
2021-06-23 13:57:56 -06:00
2019-02-12 09:22:01 -07:00
## Downloading and cloning the Gitea source code
2020-01-28 19:30:02 -07:00
The recommended method of obtaining the source code is by using `git clone` .
2019-02-12 09:22:01 -07:00
```bash
2020-01-28 19:30:02 -07:00
git clone https://github.com/go-gitea/gitea
2017-11-26 14:44:32 -07:00
```
2020-01-28 19:30:02 -07: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 14:44:32 -07:00
2019-02-12 09:22:01 -07:00
## Forking Gitea
2021-05-04 10:16:23 -06:00
Download the main Gitea source code as above. Then, fork the
2020-01-28 19:30:02 -07:00
[Gitea repository ](https://github.com/go-gitea/gitea ) on GitHub,
2019-02-12 09:22:01 -07: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 14:44:32 -07:00
```
2019-02-12 09:22:01 -07: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 14:44:32 -07:00
```
2018-01-08 15:48:42 -07:00
To be able to create pull requests, the forked repository should be added as a remote
2019-03-09 14:15:45 -07:00
to the Gitea sources. Otherwise, changes can't be pushed.
2017-11-26 14:44:32 -07:00
2019-02-12 09:22:01 -07:00
## Building Gitea (Basic)
Take a look at our
2023-07-25 22:53:13 -06:00
[instructions ](installation/from-source.md )
for [building from source ](installation/from-source.md ).
2019-02-12 09:22:01 -07:00
The simplest recommended way to build from source is:
```bash
2019-12-04 20:41:38 -07:00
TAGS="bindata sqlite sqlite_unlock_notify" make build
2017-11-26 14:44:32 -07:00
```
2019-02-12 09:22:01 -07:00
2020-07-27 12:05:42 -06:00
The `build` target will execute both `frontend` and `backend` sub-targets. If the `bindata` tag is present, the frontend files will be compiled into the binary. It is recommended to leave out the tag when doing frontend development so that changes will be reflected.
2021-05-04 10:16:23 -06:00
See `make help` for all available `make` targets. Also see [`.drone.yml` ](https://github.com/go-gitea/gitea/blob/main/.drone.yml ) to see how our continuous integration works.
2020-07-27 12:05:42 -06:00
## Building continuously
2021-05-18 11:35:59 -06:00
To run and continuously rebuild when source files change:
2020-07-27 12:05:42 -06:00
2020-12-08 23:47:06 -07:00
```bash
2021-10-14 20:35:26 -06:00
# for both frontend and backend
2020-09-04 18:55:06 -06:00
make watch
2021-10-14 20:35:26 -06:00
# or: watch frontend files (html/js/css) only
make watch-frontend
# or: watch backend files (go) only
make watch-backend
2020-12-08 23:47:06 -07:00
```
2020-07-27 12:05:42 -06:00
On macOS, watching all backend source files may hit the default open files limit which can be increased via `ulimit -n 12288` for the current shell or in your shell startup file for all future shells.
2019-02-12 09:22:01 -07:00
2019-09-29 14:36:52 -06:00
### Formatting, code analysis and spell check
2019-02-12 09:22:01 -07:00
2022-01-12 19:58:46 -07:00
Our continuous integration will reject PRs that fail the code linters (including format check, code analysis and spell check).
2019-02-12 09:22:01 -07:00
2022-01-12 19:58:46 -07:00
You should format your code:
2019-02-12 09:22:01 -07:00
```bash
make fmt
```
2022-01-12 19:58:46 -07:00
and lint the source code:
2019-02-12 09:22:01 -07:00
```bash
2022-01-12 19:58:46 -07:00
# lint both frontend and backend code
make lint
# lint only backend code
make lint-backend
2019-02-12 09:22:01 -07:00
```
2022-01-12 19:58:46 -07:00
**Note**: The results of `gofmt` are dependent on the version of `go` present.
2019-02-12 09:22:01 -07:00
You should run the same version of go that is on the continuous integration
2022-01-12 19:58:46 -07:00
server as mentioned above.
2019-02-12 09:22:01 -07:00
2020-01-28 00:30:39 -07:00
### Working on JS and CSS
2019-05-15 23:57:47 -06:00
2023-07-25 22:53:13 -06:00
Frontend development should follow [Guidelines for Frontend Development ](contributing/guidelines-frontend.md )
2021-10-14 20:35:26 -06:00
To build with frontend resources, either use the `watch-frontend` target mentioned above or just build once:
2019-02-12 09:22:01 -07:00
```bash
2020-04-11 21:50:59 -06:00
make build & & ./gitea
```
Before committing, make sure the linters pass:
```bash
make lint-frontend
2019-02-12 09:22:01 -07:00
```
2022-01-27 01:30:51 -07:00
### Configuring local ElasticSearch instance
Start local ElasticSearch instance using docker:
```sh
mkdir -p $(pwd)/data/elasticsearch
sudo chown -R 1000:1000 $(pwd)/data/elasticsearch
2022-05-29 11:59:25 -06:00
docker run --rm --memory="4g" -p 127.0.0.1:9200:9200 -p 127.0.0.1:9300:9300 -e "discovery.type=single-node" -v "$(pwd)/data/elasticsearch:/usr/share/elasticsearch/data" docker.elastic.co/elasticsearch/elasticsearch:7.16.3
2022-01-27 01:30:51 -07:00
```
Configure `app.ini` :
```ini
[indexer]
ISSUE_INDEXER_TYPE = elasticsearch
ISSUE_INDEXER_CONN_STR = http://elastic:changeme@localhost:9200
REPO_INDEXER_ENABLED = true
REPO_INDEXER_TYPE = elasticsearch
REPO_INDEXER_CONN_STR = http://elastic:changeme@localhost:9200
```
2020-07-12 03:10:56 -06:00
### Building and adding SVGs
2023-07-18 10:06:43 -06:00
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/assets/img/svg` . Custom icons can be added in the `web_src/svg` directory.
2020-07-12 03:10:56 -06:00
2020-07-26 03:47:51 -06:00
### Building the Logo
2019-05-15 23:57:47 -06:00
2022-07-27 19:22:47 -06:00
The PNG and SVG versions of the Gitea logo are built from a single SVG source file `assets/logo.svg` using the `TAGS="gitea" make generate-images` target. To run it, Node.js and npm must be available.
2020-12-18 18:17:27 -07:00
The same process can also be used to generate custom logo PNGs from a SVG source file by updating `assets/logo.svg` and running `make generate-images` . Omitting the `gitea` tag will update only the user-designated logo files.
2019-11-21 13:06:23 -07:00
2019-02-12 09:22:01 -07:00
### Updating the API
2019-03-09 14:15:45 -07:00
When creating new API routes or modifying existing API routes, you **MUST**
2019-02-12 09:22:01 -07: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 14:15:45 -07:00
If you want more information about the Swagger structure, you can look at the
2019-02-12 09:22:01 -07:00
[Swagger 2.0 Documentation ](https://swagger.io/docs/specification/2-0/basic-structure/ )
2019-03-09 14:15:45 -07: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 09:22:01 -07:00
You should be careful not to break the API for downstream users which depend
2019-03-09 14:15:45 -07: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 09:22:01 -07:00
Once you have created or changed an API endpoint, please regenerate the Swagger
documentation using:
```bash
make generate-swagger
```
2024-02-15 19:42:26 -07:00
You should validate your generated Swagger file:
2019-02-12 09:22:01 -07:00
```bash
2024-02-15 19:42:26 -07:00
make swagger-validate
2019-02-12 09:22:01 -07:00
```
2021-05-18 11:35:59 -06:00
You should commit the changed swagger JSON file. The continuous integration
2019-02-12 09:22:01 -07:00
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
2023-07-25 22:53:13 -06:00
[configuration cheat sheet ](administration/config-cheat-sheet.md )
2023-03-23 09:18:24 -06:00
found in `docs/content/doc/administer/config-cheat-sheet.en-us.md`
2019-02-12 09:22:01 -07:00
### Changing the logo
2019-03-09 14:15:45 -07:00
When changing the Gitea logo SVG, you will need to run and commit the results
2019-02-12 09:22:01 -07: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 14:15:45 -07:00
`models/` directory, you will need to make a new migration. These can be found
2019-02-12 09:22:01 -07:00
in `models/migrations/` . You can ensure that your migrations work for the main
database types using:
```bash
2021-12-23 20:56:57 -07:00
make test-sqlite-migration # with SQLite switched for the appropriate database
2017-11-26 14:44:32 -07:00
```
2019-02-12 09:22:01 -07:00
## Testing
There are two types of test run by Gitea: Unit tests and Integration Tests.
2021-12-31 07:21:11 -07:00
### Unit Tests
Unit tests are covered by `*_test.go` in `go test` system.
2021-12-31 20:31:24 -07:00
You can set the environment variable `GITEA_UNIT_TESTS_LOG_SQL=1` to display all SQL statements when running the tests in verbose mode (i.e. when `GOTESTFLAGS=-v` is set).
2021-12-31 07:21:11 -07:00
2019-02-12 09:22:01 -07:00
```bash
TAGS="bindata sqlite sqlite_unlock_notify" make test # Runs the unit tests
```
2021-12-31 07:21:11 -07:00
### Integration Tests
2019-03-09 14:15:45 -07: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 09:22:01 -07:00
```bash
2019-12-04 20:41:38 -07:00
TAGS="bindata sqlite sqlite_unlock_notify" make build test-sqlite
2019-02-12 09:22:01 -07:00
```
2021-12-23 20:56:57 -07:00
will run the integration tests in an SQLite environment. Integration tests
2020-12-08 23:47:06 -07:00
require `git lfs` to be installed. Other database tests are available but
2020-01-28 19:30:02 -07:00
may need adjustment to the local environment.
2019-02-12 09:22:01 -07:00
2022-09-02 13:18:23 -06:00
Take a look at [`tests/integration/README.md` ](https://github.com/go-gitea/gitea/blob/main/tests/integration/README.md )
2019-02-12 09:22:01 -07:00
for more information and how to run a single test.
2021-12-31 07:21:11 -07:00
### Testing for a PR
2019-02-12 09:22:01 -07:00
Our continuous integration will test the code passes its unit tests and that
2019-03-09 14:15:45 -07: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 09:22:01 -07: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-28 19:30:02 -07:00
# from the docs directory within Gitea
2019-02-12 09:22:01 -07:00
make trans-copy clean build
```
You will require a copy of [Hugo ](https://gohugo.io/ ) to run this task. Please
2021-12-23 20:56:57 -07:00
note: this may generate a number of untracked Git objects, which will need to
2019-02-12 09:22:01 -07: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
2021-05-04 10:16:23 -06:00
[`contrib/ide/README.md` ](https://github.com/go-gitea/gitea/blob/main/contrib/ide/README.md )
2019-02-12 09:22:01 -07:00
for more information.
2021-08-28 21:25:08 -06:00
## GoLand
2022-07-27 19:22:47 -06:00
Clicking the `Run Application` arrow on the function `func main()` in `/main.go`
2021-11-28 06:28:30 -07:00
can quickly start a debuggable Gitea instance.
2021-08-28 21:25:08 -06:00
2022-07-27 19:22:47 -06:00
The `Output Directory` in `Run/Debug Configuration` MUST be set to the
gitea project directory (which contains `main.go` and `go.mod` ),
otherwise, the started instance's working directory is a GoLand's temporary directory
and prevents Gitea from loading dynamic resources (eg: templates) in a development environment.
2021-08-28 21:25:08 -06:00
To run unit tests with SQLite in GoLand, set `-tags sqlite,sqlite_unlock_notify`
in `Go tool arguments` of `Run/Debug Configuration` .
2019-02-12 09:22:01 -07:00
## 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
2021-05-04 10:16:23 -06:00
branches as we will need to update it to main before merging and/or may be
2019-02-12 09:22:01 -07:00
able to help fix issues directly.
Any PR requires two approvals from the Gitea maintainers and needs to pass the
2021-05-18 11:35:59 -06:00
continuous integration. Take a look at our
2021-05-04 10:16:23 -06:00
[`CONTRIBUTING.md` ](https://github.com/go-gitea/gitea/blob/main/CONTRIBUTING.md )
2019-02-12 09:22:01 -07:00
document.
If you need more help pop on to [Discord ](https://discord.gg/gitea ) #Develop
and chat there.
2017-11-26 14:44:32 -07:00
2019-02-12 09:22:01 -07:00
That's it! You are ready to hack on Gitea.