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

date	title	slug	weight	toc	draft	menu
2016-12-01T16:00:00+02:00	Hacking on Gitea	hacking-on-gitea	10	false	false	sidebar parent name weight identifier advanced Hacking on Gitea 10 hacking-on-gitea

Hacking on Gitea

Installing go and setting the GOPATH

You should install go 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.

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.

You will also need make. (See here how to get Make)

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 {{< min-go-version >}} 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. As of last update, it should be Go version {{< go-version >}}.

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 master 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 instructions for building from source.

The simplest recommended way to build from source is:

TAGS="bindata sqlite sqlite_unlock_notify" make 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 for more, and look at our .drone.yml to see how our continuous integration works.

Formatting, code analysis and spell check

Our continuous integration will reject PRs that are not properly formatted, fail code analysis or spell check.

You should format your code with go fmt using:

make fmt

and can test whether your changes would match the results with:

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 run revive, vet and spell-check on the code with:

make revive vet misspell-check

Working on JS and CSS

For simple changes, edit files in web_src, run the build and start the server to test:

make build && ./gitea

For more involved changes use the watch-frontend task to continuously rebuild files when their sources change. The bindata tag must be absent to ensure the file system will be used for files in public. First, build and run the backend:

make backend && ./gitea

With the backend running, open another terminal and run:

make watch-frontend

Before committing, make sure the linters pass:

make lint-frontend

Note: When working on frontend code, it is advisable to set USE_SERVICE_WORKER to false in app.ini which will prevent undesirable caching of frontend assets.

Building Images

To build the images, ImageMagick, inkscape and zopflipng binaries must be available in your PATH to run make generate-images.

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 continous 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 configuration cheat sheet 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:

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:

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.

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.

TAGS="bindata sqlite sqlite_unlock_notify" make build test-sqlite

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.

Look at 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:

# from the docs directory within Gitea
make trans-copy clean build

You will require a copy of Hugo 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 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 document.

If you need more help pop on to Discord #Develop and chat there.

That's it! You are ready to hack on Gitea.