mirror of https://github.com/go-gitea/gitea.git synced 2026-04-13 16:07:56 +02:00

Files

Nicolas 47fdf3e284 Improve Contributing docs and set a release schedule (#37109 )

This PR updates `CONTRIBUTING.md` for clarity (code review, maintainers,
PR workflow)

## Suggestion

- majors about every **three months**, with a more predictable cadence
from **v1.26** onward.
- target dates such as **v1.26.0** (April 2026), **v1.27.0** (June
2026), **v1.28.0** (September 2026), **v1.29.0** (December 2026).
- announce feature freeze **two weeks** before each release.

## Other doc changes

- Reviewing PRs: separate guidance for reviewers vs authors; small edits
to maintaining PRs, merge queue, commit messages, co-authors.
- Maintainers: clearer subsections; links to GitHub Docs for 2FA / GPG.
- Split the Contributing.md into more useful markdown files

---------

Signed-off-by: Nicolas <bircni@icloud.com>

2026-04-12 11:26:02 -07:00

4.2 KiB

Raw Permalink Blame History

Backend development

This document covers backend-specific contribution expectations. For general contribution workflow, see CONTRIBUTING.md.

For coding style and architecture, see also the backend development guideline on the documentation site.

Dependencies

Go dependencies are managed using Go Modules.
You can find more details in the go mod documentation and the Go Modules Wiki.

Pull requests should only modify go.mod and go.sum where it is related to your change, be it a bugfix or a new feature.
Apart from that, these files should only be modified by Pull Requests whose only purpose is to update dependencies.

The go.mod, go.sum update needs to be justified as part of the PR description, and must be verified by the reviewers and/or merger to always reference an existing upstream commit.

API v1

The API is documented by swagger and is based on the GitHub API.

GitHub API compatibility

Gitea's API should use the same endpoints and fields as the GitHub API as far as possible, unless there are good reasons to deviate.
If Gitea provides functionality that GitHub does not, a new endpoint can be created.
If information is provided by Gitea that is not provided by the GitHub API, a new field can be used that doesn't collide with any GitHub fields.
Updating an existing API should not remove existing fields unless there is a really good reason to do so.
The same applies to status responses. If you notice a problem, feel free to leave a comment in the code for future refactoring to API v2 (which is currently not planned).

Adding/Maintaining API routes

All expected results (errors, success, fail messages) must be documented (example).
All JSON input types must be defined as a struct in modules/structs/ (example)
and referenced in routers/api/v1/swagger/options.go.
They can then be used like this example.
All JSON responses must be defined as a struct in modules/structs/ (example)
and referenced in its category in routers/api/v1/swagger/ (example)
They can be used like this example.

When to use what HTTP method

In general, HTTP methods are chosen as follows:

GET endpoints return the requested object(s) and status OK (200)
DELETE endpoints return the status No Content (204) and no content either
POST endpoints are used to create new objects (e.g. a User) and return the status Created (201) and the created object
PUT endpoints are used to add/assign existing Objects (e.g. a user to a team) and return the status No Content (204) and no content either
PATCH endpoints are used to edit/change an existing object and return the changed object and the status OK (200)

Requirements for API routes

All parameters of endpoints changing/editing an object must be optional (except the ones to identify the object, which are required).

Endpoints returning lists must

support pagination (page & limit options in query)
set X-Total-Count header via SetTotalCountHeader (example)

4.2 KiB Raw Permalink Blame History