Mirrors/gitea
0
0
Fork 0
mirror of https://github.com/go-gitea/gitea.git synced 2026-09-20 01:32:41 +02:00
Code Issues Activity

enhance

Browse Source
This commit is contained in:
Nicolas
2026-05-31 21:13:13 +02:00
parent 364b639db2
commit b49ade87fc
4 changed files with 79 additions and 148 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CONTRIBUTING.md
+2 -1
View File
@@ -4,7 +4,8 @@ This document explains how to contribute changes to the Gitea project. Topic-spe
| Topic | Document |
| :---- | :------- |
| Development environment, building, testing | [docs/development.md](docs/development.md) |
| Development environment, building | [docs/development.md](docs/development.md) |
| Running the tests | [docs/testing.md](docs/testing.md) |
| Backend (Go modules, API v1) | [docs/guideline-backend.md](docs/guideline-backend.md) |
| Frontend (npm, UI guidelines) | [docs/guideline-frontend.md](docs/guideline-frontend.md) |
| Maintainers, TOC, labels, merge queue, commit format for mergers | [docs/community-governance.md](docs/community-governance.md) |
assets/open-in-gitpod.svg
-23
View File
@@ -1,23 +0,0 @@
<svg width="160" height="45" fill="none" xmlns="http://www.w3.org/2000/svg">
<g filter="url(#filter0_d)">
<rect x="2" y="2" width="156" height="40" rx="16" fill="#F9F9F9"/>
<path fill-rule="evenodd" clip-rule="evenodd" d="M30.425 11.174c.604 1.114.233 2.53-.83 3.164l-6.986 4.166a.378.378 0 00-.18.325v6.748c0 .134.069.258.18.325l5.714 3.407c.11.066.244.066.354 0l5.714-3.407a.378.378 0 00.18-.325V21.29l-4.986 2.936c-1.067.628-2.416.231-3.015-.886-.6-1.118-.22-2.532.846-3.16l7.008-4.127c2.048-1.206 4.576.345 4.576 2.806v6.718c0 1.803-.924 3.467-2.42 4.36l-5.713 3.407a4.596 4.596 0 01-4.734 0l-5.714-3.408C18.924 29.044 18 27.38 18 25.576V18.83c0-1.803.924-3.467 2.42-4.36l6.985-4.165c1.063-.634 2.415-.245 3.02.87z" fill="url(#paint0_linear)"/>
<path fill="#F9F9F9" d="M47 12.5h95v-1H47z"/>
<path d="M52.538 27.752c2.744 0 4.844-1.876 4.844-5.152 0-3.108-2.1-5.152-4.844-5.152s-4.802 2.002-4.802 5.152c0 3.29 2.058 5.152 4.802 5.152zm0-1.554c-1.736 0-2.912-1.316-2.912-3.598 0-2.226 1.162-3.598 2.912-3.598s2.954 1.4 2.954 3.598c0 2.31-1.218 3.598-2.954 3.598zm7.89 4.158V27.22c0-.196-.013-.378-.055-.658.434.7 1.022 1.19 2.17 1.19 1.736 0 3.066-1.414 3.066-3.626 0-2.17-1.19-3.682-2.996-3.682-1.078 0-1.806.476-2.24 1.204.042-.28.056-.462.056-.672v-.308H58.72v9.688h1.708zm1.695-3.948c-1.036 0-1.764-.938-1.764-2.31 0-1.414.742-2.296 1.764-2.296 1.092 0 1.75.952 1.75 2.296 0 1.372-.7 2.31-1.75 2.31zm7.866 1.344c1.848 0 3.052-1.078 3.192-2.478h-1.736c-.112.714-.714 1.134-1.456 1.134-1.036 0-1.722-.826-1.736-1.904h4.97v-.378c0-2.226-1.204-3.682-3.29-3.682-1.988 0-3.43 1.47-3.43 3.626 0 2.366 1.442 3.682 3.486 3.682zm-1.75-4.48c.098-.896.756-1.554 1.68-1.554.924 0 1.526.63 1.554 1.554H68.24zm8.006 4.228v-4.004c0-.952.616-1.694 1.456-1.694.798 0 1.288.63 1.288 1.638v4.06h1.708v-4.312c0-1.68-.896-2.744-2.408-2.744-1.078 0-1.722.518-2.1 1.204.042-.266.056-.476.056-.672v-.308h-1.708V27.5h1.708zm8.911-7.868h1.792V17.84h-1.792v1.792zm.042 1.036V27.5h1.708v-6.832h-1.708zm5.097 6.832v-4.004c0-.952.616-1.694 1.456-1.694.798 0 1.288.63 1.288 1.638v4.06h1.708v-4.312c0-1.68-.896-2.744-2.408-2.744-1.078 0-1.722.518-2.1 1.204.042-.266.056-.476.056-.672v-.308h-1.708V27.5h1.708zm13.238.252c1.526 0 2.52-.658 2.982-1.54-.07.322-.098.644-.098.98v.308h1.68v-5.222h-4.34v1.554h2.66v.07c0 1.4-1.134 2.296-2.59 2.296-1.792 0-3.024-1.372-3.024-3.598s1.26-3.598 3.066-3.598c1.302 0 2.17.756 2.296 1.736h1.89c-.182-1.904-1.764-3.29-4.214-3.29-2.954 0-4.928 2.128-4.928 5.152 0 3.136 1.848 5.152 4.62 5.152zm6.063-8.12h1.792V17.84h-1.792v1.792zm.042 1.036V27.5h1.708v-6.832h-1.708zm6.413 6.958c.434 0 .84-.07 1.008-.126v-1.288c-.168.028-.35.042-.518.042-.728 0-1.008-.42-1.008-1.134v-3.094h1.68v-1.358h-1.68v-2.464h-1.708v2.464h-1.554v1.358h1.554v3.346c0 1.526.77 2.254 2.226 2.254zm3.961 2.73V27.22c0-.196-.014-.378-.056-.658.434.7 1.022 1.19 2.17 1.19 1.736 0 3.066-1.414 3.066-3.626 0-2.17-1.19-3.682-2.996-3.682-1.078 0-1.806.476-2.24 1.204.042-.28.056-.462.056-.672v-.308h-1.708v9.688h1.708zm1.694-3.948c-1.036 0-1.764-.938-1.764-2.31 0-1.414.742-2.296 1.764-2.296 1.092 0 1.75.952 1.75 2.296 0 1.372-.7 2.31-1.75 2.31zm7.88 1.344c2.058 0 3.514-1.372 3.514-3.64 0-2.24-1.456-3.668-3.514-3.668-2.044 0-3.5 1.428-3.5 3.668 0 2.268 1.442 3.64 3.5 3.64zm0-1.344c-1.064 0-1.764-.84-1.764-2.296 0-1.484.728-2.31 1.764-2.31 1.05 0 1.778.826 1.778 2.31 0 1.456-.714 2.296-1.778 2.296zm7.551 1.344c1.26 0 1.876-.686 2.142-1.19-.056.238-.056.42-.056.658v.28h1.708v-9.8h-1.708v3.276c0 .21 0 .42.056.672-.392-.658-1.05-1.204-2.114-1.204-1.596 0-3.15 1.218-3.15 3.668 0 2.408 1.316 3.64 3.122 3.64zm.406-1.344c-1.022 0-1.792-.896-1.792-2.31 0-1.358.77-2.296 1.792-2.296s1.778.896 1.778 2.296c0 1.372-.756 2.31-1.778 2.31z" fill="#12100C"/>
</g>
<defs>
<linearGradient id="paint0_linear" x1="33.806" y1="13.629" x2="22.389" y2="30.86" gradientUnits="userSpaceOnUse">
<stop stop-color="#FFB45B"/>
<stop offset="1" stop-color="#FF8A00"/>
</linearGradient>
<filter id="filter0_d" x="0" y=".5" width="160" height="44" filterUnits="userSpaceOnUse" color-interpolation-filters="sRGB">
<feFlood flood-opacity="0" result="BackgroundImageFix"/>
<feColorMatrix in="SourceAlpha" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0"/>
<feOffset dy=".5"/>
<feGaussianBlur stdDeviation="1"/>
<feColorMatrix values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0.1 0"/>
<feBlend in2="BackgroundImageFix" result="effect1_dropShadow"/>
<feBlend in="SourceGraphic" in2="effect1_dropShadow" result="shape"/>
</filter>
</defs>
</svg>
Side by Side

