mirror of
https://github.com/go-gitea/gitea.git
synced 2026-10-23 21:04:55 +02:00
enhance
This commit is contained in:
Nicolas committed
1 parent
364b639db2
commit
b49ade87fc
4 files changed
+79
-148
No files matched your search
+17
-124
@@ -1,27 +1,21 @@
|
||||
# Hacking on Gitea
|
||||
# Developing Gitea
|
||||
|
||||
This document describes how to set up a local development environment and build Gitea from source. For the contribution workflow and review process, see [CONTRIBUTING.md](../CONTRIBUTING.md).
|
||||
|
||||
## Quickstart
|
||||
|
||||
To get a quick working development environment you could use Gitpod.
|
||||
|
||||
[](https://gitpod.io/#https://github.com/go-gitea/gitea)
|
||||
|
||||
## Installing dependencies
|
||||
|
||||
### Go
|
||||
|
||||
[Install Go](https://go.dev/doc/install) and set up your Go environment correctly. Go version 1.26 or higher is required.
|
||||
[Install Go](https://go.dev/doc/install) and set up your Go environment correctly. The required version is the one declared in [`go.mod`](../go.mod).
|
||||
|
||||
Gitea uses `gofmt` to format source code. The results of `gofmt` can differ between Go versions, so it is recommended to install the same version that our continuous integration runs. As of last update, that is Go 1.26.3.
|
||||
Gitea uses `gofmt` to format source code. The results of `gofmt` can differ between Go versions, so it is recommended to install the same version that our continuous integration runs.
|
||||
|
||||
> [!NOTE]
|
||||
> When running make tasks that require external tools, such as `make watch-backend`, Gitea downloads and builds them as needed. To use them you must have the `"$GOPATH"/bin` directory on your executable path. If you don't, you will have to manage these tools yourself.
|
||||
|
||||
### Node.js
|
||||
|
||||
[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 version is 22.18.0; the latest LTS version is recommended.
|
||||
[Install Node.js](https://nodejs.org/en/download/), which is required to build the JavaScript and CSS files. The minimum supported version is the one declared in [`package.json`](../package.json); the latest LTS version is recommended. Gitea uses [pnpm](https://pnpm.io/) to manage frontend dependencies; the `make` targets invoke it for you, so a manual install is only needed if you want to run `pnpm` commands directly.
|
||||
|
||||
### Python (optional)
|
||||
|
||||
@@ -29,36 +23,16 @@ To lint the template files, ensure [Python](https://www.python.org/) and [Poetry
|
||||
|
||||
### Make
|
||||
|
||||
Gitea makes heavy use of Make to automate tasks and improve development.
|
||||
|
||||
#### On Linux
|
||||
|
||||
Install with the package manager.
|
||||
|
||||
On Ubuntu/Debian:
|
||||
|
||||
```bash
|
||||
sudo apt-get install make
|
||||
```
|
||||
|
||||
On Fedora/RHEL/CentOS:
|
||||
|
||||
```bash
|
||||
sudo yum install make
|
||||
```
|
||||
Gitea makes heavy use of Make to automate tasks and improve development. On Linux and macOS it is usually preinstalled or available from the system package manager.
|
||||
|
||||
#### On Windows
|
||||
|
||||
One of these three distributions of Make will run on Windows:
|
||||
Make can be provided on Windows by either of these:
|
||||
|
||||
- [Single binary build](http://www.equation.com/servlet/equation.cmd?fa=make). Copy somewhere and add to `PATH`.
|
||||
- [32-bit version](http://www.equation.com/ftpdir/make/32/make.exe)
|
||||
- [64-bit version](http://www.equation.com/ftpdir/make/64/make.exe)
|
||||
- [MinGW-w64](https://www.mingw-w64.org) / [MSYS2](https://www.msys2.org/).
|
||||
- MSYS2 is a collection of tools and libraries providing an easy-to-use environment for building, installing and running native Windows software; it includes MinGW-w64.
|
||||
- In MinGW-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/).
|
||||
- To compile Gitea with `CGO_ENABLED` (e.g. 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`.
|
||||
- [Chocolatey package](https://chocolatey.org/packages/make). Run `choco install make`.
|
||||
|
||||
> [!NOTE]
|
||||
@@ -72,41 +46,23 @@ The recommended method of obtaining the source code is by using `git clone`.
|
||||
git clone https://github.com/go-gitea/gitea
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
> Since the advent of Go modules, it is no longer necessary to build Go projects from within `$GOPATH`, so the `go get` approach is no longer recommended.
|
||||
|
||||
## Forking Gitea
|
||||
|
||||
Download the main 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 to 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
|
||||
```
|
||||
|
||||
or:
|
||||
|
||||
```bash
|
||||
# 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.
|
||||
To contribute changes, [fork the Gitea repository](https://github.com/go-gitea/gitea) on GitHub and add your fork as a git remote so you can push branches and open pull requests. See GitHub's [working with forks](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks) documentation for the details.
|
||||
|
||||
## Building Gitea
|
||||
|
||||
See the [build from source instructions](https://docs.gitea.com/installation/install-from-source) for the full details.
|
||||
|
||||
The simplest recommended way to build from source is:
|
||||
The simplest recommended way to build from source for development is:
|
||||
|
||||
```bash
|
||||
TAGS="bindata sqlite sqlite_unlock_notify" make build
|
||||
TAGS="sqlite" make build
|
||||
```
|
||||
|
||||
The `build` target executes both the `frontend` and `backend` sub-targets. If the `bindata` tag is present, the frontend files are compiled into the binary. Leave the tag out when doing frontend development so that changes are reflected without rebuilding.
|
||||
The default `sqlite` tag uses the pure-Go [modernc](https://modernc.org/sqlite) driver, so no C compiler or extra tags are needed. To use the CGO-based mattn driver instead, build with `TAGS="sqlite sqlite_mattn sqlite_unlock_notify"`.
|
||||
|
||||
The `build` target executes both the `frontend` and `backend` sub-targets. The `bindata` tag embeds the frontend files into the binary; it is only needed for packaging a self-contained build and should be left out during development so that frontend changes are picked up without rebuilding.
|
||||
|
||||
See `make help` for all available `make` targets, and the workflows in [`.github/workflows`](https://github.com/go-gitea/gitea/tree/main/.github/workflows) to see how our continuous integration works.
|
||||
|
||||
@@ -146,53 +102,23 @@ make lint
|
||||
make lint-backend
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
> The results of `gofmt` depend on the version of Go present. Run the same version of Go that the continuous integration server uses, as mentioned above.
|
||||
|
||||
### Working on JS and CSS
|
||||
|
||||
Frontend development should follow the [Guidelines for Frontend Development](https://docs.gitea.com/contributing/guidelines-frontend).
|
||||
|
||||
To build with frontend resources, either use the `watch-frontend` target mentioned above or just build once:
|
||||
|
||||
```bash
|
||||
make build && ./gitea
|
||||
```
|
||||
|
||||
Before committing, make sure the linters pass:
|
||||
|
||||
```bash
|
||||
make lint-frontend
|
||||
```
|
||||
|
||||
### Configuring a local ElasticSearch instance
|
||||
|
||||
Start a local ElasticSearch instance using Docker:
|
||||
|
||||
```sh
|
||||
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`:
|
||||
|
||||
```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 into the output directory `public/assets/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. Node.js and npm must be available to run it.
|
||||
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. Node.js and pnpm must be available to run it.
|
||||
|
||||
The same process can generate custom logo PNGs from an SVG source file by updating `assets/logo.svg` and running `make generate-images`. Omitting the `gitea` tag updates only the user-designated logo files.
|
||||
|
||||
@@ -220,50 +146,17 @@ Commit the changed Swagger JSON file. The continuous integration server checks t
|
||||
make swagger-check
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
> 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 also add information to the [configuration cheat sheet](https://docs.gitea.com/administration/config-cheat-sheet), which lives in the [documentation repository](https://gitea.com/gitea/docs).
|
||||
|
||||
### Database migrations
|
||||
|
||||
If you make breaking changes to any of the database-persisted structs in the `models/` directory, you will need to add 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 # switch SQLite for the appropriate database
|
||||
```
|
||||
If you make breaking changes to any of the database-persisted structs in the `models/` directory, you will need to add a new migration in `models/migrations/`.
|
||||
|
||||
## Testing
|
||||
|
||||
Gitea runs two types of test: unit tests and integration tests.
|
||||
|
||||
### Unit tests
|
||||
|
||||
Unit tests are covered by `*_test.go` files in the `go test` system. 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).
|
||||
|
||||
```bash
|
||||
TAGS="bindata sqlite sqlite_unlock_notify" make test # runs the unit tests
|
||||
```
|
||||
|
||||
### Integration tests
|
||||
|
||||
Unit tests cannot completely test Gitea alone, so we have written integration tests; however, these are database dependent.
|
||||
|
||||
```bash
|
||||
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.
|
||||
|
||||
See [`tests/integration/README.md`](../tests/integration/README.md) for more information and how to run a single test.
|
||||
|
||||
### Testing for a PR
|
||||
|
||||
Our continuous integration will test that the code passes its unit tests and that all supported databases pass integration tests in a Docker environment. Migration from several recent versions of Gitea is also tested.
|
||||
|
||||
Please submit your PR with additional unit and integration tests as appropriate.
|
||||
For how to run the backend, integration, e2e, and migration tests, see [docs/testing.md](testing.md).
|
||||
|
||||
## Documentation for the website
|
||||
|
||||
@@ -283,7 +176,7 @@ Clicking the `Run Application` arrow on the function `func main()` in `/main.go`
|
||||
|
||||
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 temporary directory, which prevents Gitea from loading dynamic resources (e.g. templates) in a development environment.
|
||||
|
||||
To run unit tests with SQLite in GoLand, set `-tags sqlite,sqlite_unlock_notify` in `Go tool arguments` of `Run/Debug Configuration`.
|
||||
To run unit tests with SQLite in GoLand, set `-tags sqlite` in `Go tool arguments` of `Run/Debug Configuration`.
|
||||
|
||||
## Submitting PRs
|
||||
|
||||
@@ -293,4 +186,4 @@ Any PR requires two approvals from the Gitea maintainers and needs to pass conti
|
||||
|
||||
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.
|
||||
That's it! You are ready to start developing Gitea.
|
||||
Reference in new issue
Block a user