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: "developers"
name: "Hacking on Gitea"
weight: 10
identifier: "hacking-on-gitea"

Hacking on Gitea

Table of Contents

Installing go

You should install go and set up your go environment correctly.

Next, install Node.js with npm which is required to build the JavaScript and CSS files. The minimum supported Node.js version is {{< min-node-version >}} and the latest LTS version is recommended.

Note: When executing make tasks that require external tools, like make watch-backend, 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 {{< min-go-version >}} or higher is required. Gitea uses gofmt to format source code. However, the results of gofmt can differ by the version of go. Therefore it is recommended to install the version of Go that our continuous integration is running. As of last update, the Go version should be {{< go-version >}}.

Installing Make

Gitea makes heavy use of Make to automate tasks and improve development. This guide covers how to install Make.

On Linux

Install with the package manager.

On Ubuntu/Debian:

sudo apt-get install make

On Fedora/RHEL/CentOS:

sudo yum install make

On Windows

One of these three distributions of Make will run on Windows:

Single binary build. Copy somewhere and add to PATH.
- 32-bits version
- 64-bits version
MinGW-w64 / MSYS2.
- 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.
- 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.
- To compile Gitea with CGO_ENABLED (eg: SQLite3), you might need to use tdm-gcc instead of MSYS2 gcc, because MSYS2 gcc headers lack some Windows-only CRT functions like _beginthread.
Chocolatey package. Run choco install make

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 command, e.g. set TAGS=bindata.

Downloading and cloning the Gitea source code

The recommended method of obtaining the source code is by using git clone.

git clone https://github.com/go-gitea/gitea

(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.)

Forking Gitea

Download the main Gitea source code as above. Then, fork the Gitea repository on GitHub, and either switch the git remote origin for your fork or add your fork as another remote:

# 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

or:

# Add new remote for our fork
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 }}‘>building from source.

The simplest recommended way to build from source is:

TAGS="bindata sqlite sqlite_unlock_notify" make build

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.

See make help for all available make targets. Also see .drone.yml to see how our continuous integration works.

Building continuously

To run and continuously rebuild when source files change:

# for both frontend and backend
make watch

# or: watch frontend files (html/js/css) only
make watch-frontend

# or: watch backend files (go) only
make watch-backend

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.

Formatting, code analysis and spell check

Our continuous integration will reject PRs that fail the code linters (including format check, code analysis and spell check).

You should format your code:

make fmt

and lint the source code:

# lint both frontend and backend code
make lint
# lint only backend code
make lint-backend

Note: The results of gofmt 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.

Working on JS and CSS

Frontend development should follow Guidelines for Frontend Development

To build with frontend resources, either use the watch-frontend target mentioned above or just build once:

make build && ./gitea

Before committing, make sure the linters pass:

make lint-frontend

Configuring local ElasticSearch instance

Start local ElasticSearch instance using docker:

mkdir -p $(pwd)/data/elasticsearch
sudo chown -R 1000:1000 $(pwd)/data/elasticsearch
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

Configure app.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

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.

Building the Logo

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.

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.

Updating the API

When creating new API routes or modifying existing API routes, you MUST update and/or create Swagger documentation for these using go-swagger comments. The structure of these comments is described in the specification. If you want more information about the Swagger structure, you can look at the Swagger 2.0 Documentation or compare with a previous PR adding a new API endpoint, e.g. PR #5483

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:

make generate-swagger

You should validate your generated Swagger file and spell-check it with:

make swagger-validate misspell-check

You should commit the changed swagger JSON file. The continuous integration server will check that this has been done using:

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

hacking-on-gitea.en-us.md 13KB Raw Blame History