mirror of
https://github.com/go-gitea/gitea.git
synced 2026-09-20 01:32:41 +02:00
docs: add development setup guide and Gitpod integration
This commit is contained in:
Nicolas
@@ -4,6 +4,7 @@ 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) |
|
||||
| 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) |
|
||||
|
||||
@@ -53,6 +53,8 @@ Internet connectivity is required to download the go and npm modules. When build
|
||||
|
||||
More info: https://docs.gitea.com/installation/install-from-source
|
||||
|
||||
For setting up a local development environment, continuous builds, linting, and testing, see [docs/development.md](docs/development.md).
|
||||
|
||||
## Using
|
||||
|
||||
After building, a binary file named `gitea` will be generated in the root of the source tree by default. To run it, use:
|
||||
@@ -69,7 +71,8 @@ Expected workflow is: Fork -> Patch -> Push -> Pull Request
|
||||
> [!NOTE]
|
||||
>
|
||||
> 1. **YOU MUST READ THE [CONTRIBUTORS GUIDE](CONTRIBUTING.md) BEFORE STARTING TO WORK ON A PULL REQUEST.**
|
||||
> 2. If you have found a vulnerability in the project, please write privately to **security@gitea.io**. Thanks!
|
||||
> 2. New to the codebase? The [development guide](docs/development.md) walks through setting up a local environment and building from source.
|
||||
> 3. If you have found a vulnerability in the project, please write privately to **security@gitea.io**. Thanks!
|
||||
|
||||
## Translating
|
||||
|
||||
|
||||
@@ -0,0 +1,23 @@
|
||||
<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>
|
||||
|
After Width: | Height: | Size: 4.5 KiB |
@@ -0,0 +1,296 @@
|
||||
# Hacking on 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.
|
||||
|
||||
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.
|
||||
|
||||
> [!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.
|
||||
|
||||
### Python (optional)
|
||||
|
||||
To lint the template files, ensure [Python](https://www.python.org/) and [Poetry](https://python-poetry.org/) are installed.
|
||||
|
||||
### 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
|
||||
```
|
||||
|
||||
#### On Windows
|
||||
|
||||
One of these three distributions of Make will run on Windows:
|
||||
|
||||
- [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]
|
||||
> If you are building with make from the Windows Command Prompt, you may run into issues. The prompts above (Git Bash or MinGW) are recommended. If you only have Command Prompt (or PowerShell) you can set environment variables using the [set](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/set_1) 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`.
|
||||
|
||||
```bash
|
||||
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.
|
||||
|
||||
## 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:
|
||||
|
||||
```bash
|
||||
TAGS="bindata sqlite sqlite_unlock_notify" 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.
|
||||
|
||||
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.
|
||||
|
||||
### Building continuously
|
||||
|
||||
To run and continuously rebuild when source files change:
|
||||
|
||||
```bash
|
||||
# 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 raised 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 linters (including format check, code analysis and spell check).
|
||||
|
||||
Format your code:
|
||||
|
||||
```bash
|
||||
make fmt
|
||||
```
|
||||
|
||||
and lint the source code:
|
||||
|
||||
```bash
|
||||
# lint both frontend and backend code
|
||||
make lint
|
||||
# lint only backend code
|
||||
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 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.
|
||||
|
||||
### Updating the API
|
||||
|
||||
When creating or modifying API routes, you **MUST** update and/or create [Swagger](https://swagger.io/docs/specification/2-0/what-is-swagger/) documentation for them using [go-swagger](https://goswagger.io/) comments. The structure of these comments is described in the [specification](https://goswagger.io/use/spec.html#annotation-syntax). For more information about the Swagger structure, see the [Swagger 2.0 Documentation](https://swagger.io/docs/specification/2-0/basic-structure/), or compare with a previous PR adding a new API endpoint, e.g. [PR #5483](https://github.com/go-gitea/gitea/pull/5843/files#diff-2e0a7b644cf31e1c8ef7d76b444fe3aaR20).
|
||||
|
||||
Be careful not to break the API for downstream users who depend on a stable API. In general, additions are acceptable, but deletions or fundamental changes to the API will be rejected.
|
||||
|
||||
Once you have created or changed an API endpoint, regenerate the Swagger documentation:
|
||||
|
||||
```bash
|
||||
make generate-swagger
|
||||
```
|
||||
|
||||
Validate your generated Swagger file:
|
||||
|
||||
```bash
|
||||
make swagger-validate
|
||||
```
|
||||
|
||||
Commit the changed Swagger JSON file. The continuous integration server checks that this has been done using:
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
## Documentation for the website
|
||||
|
||||
Documentation for the website lives in the [documentation repository](https://gitea.com/gitea/docs). The `docs/` directory in this repository holds contributor-facing documents only; if you change them you can check that they pass continuous integration using:
|
||||
|
||||
```bash
|
||||
make lint-md
|
||||
```
|
||||
|
||||
## Visual Studio Code
|
||||
|
||||
A `launch.json` and `tasks.json` are provided in [`contrib/development/vscode`](../contrib/development/vscode). See [`contrib/development/README.md`](../contrib/development/README.md) for more information.
|
||||
|
||||
## GoLand
|
||||
|
||||
Clicking the `Run Application` arrow on the function `func main()` in `/main.go` can quickly start a debuggable Gitea instance.
|
||||
|
||||
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`.
|
||||
|
||||
## 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 main before merging and may be able to help fix issues directly.
|
||||
|
||||
Any PR requires two approvals from the Gitea maintainers and needs to pass continuous integration. See the [CONTRIBUTING.md](../CONTRIBUTING.md) document.
|
||||
|
||||
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.
|
||||
Reference in New Issue
Block a user