From e8433b7fe6dd1dfa5ecf0633568cc3e34caeb0f9 Mon Sep 17 00:00:00 2001 From: Lunny Xiao Date: Thu, 23 Mar 2023 23:18:24 +0800 Subject: Restructure documentation. Now the documentation has installation, administration, usage, development, contributing the 5 main parts (#23629) - **Installation**: includes how to install Gitea and related other tools, also includes upgrade Gitea - **Administration**: includes how to configure Gitea, customize Gitea and manage Gitea instance out of Gitea admin UI - **Usage**: includes how to use Gitea's functionalities. A sub documentation is about packages, in future we could also include CI/CD and others. - **Development**: includes how to integrate with Gitea's API, how to develop new features within Gitea - **Contributing**: includes how to contribute code to Gitea repositories. After this is merged, I think we can have a sub-documentation of `Usage` part named `Actions` to describe how to use Gitea actions --------- Co-authored-by: John Olheiser --- docs/content/doc/developers/api-usage.en-us.md | 137 -------- docs/content/doc/developers/api-usage.zh-cn.md | 71 ---- .../doc/developers/guidelines-backend.en-us.md | 123 ------- .../doc/developers/guidelines-frontend.en-us.md | 136 -------- .../doc/developers/guidelines-refactoring.en-us.md | 51 --- .../doc/developers/hacking-on-gitea.en-us.md | 379 --------------------- .../doc/developers/hacking-on-gitea.zh-cn.md | 349 ------------------- docs/content/doc/developers/integrations.en-us.md | 45 --- docs/content/doc/developers/integrations.zh-tw.md | 22 -- docs/content/doc/developers/migrations.en-us.md | 41 --- docs/content/doc/developers/migrations.zh-tw.md | 39 --- .../doc/developers/oauth2-provider.en-us.md | 139 -------- .../doc/developers/oauth2-provider.zh-tw.md | 96 ------ 13 files changed, 1628 deletions(-) delete mode 100644 docs/content/doc/developers/api-usage.en-us.md delete mode 100644 docs/content/doc/developers/api-usage.zh-cn.md delete mode 100644 docs/content/doc/developers/guidelines-backend.en-us.md delete mode 100644 docs/content/doc/developers/guidelines-frontend.en-us.md delete mode 100644 docs/content/doc/developers/guidelines-refactoring.en-us.md delete mode 100644 docs/content/doc/developers/hacking-on-gitea.en-us.md delete mode 100644 docs/content/doc/developers/hacking-on-gitea.zh-cn.md delete mode 100644 docs/content/doc/developers/integrations.en-us.md delete mode 100644 docs/content/doc/developers/integrations.zh-tw.md delete mode 100644 docs/content/doc/developers/migrations.en-us.md delete mode 100644 docs/content/doc/developers/migrations.zh-tw.md delete mode 100644 docs/content/doc/developers/oauth2-provider.en-us.md delete mode 100644 docs/content/doc/developers/oauth2-provider.zh-tw.md (limited to 'docs/content/doc/developers') diff --git a/docs/content/doc/developers/api-usage.en-us.md b/docs/content/doc/developers/api-usage.en-us.md deleted file mode 100644 index a7b87f8f08..0000000000 --- a/docs/content/doc/developers/api-usage.en-us.md +++ /dev/null @@ -1,137 +0,0 @@ ---- -date: "2018-06-24:00:00+02:00" -title: "API Usage" -slug: "api-usage" -weight: 40 -toc: false -draft: false -menu: - sidebar: - parent: "developers" - name: "API Usage" - weight: 40 - identifier: "api-usage" ---- - -# API Usage - -**Table of Contents** - -{{< toc >}} - -## Enabling/configuring API access - -By default, `ENABLE_SWAGGER` is true, and -`MAX_RESPONSE_ITEMS` is set to 50. See [Config Cheat -Sheet](https://docs.gitea.io/en-us/config-cheat-sheet/) for more -information. - -## Authentication - -Gitea supports these methods of API authentication: - -- HTTP basic authentication -- `token=...` parameter in URL query string -- `access_token=...` parameter in URL query string -- `Authorization: token ...` header in HTTP headers - -All of these methods accept the same API key token type. You can -better understand this by looking at the code -- as of this writing, -Gitea parses queries and headers to find the token in -[modules/auth/auth.go](https://github.com/go-gitea/gitea/blob/6efdcaed86565c91a3dc77631372a9cc45a58e89/modules/auth/auth.go#L47). - -## Generating and listing API tokens - -A new token can be generated with a `POST` request to -`/users/:name/tokens`. - -Note that `/users/:name/tokens` is a special endpoint and requires you -to authenticate using `BasicAuth` and a password, as follows: - -```sh -$ curl -H "Content-Type: application/json" -d '{"name":"test"}' -u username:password https://gitea.your.host/api/v1/users//tokens -{"id":1,"name":"test","sha1":"9fcb1158165773dd010fca5f0cf7174316c3e37d","token_last_eight":"16c3e37d"} -``` - -The ``sha1`` (the token) is only returned once and is not stored in -plain-text. It will not be displayed when listing tokens with a `GET` -request; e.g. - -```sh -$ curl --url https://yourusername:password@gitea.your.host/api/v1/users//tokens -[{"name":"test","sha1":"","token_last_eight:"........":},{"name":"dev","sha1":"","token_last_eight":"........"}] -``` - -To use the API with basic authentication with two factor authentication -enabled, you'll need to send an additional header that contains the one -time password (6 digitrotating token). -An example of the header is `X-Gitea-OTP: 123456` where `123456` -is where you'd place the code from your authenticator. -Here is how the request would look like in curl: - -```sh -$ curl -H "X-Gitea-OTP: 123456" --url https://yourusername:yourpassword@gitea.your.host/api/v1/users/yourusername/tokens -``` - -You can also create an API key token via your Gitea installation's web -interface: `Settings | Applications | Generate New Token`. - -## OAuth2 Provider - -Access tokens obtained from Gitea's [OAuth2 provider](https://docs.gitea.io/en-us/oauth2-provider) are accepted by these methods: - -- `Authorization bearer ...` header in HTTP headers -- `token=...` parameter in URL query string -- `access_token=...` parameter in URL query string - -### More on the `Authorization:` header - -For historical reasons, Gitea needs the word `token` included before -the API key token in an authorization header, like this: - -```sh -Authorization: token 65eaa9c8ef52460d22a93307fe0aee76289dc675 -``` - -In a `curl` command, for instance, this would look like: - -```sh -curl "http://localhost:4000/api/v1/repos/test1/test1/issues" \ - -H "accept: application/json" \ - -H "Authorization: token 65eaa9c8ef52460d22a93307fe0aee76289dc675" \ - -H "Content-Type: application/json" -d "{ \"body\": \"testing\", \"title\": \"test 20\"}" -i -``` - -As mentioned above, the token used is the same one you would use in -the `token=` string in a GET request. - -## Pagination - -The API supports pagination. The `page` and `limit` parameters are used to specify the page number and the number of items per page. As well, the `Link` header is returned with the next, previous, and last page links if there are more than one pages. The `x-total-count` is also returned to indicate the total number of items. - -```sh -curl -v "http://localhost/api/v1/repos/search?limit=1" -... -< link: ; rel="next",; rel="last" -... -< x-total-count: 5252 -``` - -## API Guide: - -API Reference guide is auto-generated by swagger and available on: -`https://gitea.your.host/api/swagger` -or on the -[Gitea demo instance](https://try.gitea.io/api/swagger) - -The OpenAPI document is at: -`https://gitea.your.host/swagger.v1.json` - -## Sudo - -The API allows admin users to sudo API requests as another user. Simply add either a `sudo=` parameter or `Sudo:` request header with the username of the user to sudo. - -## SDKs - -- [Official go-sdk](https://gitea.com/gitea/go-sdk) -- [more](https://gitea.com/gitea/awesome-gitea#user-content-sdk) diff --git a/docs/content/doc/developers/api-usage.zh-cn.md b/docs/content/doc/developers/api-usage.zh-cn.md deleted file mode 100644 index c998361115..0000000000 --- a/docs/content/doc/developers/api-usage.zh-cn.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -date: "2018-06-24:00:00+02:00" -title: "API 使用指南" -slug: "api-usage" -weight: 40 -toc: false -draft: false -menu: - sidebar: - parent: "developers" - name: "API 使用指南" - weight: 40 - identifier: "api-usage" ---- - -# Gitea API 使用指南 - -## 开启/配置 API 访问 - -通常情况下， `ENABLE_SWAGGER` 默认开启并且参数 `MAX_RESPONSE_ITEMS` 默认为 50。您可以从 [Config Cheat -Sheet](https://docs.gitea.io/en-us/config-cheat-sheet/) 中获取更多配置相关信息。 - -## 通过 API 认证 - -Gitea 支持以下几种 API 认证方式： - -- HTTP basic authentication 方式 -- 通过指定 `token=...` URL 查询参数方式 -- 通过指定 `access_token=...` URL 查询参数方式 -- 通过指定 `Authorization: token ...` HTTP header 方式 - -以上提及的认证方法接受相同的 apiKey token 类型，您可以在编码时通过查阅代码更好地理解这一点。 -Gitea 调用解析查询参数以及头部信息来获取 token 的代码可以在 [modules/auth/auth.go](https://github.com/go-gitea/gitea/blob/6efdcaed86565c91a3dc77631372a9cc45a58e89/modules/auth/auth.go#L47) 中找到。 - -您可以通过您的 gitea web 界面来创建 apiKey token： -`Settings | Applications | Generate New Token`. - -### 关于 `Authorization:` header - -由于一些历史原因，Gitea 需要在 header 的 apiKey token 里引入前缀 `token`，类似于如下形式： - -``` -Authorization: token 65eaa9c8ef52460d22a93307fe0aee76289dc675 -``` - -以 `curl` 命令为例，它会以如下形式携带在请求中： - -``` -curl "http://localhost:4000/api/v1/repos/test1/test1/issues" \ - -H "accept: application/json" \ - -H "Authorization: token 65eaa9c8ef52460d22a93307fe0aee76289dc675" \ - -H "Content-Type: application/json" -d "{ \"body\": \"testing\", \"title\": \"test 20\"}" -i -``` - -正如上例所示，您也可以在 GET 请求中使用同一个 token 并以 `token=` 的查询参数形式携带 token 来进行认证。 - -## 通过 API 列出您发布的令牌 - -`/users/:name/tokens` 是一个特殊的接口，需要您使用 basic authentication 进行认证，具体原因在 issue 中 -[#3842](https://github.com/go-gitea/gitea/issues/3842#issuecomment-397743346) 有所提及，使用方法如下所示： - -### 使用 Basic authentication 认证： - -``` -$ curl --url https://yourusername:yourpassword@gitea.your.host/api/v1/users/yourusername/tokens -[{"name":"test","sha1":"..."},{"name":"dev","sha1":"..."}] -``` - -## 使用 Sudo 方式请求 API - -此 API 允许管理员借用其他用户身份进行 API 请求。只需在请求中指定查询参数 `sudo=` 或是指定 header 中的 `Sudo:` 为需要使用的用户 username 即可。 diff --git a/docs/content/doc/developers/guidelines-backend.en-us.md b/docs/content/doc/developers/guidelines-backend.en-us.md deleted file mode 100644 index f35111522f..0000000000 --- a/docs/content/doc/developers/guidelines-backend.en-us.md +++ /dev/null @@ -1,123 +0,0 @@ ---- -date: "2021-11-01T23:41:00+08:00" -title: "Guidelines for Backend Development" -slug: "guidelines-backend" -weight: 20 -toc: false -draft: false -menu: - sidebar: - parent: "developers" - name: "Guidelines for Backend" - weight: 20 - identifier: "guidelines-backend" ---- - -# Guidelines for Backend Development - -**Table of Contents** - -{{< toc >}} - -## Background - -Gitea uses Golang as the backend programming language. It uses many third-party packages and also write some itself. -For example, Gitea uses [Chi](https://github.com/go-chi/chi) as basic web framework. [Xorm](https://xorm.io) is an ORM framework that is used to interact with the database. -So it's very important to manage these packages. Please take the below guidelines before you start to write backend code. - -## Package Design Guideline - -### Packages List - -To maintain understandable code and avoid circular dependencies it is important to have a good code structure. The Gitea backend is divided into the following parts: - -- `build`: Scripts to help build Gitea. -- `cmd`: All Gitea actual sub commands includes web, doctor, serv, hooks, admin and etc. `web` will start the web service. `serv` and `hooks` will be invoked by Git or OpenSSH. Other sub commands could help to maintain Gitea. -- `tests`: Common test utility functions - - `tests/integration`: Integration tests, to test back-end regressions - - `tests/e2e`: E2e tests, to test test front-end <> back-end compatibility and visual regressions. -- `models`: Contains the data structures used by xorm to construct database tables. It also contains functions to query and update the database. Dependencies to other Gitea code should be avoided. You can make exceptions in cases such as logging. - - `models/db`: Basic database operations. All other `models/xxx` packages should depend on this package. The `GetEngine` function should only be invoked from `models/`. - - `models/fixtures`: Sample data used in unit tests and integration tests. One `yml` file means one table which will be loaded into database when beginning the tests. - - `models/migrations`: Stores database migrations between versions. PRs that change a database structure **MUST** also have a migration step. -- `modules`: Different modules to handle specific functionality in Gitea. Work in Progress: Some of them should be moved to `services`, in particular those that depend on models because they rely on the database. - - `modules/setting`: Store all system configurations read from ini files and has been referenced by everywhere. But they should be used as function parameters when possible. - - `modules/git`: Package to interactive with `Git` command line or Gogit package. -- `public`: Compiled frontend files (javascript, images, css, etc.) -- `routers`: Handling of server requests. As it uses other Gitea packages to serve the request, other packages (models, modules or services) must not depend on routers. - - `routers/api` Contains routers for `/api/v1` aims to handle RESTful API requests. - - `routers/install` Could only respond when system is in INSTALL mode (INSTALL_LOCK=false). - - `routers/private` will only be invoked by internal sub commands, especially `serv` and `hooks`. - - `routers/web` will handle HTTP requests from web browsers or Git SMART HTTP protocols. -- `services`: Support functions for common routing operations or command executions. Uses `models` and `modules` to handle the requests. -- `templates`: Golang templates for generating the html output. - -### Package Dependencies - -Since Golang doesn't support import cycles, we have to decide the package dependencies carefully. There are some levels between those packages. Below is the ideal package dependencies direction. - -`cmd` -> `routers` -> `services` -> `models` -> `modules` - -From left to right, left packages could depend on right packages, but right packages MUST not depend on left packages. The sub packages on the same level could depend on according this level's rules. - -**NOTICE** - -Why do we need database transactions outside of `models`? And how? -Some actions should allow for rollback when database record insertion/update/deletion failed. -So services must be allowed to create a database transaction. Here is some example, - -```go -// services/repository/repository.go -func CreateXXXX() error { - return db.WithTx(func(ctx context.Context) error { - e := db.GetEngine(ctx) - // do something, if err is returned, it will rollback automatically - if err := issues.UpdateIssue(ctx, repoID); err != nil { - // ... - return err - } - // ... - return nil - }) -} -``` - -You should **not** use `db.GetEngine(ctx)` in `services` directly, but just write a function under `models/`. -If the function will be used in the transaction, just let `context.Context` as the function's first parameter. - -```go -// models/issues/issue.go -func UpdateIssue(ctx context.Context, repoID int64) error { - e := db.GetEngine(ctx) - - // ... -} -``` - -### Package Name - -For the top level package, use a plural as package name, i.e. `services`, `models`, for sub packages, use singular, -i.e. `services/user`, `models/repository`. - -### Import Alias - -Since there are some packages which use the same package name, it is possible that you find packages like `modules/user`, `models/user`, and `services/user`. When these packages are imported in one Go file, it's difficult to know which package we are using and if it's a variable name or an import name. So, we always recommend to use import aliases. To differ from package variables which are commonly in camelCase, just use **snake_case** for import aliases. -i.e. `import user_service "code.gitea.io/gitea/services/user"` - -### Important Gotchas - -- Never write `x.Update(exemplar)` without an explicit `WHERE` clause: - - This will cause all rows in the table to be updated with the non-zero values of the exemplar - including IDs. - - You should usually write `x.ID(id).Update(exemplar)`. -- If during a migration you are inserting into a table using `x.Insert(exemplar)` where the ID is preset: - - You will need to ``SET IDENTITY_INSERT `table` ON`` for the MSSQL variant (the migration will fail otherwise) - - However, you will also need to update the id sequence for postgres - the migration will silently pass here but later insertions will fail: - ``SELECT setval('table_name_id_seq', COALESCE((SELECT MAX(id)+1 FROM `table_name`), 1), false)`` - -### Future Tasks - -Currently, we are creating some refactors to do the following things: - -- Correct that codes which doesn't follow the rules. -- There are too many files in `models`, so we are moving some of them into a sub package `models/xxx`. -- Some `modules` sub packages should be moved to `services` because they depend on `models`. diff --git a/docs/content/doc/developers/guidelines-frontend.en-us.md b/docs/content/doc/developers/guidelines-frontend.en-us.md deleted file mode 100644 index e2bdc7adcb..0000000000 --- a/docs/content/doc/developers/guidelines-frontend.en-us.md +++ /dev/null @@ -1,136 +0,0 @@ ---- -date: "2021-10-13T16:00:00+02:00" -title: "Guidelines for Frontend Development" -slug: "guidelines-frontend" -weight: 20 -toc: false -draft: false -menu: - sidebar: - parent: "developers" - name: "Guidelines for Frontend" - weight: 20 - identifier: "guidelines-frontend" ---- - -# Guidelines for Frontend Development - -**Table of Contents** - -{{< toc >}} - -## Background - -Gitea uses [Fomantic-UI](https://fomantic-ui.com/introduction/getting-started.html) (based on [jQuery](https://api.jquery.com)) and [Vue3](https://vuejs.org/) for its frontend. - -The HTML pages are rendered by [Go HTML Template](https://pkg.go.dev/html/template). - -The source files can be found in the following directories: - -* **CSS styles:** `web_src/css/` -* **JavaScript files:** `web_src/js/` -* **Vue components:** `web_src/js/components/` -* **Go HTML templates:** `templates/` - -## General Guidelines - -We recommend [Google HTML/CSS Style Guide](https://google.github.io/styleguide/htmlcssguide.html) and [Google JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html) - -### Gitea specific guidelines: - -1. Every feature (Fomantic-UI/jQuery module) should be put in separate files/directories. -2. HTML ids and classes should use kebab-case, it's preferred to contain 2-3 feature related keywords. -3. HTML ids and classes used in JavaScript should be unique for the whole project, and should contain 2-3 feature related keywords. We recommend to use the `js-` prefix for classes that are only used in JavaScript. -4. CSS styling for classes provided by frameworks should not be overwritten. Always use new class names with 2-3 feature related keywords to overwrite framework styles. Gitea's helper CSS classes in `helpers.less` could be helpful. -5. The backend can pass complex data to the frontend by using `ctx.PageData["myModuleData"] = map[]{}`, but do not expose whole models to the frontend to avoid leaking sensitive data. -6. Simple pages and SEO-related pages use Go HTML Template render to generate static Fomantic-UI HTML output. Complex pages can use Vue3. -7. Clarify variable types, prefer `elem.disabled = true` instead of `elem.setAttribute('disabled', 'anything')`, prefer `$el.prop('checked', var === 'yes')` instead of `$el.prop('checked', var)`. -8. Use semantic elements, prefer `