From b49ade87fc8da985977c4189d0c58a40ad8e21c1 Mon Sep 17 00:00:00 2001 From: Nicolas Date: Sun, 31 May 2026 21:13:13 +0200 Subject: [PATCH] enhance --- CONTRIBUTING.md | 3 +- assets/open-in-gitpod.svg | 23 ------- docs/development.md | 141 +++++--------------------------------- docs/testing.md | 60 ++++++++++++++++ 4 files changed, 79 insertions(+), 148 deletions(-) delete mode 100644 assets/open-in-gitpod.svg create mode 100644 docs/testing.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dd3c8564caf..30edbe0e63b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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) | diff --git a/assets/open-in-gitpod.svg b/assets/open-in-gitpod.svg deleted file mode 100644 index b97cd294879..00000000000 --- a/assets/open-in-gitpod.svg +++ /dev/null @@ -1,23 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/development.md b/docs/development.md index ed72b849a15..5d3edefcde7 100644 --- a/docs/development.md +++ b/docs/development.md @@ -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. diff --git a/docs/testing.md b/docs/testing.md new file mode 100644 index 00000000000..70b108c3054 --- /dev/null +++ b/docs/testing.md @@ -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='' 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).