Before

Width:  |  Height:  |  Size: 4.5 KiB

docs/development.md
+17 -124
View File
@@ -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.
[![Open in Gitpod](../assets/open-in-gitpod.svg)](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.
docs/testing.md
+60
View File
@@ -0,0 +1,60 @@
# Testing Gitea
Gitea has three kinds of automated tests: backend unit tests, integration tests, and end-to-end (e2e) tests. The default database for local test runs is SQLite (pure-Go modernc driver), so no extra services are required to get started.
## Unit tests
Unit tests live in `*_test.go` files next to the code they cover and run through `go test`. Set `GITEA_TEST_LOG_SQL=1` to log all SQL statements executed during the tests.
```bash
make test-backend
```
To run a single test, use `go test` directly or the `#` selector:
```bash
go test -run '^TestName$' ./modulepath/
make test-backend#TestName
```
Frontend unit tests run with:
```bash
make test-frontend
```
## Integration tests
Integration tests exercise Gitea against a real database. They live in `tests/integration/` and require `git lfs` to be installed. With an empty `GITEA_TEST_DATABASE` they default to SQLite:
```bash
make test-integration
```
Use `GITEA_TEST_DATABASE` to run against MySQL, PostgreSQL, or MSSQL instead. The required connection environment variables and ready-to-use Docker commands for each database are documented in [`tests/integration/README.md`](../tests/integration/README.md), which also explains how to run a single integration test.
## End-to-end tests
End-to-end tests drive a running Gitea instance with [Playwright](https://playwright.dev/):
```bash
make test-e2e
```
To run a single e2e test file, pass it via `GITEA_TEST_E2E_FLAGS`:
```bash
GITEA_TEST_E2E_FLAGS='<filepath>' make test-e2e
```
## Migration tests
If you change a database-persisted struct in `models/` you will usually need a new migration in `models/migrations/`. Run the migration tests with:
```bash
make test-migration
```
## Continuous integration
Our continuous integration runs the unit tests and runs the integration tests against every supported database, and also tests migration from several recent Gitea versions. Please submit your pull request with additional unit and integration tests as appropriate; prefer unit tests when the logic can be tested in isolation, and keep local integration and e2e tests fast (aim for sub-2s).