mirror of
https://github.com/go-gitea/gitea.git
synced 2026-11-19 15:14:40 +09:00
If the stderr output is not handled, then it needs to use RunWithStderr to make sure the git error message is included in the returned error. Otherwise, when the git command fails, the error log won't show useful information. Ref: * #39795 : no useful information in log messages * https://github.com/go-gitea/gitea/pull/40160#pullrequestreview-5752720866
175 lines
7.8 KiB
Markdown
175 lines
7.8 KiB
Markdown
# Backend development guidelines
|
|
|
|
This document covers backend-specific architecture and contribution expectations.
|
|
For the general workflow see [CONTRIBUTING.md](../CONTRIBUTING.md), and for building
|
|
and testing see [development.md](development.md) and [testing.md](testing.md).
|
|
|
|
## Background
|
|
|
|
The backend is written in Go. Web routing is handled by
|
|
[chi](https://github.com/go-chi/chi) and database access goes through the
|
|
[XORM](https://xorm.io/) ORM. Understanding how the packages depend on each other is
|
|
essential before contributing backend code.
|
|
|
|
## Package design
|
|
|
|
### Package layout
|
|
|
|
The backend is split into top-level packages, each with a focused responsibility:
|
|
|
|
- `build`: helper scripts used at compile time
|
|
- `cmd`: subcommands such as `web`, `serv`, `hooks`, `doctor`, and admin utilities
|
|
- `models`: data structures and database operations (XORM); keeps external
|
|
dependencies to a minimum
|
|
- `models/db`: core database operations
|
|
- `models/fixtures`: sample data used by tests
|
|
- `modelmigration`: schema migration scripts
|
|
- `modules`: standalone functionality with few dependencies
|
|
- `modules/setting`: configuration handling
|
|
- `modules/git`: interaction with the Git command line
|
|
- `routers`: request handlers, split into `api`, `web`, `install`, and `private`
|
|
- `services`: business logic that ties routers and models together
|
|
- `templates`: Go HTML templates
|
|
- `public`: compiled frontend assets
|
|
- `tests`: integration and end-to-end test helpers
|
|
|
|
### Dependency direction
|
|
|
|
Dependencies only flow in one direction:
|
|
|
|
```text
|
|
cmd → routers → services → models → modules
|
|
```
|
|
|
|
A package on the left may import a package on its right, but never the reverse.
|
|
|
|
### Naming conventions
|
|
|
|
- Top-level packages use the plural form: `services`, `models`, `routers`.
|
|
- Subpackages use the singular form: `services/user`, `models/repository`.
|
|
|
|
When packages from different layers share a name, use a snake_case import alias to
|
|
disambiguate:
|
|
|
|
```go
|
|
import user_service "gitea.dev/services/user"
|
|
```
|
|
|
|
### Database transactions
|
|
|
|
Operations that must roll back together should run inside `db.WithTx()` (or
|
|
`db.WithTx2()` when a value must be returned), defined in `models/db/context.go`.
|
|
Functions that participate in a transaction take a `context.Context` as their first
|
|
parameter so the transaction can be propagated.
|
|
|
|
PostgreSQL, MySQL and MSSQL (via `READ_COMMITTED_SNAPSHOT`) read the last committed
|
|
row version, so reads never wait for writers. Guard read-then-write logic with a
|
|
conditional `UPDATE` or a lock.
|
|
|
|
### XORM gotchas
|
|
|
|
- Never call `x.Update(exemplar)` without an explicit `WHERE` clause — it updates
|
|
every row in the table.
|
|
- Partial table migrations must use `SyncWithOptions(IgnoreDrop...)` rather than a
|
|
plain `Sync`.
|
|
- When inserting rows with preset IDs, MSSQL requires `SET IDENTITY_INSERT` to be
|
|
enabled and PostgreSQL requires the sequence to be updated afterwards.
|
|
- Struct conditions skip zero-valued fields, so `Get(&Reaction{IssueID: 1})` also
|
|
matches comment reactions. Use `Where` or `builder` when a zero value matters.
|
|
- Struct updates skip zero-valued fields unless selected by `Cols` or `AllCols()`.
|
|
`Cols` silently ignores unknown names. `updated` columns are always written unless
|
|
`NoAutoTime()` is used.
|
|
- `xorm:"deleted"` columns count both `0` and `NULL` as not deleted, so hand-written
|
|
conditions must accept both.
|
|
- On every start, `SyncAllTables` drops indexes absent from the model, so declare
|
|
migration-created indexes there, including in backports. It only warns about
|
|
nullability and default changes, so apply them through migrations.
|
|
- `ForUpdate` only works on MySQL and PostgreSQL. MSSQL rejects TEXT columns in
|
|
struct conditions and inserts of more than 1000 rows.
|
|
- Paginated queries need a unique tiebreaker like `id` for a stable order.
|
|
|
|
### Git
|
|
|
|
- Pass already opened repositories down or use `git.RepositoryFromContextOrOpen`
|
|
rather than reopening them or spawning extra `git` processes.
|
|
- If git command stderr output is not handled by the caller, then it needs to use RunWithStderr
|
|
to make sure the git error message is included in the returned error and displayed in the logs.
|
|
|
|
## Dependencies
|
|
|
|
Go dependencies are managed with [Go Modules](https://go.dev/ref/mod).
|
|
|
|
Pull requests should only modify `go.mod` and `go.sum` where it relates to the
|
|
change at hand, be it a bug fix or a new feature. Otherwise, these files should only
|
|
be touched by pull requests whose sole purpose is updating dependencies. Run
|
|
`make tidy` after any change to `go.mod`.
|
|
|
|
Any `go.mod` / `go.sum` update must be justified in the PR description and must be
|
|
verified by reviewers and the merger to reference an existing upstream commit.
|
|
|
|
## Golang HTML template
|
|
|
|
Gitea uses Go's built-in HTML template engine which is dynamically & weakly typed.
|
|
To make template code maintainable:
|
|
|
|
- Go code should take over complex logic and prepare template data as much as possible, templates only render the data.
|
|
- Prefer struct types provided by Go code instead of map types for template data.
|
|
- Avoid using single word names for non-local variables.
|
|
- Avoid passing `"root" $` or `"." .` to sub-templates, instead pass the specific data needed by the sub-template.
|
|
- Use explicit variable names instead of `.` to access data: ``{{range $item := $.TargetItems}}{{ $item.Name }}{{end}}``
|
|
- Use Go code to implement render helpers if the render logic is too complex.
|
|
|
|
Using a modern and statically & strongly typed template engine to replace Golang HTML template might be good,
|
|
but the challenge is huge, the requisites are:
|
|
|
|
- A working and maintainable proof-of-concept for the most complex templates (like "PR View" and "PR Diff").
|
|
- A firm commitment of sufficient engineering resources.
|
|
|
|
## API v1
|
|
|
|
The API is documented with [Swagger](https://gitea.com/api/swagger) and is modelled
|
|
on [the GitHub API](https://docs.github.com/en/rest).
|
|
|
|
### GitHub API compatibility
|
|
|
|
Gitea's API should use the same endpoints and fields as the GitHub API where
|
|
possible, unless there is a good reason to deviate.
|
|
|
|
- If Gitea offers functionality GitHub does not, a new endpoint may be added.
|
|
- If Gitea exposes information the GitHub API does not, a new field may be added as
|
|
long as it does not collide with a GitHub field.
|
|
- Existing fields should not be removed unless there is a strong reason; the same
|
|
applies to status responses.
|
|
|
|
If you notice a problem that would require a breaking change, leave a comment in the
|
|
code for a future refactor to API v2 (which is currently not planned) rather than
|
|
breaking v1.
|
|
|
|
### Adding and maintaining API routes
|
|
|
|
- Document success responses in the swagger comments on the route. Replace explicit
|
|
error responses with a `default` response referencing `#/responses/error`.
|
|
- Every JSON request body must be defined as a struct in `modules/structs/` and
|
|
registered in [`routers/api/v1/swagger/options.go`](../routers/api/v1/swagger/options.go).
|
|
- Every JSON response must be defined as a struct in `modules/structs/` and
|
|
registered with its category under [`routers/api/v1/swagger/`](../routers/api/v1/swagger).
|
|
|
|
### HTTP methods and status codes
|
|
|
|
In general, choose HTTP methods as follows:
|
|
|
|
- **GET** returns the requested object(s) with status **200 OK**.
|
|
- **POST** creates a new object (e.g. a user) and returns **201 Created** with the
|
|
created object.
|
|
- **PUT** adds or assigns an existing object (e.g. a user to a team) and returns
|
|
**204 No Content** with no response body.
|
|
- **PATCH** edits an existing object and returns the changed object with **200 OK**.
|
|
- **DELETE** removes an object and returns **204 No Content** with no body.
|
|
|
|
### Requirements for API routes
|
|
|
|
- All parameters of endpoints that edit an object must be optional, except those
|
|
needed to identify the object, which are required.
|
|
- Endpoints returning lists must support pagination (`page` and `limit` query
|
|
options) and set the `X-Total-Count` header via `ctx.SetTotalCountHeader(...)`.
|