diff options
Diffstat (limited to 'docs/content/doc/developers')
| -rw-r--r-- | docs/content/doc/developers/api-usage.en-us.md | 137 | ||||
| -rw-r--r-- | docs/content/doc/developers/api-usage.zh-cn.md | 71 | ||||
| -rw-r--r-- | docs/content/doc/developers/guidelines-backend.en-us.md | 123 | ||||
| -rw-r--r-- | docs/content/doc/developers/guidelines-frontend.en-us.md | 136 | ||||
| -rw-r--r-- | docs/content/doc/developers/guidelines-refactoring.en-us.md | 51 | ||||
| -rw-r--r-- | docs/content/doc/developers/hacking-on-gitea.en-us.md | 379 | ||||
| -rw-r--r-- | docs/content/doc/developers/hacking-on-gitea.zh-cn.md | 349 | ||||
| -rw-r--r-- | docs/content/doc/developers/integrations.en-us.md | 45 | ||||
| -rw-r--r-- | docs/content/doc/developers/integrations.zh-tw.md | 22 | ||||
| -rw-r--r-- | docs/content/doc/developers/migrations.en-us.md | 41 | ||||
| -rw-r--r-- | docs/content/doc/developers/migrations.zh-tw.md | 39 | ||||
| -rw-r--r-- | docs/content/doc/developers/oauth2-provider.en-us.md | 139 | ||||
| -rw-r--r-- | docs/content/doc/developers/oauth2-provider.zh-tw.md | 96 |
13 files changed, 0 insertions, 1628 deletions
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/<username>/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/<username>/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: <http://localhost/api/v1/repos/search?limit=1&page=2>; rel="next",<http://localhost/api/v1/repos/search?limit=1&page=5252>; 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 `<button class="ui button">` instead of `<div class="ui button">`. -9. Avoid unnecessary `!important` in CSS, add comments to explain why it's necessary if it can't be avoided. -10. Avoid mixing different events in one event listener, prefer to use individual event listeners for every event. -11. Custom event names are recommended to use `ce-` prefix. - -### Accessibility / ARIA - -In history, Gitea heavily uses Fomantic UI which is not an accessibility-friendly framework. -Gitea uses some patches to make Fomantic UI more accessible (see the `aria.js` and `aria.md`), -but there are still many problems which need a lot of work and time to fix. - -### Framework Usage - -Mixing different frameworks together is discouraged, it makes the code difficult to be maintained. -A JavaScript module should follow one major framework and follow the framework's best practice. - -Recommended implementations: - -* Vue + Vanilla JS -* Fomantic-UI (jQuery) -* Vanilla JS - -Discouraged implementations: - -* Vue + Fomantic-UI (jQuery) -* jQuery + Vanilla JS - -To make UI consistent, Vue components can use Fomantic-UI CSS classes. -Although mixing different frameworks is discouraged, -it should also work if the mixing is necessary and the code is well-designed and maintainable. - -### `async` Functions - -Only mark a function as `async` if and only if there are `await` calls -or `Promise` returns inside the function. - -It's not recommended to use `async` event listeners, which may lead to problems. -The reason is that the code after await is executed outside the event dispatch. -Reference: https://github.com/github/eslint-plugin-github/blob/main/docs/rules/async-preventdefault.md - -If an event listener must be `async`, the `e.preventDefault()` should be before any `await`, -it's recommended to put it at the beginning of the function. - -If we want to call an `async` function in a non-async context, -it's recommended to use `const _promise = asyncFoo()` to tell readers -that this is done by purpose, we want to call the async function and ignore the Promise. -Some lint rules and IDEs also have warnings if the returned Promise is not handled. - -### HTML Attributes and `dataset` - -The usage of `dataset` is forbidden, its camel-casing behaviour makes it hard to grep for attributes. -However, there are still some special cases, so the current guideline is: - -* For legacy code: - * `$.data()` should be refactored to `$.attr()`. - * `$.data()` can be used to bind some non-string data to elements in rare cases, but it is highly discouraged. - -* For new code: - * `node.dataset` should not be used, use `node.getAttribute` instead. - * never bind any user data to a DOM node, use a suitable design pattern to describe the relation between node and data. - -### Show/Hide Elements - -* Vue components are recommended to use `v-if` and `v-show` to show/hide elements. -* Go template code should use Gitea's `.gt-hidden` and `showElem()/hideElem()/toggleElem()`, see more details in `.gt-hidden`'s comment. - -### Styles and Attributes in Go HTML Template - -It's recommended to use: - -```html -<div class="gt-name1 gt-name2 {{if .IsFoo}}gt-foo{{end}}" {{if .IsFoo}}data-foo{{end}}></div> -``` - -instead of: - -```html -<div class="gt-name1 gt-name2{{if .IsFoo}} gt-foo{{end}}"{{if .IsFoo}} data-foo{{end}}></div> -``` - -to make the code more readable. - -### Legacy Code - -A lot of legacy code already existed before this document's written. It's recommended to refactor legacy code to follow the guidelines. - -### Vue3 and JSX - -Gitea is using Vue3 now. We decided not to introduce JSX to keep the HTML and the JavaScript code separated. diff --git a/docs/content/doc/developers/guidelines-refactoring.en-us.md b/docs/content/doc/developers/guidelines-refactoring.en-us.md deleted file mode 100644 index 29025f25f7..0000000000 --- a/docs/content/doc/developers/guidelines-refactoring.en-us.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -date: "2023-02-14T00:00:00+00:00" -title: "Guidelines for Refactoring" -slug: "guidelines-refactoring" -weight: 20 -toc: false -draft: false -menu: - sidebar: - parent: "developers" - name: "Guidelines for Refactoring" - weight: 20 - identifier: "guidelines-refactoring" ---- - -# Guidelines for Refactoring - -**Table of Contents** - -{{< toc >}} - -## Background - -Since the first line of code was written at Feb 12, 2014, Gitea has grown to be a large project. -As a result, the codebase has become larger and larger. The larger the codebase is, the more difficult it is to maintain. -A lot of outdated mechanisms exist, a lot of frameworks are mixed together, some legacy code might cause bugs and block new features. -To make the codebase more maintainable and make Gitea better, developers should keep in mind to use modern mechanisms to refactor the old code. - -This document is a collection of guidelines for refactoring the codebase. - -## Refactoring Suggestions - -* Design more about the future, but not only resolve the current problem. -* Reduce ambiguity, reduce conflicts, improve maintainability. -* Describe the refactoring, for example: - * Why the refactoring is needed. - * How the legacy problems would be solved. - * What's the Pros/Cons of the refactoring. -* Only do necessary changes, keep the old logic as much as possible. -* Introduce some intermediate steps to make the refactoring easier to review, a complete refactoring plan could be done in several PRs. -* If there is any divergence, the TOC(Technical Oversight Committee) should be involved to help to make decisions. -* Add necessary tests to make sure the refactoring is correct. -* Non-bug refactoring is preferred to be done at the beginning of a milestone, it would be easier to find problems before the release. - -## Reviewing & Merging Suggestions - -* A refactoring PR shouldn't be kept open for a long time (usually 7 days), it should be reviewed as soon as possible. -* A refactoring PR should be merged as soon as possible, it should not be blocked by other PRs. -* If there is no objection from TOC, a refactoring PR could be merged after 7 days with one core member's approval (not the author). -* Tolerate some dirty/hacky intermediate steps if the final result is good. -* Tolerate some regression bugs if the refactoring is necessary, fix bugs as soon as possible. diff --git a/docs/content/doc/developers/hacking-on-gitea.en-us.md b/docs/content/doc/developers/hacking-on-gitea.en-us.md deleted file mode 100644 index 3283240c98..0000000000 --- a/docs/content/doc/developers/hacking-on-gitea.en-us.md +++ /dev/null @@ -1,379 +0,0 @@ ---- -date: "2016-12-01T16:00:00+02:00" -title: "Hacking on Gitea" -slug: "hacking-on-gitea" -weight: 10 -toc: false -draft: false -menu: - sidebar: - parent: "developers" - name: "Hacking on Gitea" - weight: 10 - identifier: "hacking-on-gitea" ---- - -# Hacking on Gitea - -**Table of Contents** - -{{< toc >}} - -## Quickstart - -To get a quick working development environment you could use Gitpod. - -[](https://gitpod.io/#https://github.com/go-gitea/gitea) - -## Installing go - -You should [install go](https://golang.org/doc/install) and set up your go -environment correctly. - -Next, [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 {{< min-node-version >}} and the latest LTS version is recommended. - -**Note**: When executing make tasks that require external tools, like -`make watch-backend`, Gitea will automatically download and build these as -necessary. To be able to use these you must have the `"$GOPATH"/bin` directory -on the executable path. If you don't add the go bin directory to the -executable path you will have to manage this yourself. - -**Note 2**: Go version {{< min-go-version >}} or higher is required. -Gitea uses `gofmt` to format source code. However, the results of -`gofmt` can differ by the version of `go`. Therefore it is -recommended to install the version of Go that our continuous integration is -running. As of last update, the Go version should be {{< go-version >}}. - -## Installing Make - -Gitea makes heavy use of Make to automate tasks and improve development. This -guide covers how to install Make. - -### 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-bits version](http://www.equation.com/ftpdir/make/32/make.exe) - - [64-bits 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 you with an easy-to-use environment for building, installing and running native Windows software, it includes MinGW-w64. - - In MingGW-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 (eg: 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 attempting to build using make with Windows Command Prompt, you may run into issues. The above prompts (Git bash, or MinGW) are recommended, however if you only have command prompt (or potentially 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 -``` - -(Since the advent of go modules, it is no longer necessary to build go projects -from within the `$GOPATH`, hence 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 for 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 (Basic) - -Take a look at our -<a href='{{< relref "doc/installation/from-source.en-us.md" >}}'>instructions</a> -for <a href='{{< relref "doc/installation/from-source.en-us.md" >}}'>building -from source</a>. - -The simplest recommended way to build from source is: - -```bash -TAGS="bindata sqlite sqlite_unlock_notify" make build -``` - -The `build` target will execute both `frontend` and `backend` sub-targets. If the `bindata` tag is present, the frontend files will be compiled into the binary. It is recommended to leave out the tag when doing frontend development so that changes will be reflected. - -See `make help` for all available `make` targets. Also see [`.drone.yml`](https://github.com/go-gitea/gitea/blob/main/.drone.yml) 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 increased 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 code linters (including format check, code analysis and spell check). - -You should 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` are dependent on the version of `go` present. -You should run the same version of go that is on the continuous integration -server as mentioned above. - -### Working on JS and CSS - -Frontend development should follow [Guidelines for Frontend Development]({{< relref "doc/developers/guidelines-frontend.en-us.md" >}}) - -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 local ElasticSearch instance - -Start 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 defined in `build/generate-svg.js` into the output directory `public/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. To run it, Node.js and npm must be available. - -The same process can also be used to generate custom logo PNGs from a SVG source file by updating `assets/logo.svg` and running `make generate-images`. Omitting the `gitea` tag will update only the user-designated logo files. - -### Updating the API - -When creating new API routes or modifying existing API routes, you **MUST** -update and/or create [Swagger](https://swagger.io/docs/specification/2-0/what-is-swagger/) -documentation for these 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). -If you want more information about the Swagger structure, you can look at 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) - -You should be careful not to break the API for downstream users which depend -on a stable API. In general, this means additions are acceptable, but deletions -or fundamental changes to the API will be rejected. - -Once you have created or changed an API endpoint, please regenerate the Swagger -documentation using: - -```bash -make generate-swagger -``` - -You should validate your generated Swagger file and spell-check it with: - -```bash -make swagger-validate misspell-check -``` - -You should commit the changed swagger JSON file. The continuous integration -server will check that this has been done using: - -```bash -make swagger-check -``` - -**Note**: Please note you should 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 add information to `custom/conf/app.ini` -and to the -<a href='{{< relref "doc/advanced/config-cheat-sheet.en-us.md" >}}'>configuration cheat sheet</a> -found in `docs/content/doc/advanced/config-cheat-sheet.en-us.md` - -### Changing the logo - -When changing the Gitea logo SVG, you will need to run and commit the results -of: - -```bash -make generate-images -``` - -This will create the necessary Gitea favicon and others. - -### Database Migrations - -If you make breaking changes to any of the database persisted structs in the -`models/` directory, you will need to make 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 # with SQLite switched for the appropriate database -``` - -## Testing - -There are two types of test run by Gitea: Unit tests and Integration Tests. - -### Unit Tests - -Unit tests are covered by `*_test.go` in `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 will not and cannot completely test Gitea alone. Therefore, 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. - -Take a look at [`tests/integration/README.md`](https://github.com/go-gitea/gitea/blob/main/tests/integration/README.md) -for more information and how to run a single test. - -### Testing for a PR - -Our continuous integration will test the code passes its unit tests and that -all supported databases will pass integration test in a Docker environment. -Migration from several recent versions of Gitea will also be tested. - -Please submit your PR with additional tests and integration tests as -appropriate. - -## Documentation for the website - -Documentation for the website is found in `docs/`. If you change this you -can test your changes to ensure that they pass continuous integration using: - -```bash -# from the docs directory within Gitea -make trans-copy clean build -``` - -You will require a copy of [Hugo](https://gohugo.io/) to run this task. Please -note: this may generate a number of untracked Git objects, which will need to -be cleaned up. - -## Visual Studio Code - -A `launch.json` and `tasks.json` are provided within `contrib/ide/vscode` for -Visual Studio Code. Look at -[`contrib/ide/README.md`](https://github.com/go-gitea/gitea/blob/main/contrib/ide/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's temporary directory -and prevents Gitea from loading dynamic resources (eg: 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/or may be -able to help fix issues directly. - -Any PR requires two approvals from the Gitea maintainers and needs to pass the -continuous integration. Take a look at our -[`CONTRIBUTING.md`](https://github.com/go-gitea/gitea/blob/main/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. diff --git a/docs/content/doc/developers/hacking-on-gitea.zh-cn.md b/docs/content/doc/developers/hacking-on-gitea.zh-cn.md deleted file mode 100644 index 9c9141bf50..0000000000 --- a/docs/content/doc/developers/hacking-on-gitea.zh-cn.md +++ /dev/null @@ -1,349 +0,0 @@ ---- -date: "2016-12-01T16:00:00+02:00" -title: "玩转 Gitea" -slug: "hacking-on-gitea" -weight: 10 -toc: false -draft: false -menu: - sidebar: - parent: "developers" - name: "玩转 Gitea" - weight: 10 - identifier: "hacking-on-gitea" ---- - -# Hacking on Gitea - -**目录** - -{{< toc >}} - -## 快速入门 - -要获得快速工作的开发环境，您可以使用 Gitpod。 - -[](https://gitpod.io/#https://github.com/go-gitea/gitea) - -## 安装 Golang - -您需要 [安装 go]( https://golang.org/doc/install ) 并设置您的 go 环境。 - -接下来，[使用 npm 安装 Node.js](https://nodejs.org/en/download/) ，这是构建 -JavaScript 和 CSS 文件的必要工具。最低支持的 Node.js 版本是 {{< min-node-version >}} -并且推荐使用最新的 LTS 版本。 - -**注意** ：当执行需要外部工具的 make 任务时，比如 -`make watch-backend`，Gitea 会自动下载并构建这些必要的组件。为了能够使用这些，你必须 -将 `"$GOPATH"/bin` 目录加入到可执行路径上。如果你不把go bin目录添加到可执行路径你必须手动 -指定可执行程序路径。 - -**注意2** ：Go版本 {{< min-go-version >}} 或更高版本是必须的。Gitea 使用 `gofmt` 来 -格式化源代码。然而，`gofmt` 的结果可能因 `go` 的版本而有差异。因此推荐安装我们持续集成使用 -的 Go版本。截至上次更新，Go 版本应该是 {{< go-version >}}。 - -## 安装 Make - -Gitea 大量使用 `Make` 来自动化任务和改进开发。本指南涵盖了如何安装 Make。 - -### 在 Linux 上 - -使用包管理器安装。 - -在 Ubuntu/Debian 上： - -```bash -sudo apt-get install make -``` - -在 Fedora/RHEL/CentOS 上： - -```bash -sudo yum install make -``` - -### 在 Windows 上 - -Make 的这三个发行版都可以在 Windows 上运行： - -- [单个二进制构建]( http://www.equation.com/servlet/equation.cmd?fa=make )。复制到某处并添加到 `PATH`。 - - [32 位版本](http://www.equation.com/ftpdir/make/32/make.exe) - - [64 位版本](http://www.equation.com/ftpdir/make/64/make.exe) -- [MinGW-w64](https://www.mingw-w64.org) / [MSYS2](https://www.msys2.org/)。 - - MSYS2 是一个工具和库的集合，为您提供一个易于使用的环境来构建、安装和运行本机 Windows 软件，它包括 MinGW-w64。 - - 在 MingGW-w64 中，二进制文件称为 `mingw32-make.exe` 而不是 `make.exe`。将 `bin` 文件夹添加到 `PATH`。 - - 在 MSYS2 中，您可以直接使用 `make`。请参阅 [MSYS2 移植](https://www.msys2.org/wiki/Porting/)。 - - 要使用 CGO_ENABLED（例如：SQLite3）编译 Gitea，您可能需要使用 [tdm-gcc](https://jmeubank.github.io/tdm-gcc/) 而不是 MSYS2 gcc，因为 MSYS2 gcc 标头缺少一些 Windows -只有 CRT 函数像 _beginthread 一样。 -- [Chocolatey包管理器]( https://chocolatey.org/packages/make )。运行`choco install make` - -**注意** ：如果您尝试在 Windows 命令提示符下使用 make 进行构建，您可能会遇到问题。建议使用上述提示（Git bash 或 MinGW），但是如果您只有命令提示符（或可能是 PowerShell），则可以使用 [set](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/set_1) 命令，例如 `set TAGS=bindata`。 - -## 下载并克隆 Gitea 源代码 - -获取源代码的推荐方法是使用 `git clone`。 - -```bash -git clone https://github.com/go-gitea/gitea -``` - -（自从go modules出现后，不再需要构建 go 项目从 `$GOPATH` 中获取，因此不再推荐使用 `go get` 方法。） - -## 派生 Gitea - -如上所述下载主要的 Gitea 源代码。然后，派生 [Gitea 仓库](https://github.com/go-gitea/gitea)， -并为您的本地仓库切换 git 远程源，或添加另一个远程源： - -```bash -# 将原来的 Gitea origin 重命名为 upstream -git remote rename origin upstream -git remote add origin "git@github.com:$GITHUB_USERNAME/gitea.git" -git fetch --all --prune -``` - -或者： - -```bash -# 为我们的 fork 添加新的远程 -git remote add "$FORK_NAME" "git@github.com:$GITHUB_USERNAME/gitea.git" -git fetch --all --prune -``` - -为了能够创建合并请求，应将分叉存储库添加为 Gitea 本地仓库的远程，否则无法推送更改。 - -## 构建 Gitea（基本） - -看看我们的 -<a href='{{ < relref "doc/installation/from-source.en-us.md" > }}'>说明</a> -关于如何 <a href='{{ < relref "doc/installation/from-source.en-us.md" > }}'>从源代码构建</a> 。 - -从源代码构建的最简单推荐方法是： - -```bash -TAGS="bindata sqlite sqlite_unlock_notify" make build -``` - -`build` 目标将同时执行 `frontend` 和 `backend` 子目标。如果存在 `bindata` 标签，资源文件将被编译成二进制文件。建议在进行前端开发时省略 `bindata` 标签，以便实时反映更改。 - -有关所有可用的 `make` 目标，请参阅 `make help`。另请参阅 [`.drone.yml`](https://github.com/go-gitea/gitea/blob/main/.drone.yml) 以了解我们的持续集成是如何工作的。 - -## 持续构建 - -要在源文件更改时运行并持续构建： - -```bash -# 对于前端和后端 -make watch - -# 或者：只看前端文件（html/js/css） -make watch-frontend - -# 或者：只看后端文件 (go) -make watch-backend -``` - -在 macOS 上，监视所有后端源文件可能会达到默认的打开文件限制，这可以通过当前 shell 的 `ulimit -n 12288` 或所有未来 shell 的 shell 启动文件来增加。 - -### 格式化、代码分析和拼写检查 - -我们的持续集成将拒绝未通过代码检查（包括格式检查、代码分析和拼写检查）的 PR。 - -你应该格式化你的代码： - -```bash -make fmt -``` - -并检查源代码： - -```bash -# lint 前端和后端代码 -make lint -# 仅 lint 后端代码 -make lint-backend -``` - -**注意** ：`gofmt` 的结果取决于 `go` 的版本。您应该运行与持续集成相同的 go 版本。 - -### 处理 JS 和 CSS - -前端开发应遵循 [Guidelines for Frontend Development]({{ < 相关参考 "doc/developers/guidelines-frontend.en-us.md" > }}) - -要使用前端资源构建，请使用上面提到的“watch-frontend”目标或只构建一次： - -```bash -make build && ./gitea -``` - -在提交之前，确保 linters 通过： - -```bash -make lint-frontend -``` - -### 配置本地 ElasticSearch 实例 - -使用 docker 启动本地 ElasticSearch 实例： - -```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 -``` - -配置`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 -``` - -### 构建和添加 SVGs - -SVG 图标是使用 `make svg` 目标构建的，该目标将 `build/generate-svg.js` 中定义的图标源编译到输出目录 `public/img/svg` 中。可以在 `web_src/svg` 目录中添加自定义图标。 - -### 构建 Logo - -Gitea Logo的 PNG 和 SVG 版本是使用 `TAGS="gitea" make generate-images` 目标从单个 SVG 源文件 assets/logo.svg 构建的。要运行它，Node.js 和 npm 必须可用。 - -通过更新 `assets/logo.svg` 并运行 `make generate-images`，同样的过程也可用于从 SVG 源文件生成自定义 Logo PNG。忽略 gitea 编译选项将仅更新用户指定的 LOGO 文件。 - -### 更新 API - -创建新的 API 路由或修改现有的 API 路由时，您**必须** -更新和/或创建 [Swagger](https://swagger.io/docs/specification/2-0/what-is-swagger/) -这些使用 [go-swagger](https://goswagger.io/) 评论的文档。 -[规范]( https://goswagger.io/use/spec.html#annotation-syntax )中描述了这些注释的结构。 -如果您想了解更多有关 Swagger 结构的信息，可以查看 -[Swagger 2.0 文档](https://swagger.io/docs/specification/2-0/basic-structure/) -或与添加新 API 端点的先前 PR 进行比较，例如 [PR #5483](https://github.com/go-gitea/gitea/pull/5843/files#diff-2e0a7b644cf31e1c8ef7d76b444fe3aaR20) - -您应该注意不要破坏下游用户依赖的 API。在稳定的 API 上，一般来说添加是可以接受的，但删除 -或对 API 进行根本性更改将会被拒绝。 - -创建或更改 API 端点后，请用以下命令重新生成 Swagger 文档： - -```bash -make generate-swagger -``` - -您应该验证生成的 Swagger 文件并使用以下命令对其进行拼写检查： - -```bash -make swagger-validate misspell-check -``` - -您应该提交更改后的 swagger JSON 文件。持续集成服务器将使用以下方法检查是否已完成： - -```bash -make swagger-check -``` - -**注意** ：请注意，您应该使用 Swagger 2.0 文档，而不是 OpenAPI 3 文档。 - -### 创建新的配置选项 - -创建新的配置选项时，将它们添加到 `modules/setting` 的对应文件。您应该将信息添加到 `custom/conf/app.ini` -并到 <a href = '{{ < relref "doc/advanced/config-cheat-sheet.en-us.md" > }}'>配置备忘单</a> -在 `docs/content/doc/advanced/config-cheat-sheet.en-us.md` 中找到 - -### 更改Logo - -更改 Gitea Logo SVG 时，您将需要运行并提交结果的： - -```bash -make generate-images -``` - -这将创建必要的 Gitea 图标和其他图标。 - -### 数据库迁移 - -如果您对数据库中的任何数据库持久结构进行重大更改 -`models/` 目录，您将需要进行新的迁移。可以找到这些 -在 `models/migrations/` 中。您可以确保您的迁移适用于主要 -数据库类型使用： - -```bash -make test-sqlite-migration # 将 SQLite 切换为适当的数据库 -``` - -## 测试 - -Gitea 运行两种类型的测试：单元测试和集成测试。 - -### 单元测试 - -`go test` 系统中的`*_test.go` 涵盖了单元测试。 -您可以设置环境变量 `GITEA_UNIT_TESTS_LOG_SQL=1` 以在详细模式下运行测试时显示所有 SQL 语句（即设置`GOTESTFLAGS=-v` 时）。 - -```bash -TAGS="bindata sqlite sqlite_unlock_notify" make test # Runs the unit tests -``` - -### 集成测试 - -单元测试不会也不能完全单独测试 Gitea。因此，我们编写了集成测试；但是，这些依赖于数据库。 - -```bash -TAGS="bindata sqlite sqlite_unlock_notify" make build test-sqlite -``` - -将在 SQLite 环境中运行集成测试。集成测试需要安装 `git lfs`。其他数据库测试可用，但 -可能需要适应当地环境。 - -看看 [`tests/integration/README.md`](https://github.com/go-gitea/gitea/blob/main/tests/integration/README.md) 有关更多信息以及如何运行单个测试。 - -### 测试 PR - -我们的持续集成将测试代码是否通过了单元测试，并且所有支持的数据库都将在 Docker 环境中通过集成测试。 -还将测试从几个最新版本的 Gitea 迁移。 - -请在PR中附带提交适当的单元测试和集成测试。 - -## 网站文档 - -该网站的文档位于 `docs/` 中。如果你改变了文档内容，你可以使用以下测试方法进行持续集成： - -```bash -# 来自 Gitea 中的 docs 目录 -make trans-copy clean build -``` - -运行此任务依赖于 [Hugo](https://gohugo.io/)。请注意：这可能会生成一些未跟踪的 Git 对象， -需要被清理干净。 - -## Visual Studio Code - -`contrib/ide/vscode` 中为 Visual Studio Code 提供了 `launch.json` 和 `tasks.json`。查看 -[`contrib/ide/README.md`](https://github.com/go-gitea/gitea/blob/main/contrib/ide/README.md) 了解更多信息。 - -## Goland - -单击 `/main.go` 中函数 `func main()` 上的 `Run Application` 箭头 -可以快速启动一个可调试的 Gitea 实例。 - -`Run/Debug Configuration` 中的 `Output Directory` 必须设置为 -gitea 项目目录（包含 `main.go` 和 `go.mod`）， -否则，启动实例的工作目录是 GoLand 的临时目录 -并防止 Gitea 在开发环境中加载动态资源（例如：模板）。 - -要在 GoLand 中使用 SQLite 运行单元测试，请设置 `-tags sqlite,sqlite_unlock_notify` -在 `运行/调试配置` 的 `Go 工具参数` 中。 - -## 提交 PR - -对更改感到满意后，将它们推送并打开拉取请求。它建议您允许 Gitea Managers 和 Owners 修改您的 PR -分支，因为我们需要在合并之前将其更新为 main 和/或可能是能够直接帮助解决问题。 - -任何 PR 都需要 Gitea 维护者的两次批准，并且需要通过持续集成。看看我们的 -[CONTRIBUTING.md](https://github.com/go-gitea/gitea/blob/main/CONTRIBUTING.md) -文档。 - -如果您需要更多帮助，请访问 [Discord](https://discord.gg/gitea) #Develop 频道 -并在那里聊天。 - -现在，您已准备好 Hacking Gitea。 diff --git a/docs/content/doc/developers/integrations.en-us.md b/docs/content/doc/developers/integrations.en-us.md deleted file mode 100644 index 15d5e7e59e..0000000000 --- a/docs/content/doc/developers/integrations.en-us.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -date: "2019-04-15T17:29:00+08:00" -title: "Integrations" -slug: "integrations" -weight: 40 -toc: false -draft: false -menu: - sidebar: - parent: "developers" - name: "Integrations" - weight: 65 - identifier: "integrations" ---- - -# Integrations - -Gitea has a wonderful community of third-party integrations, as well as first-class support in various other -projects. - -We are curating a list over at [awesome-gitea](https://gitea.com/gitea/awesome-gitea) to track these! - -If you are looking for [CI/CD](https://gitea.com/gitea/awesome-gitea#user-content-devops), -an [SDK](https://gitea.com/gitea/awesome-gitea#user-content-sdk), -or even some extra [themes](https://gitea.com/gitea/awesome-gitea#user-content-themes), -you can find them listed in the [awesome-gitea](https://gitea.com/gitea/awesome-gitea) repository! - -## Pre-Fill New File name and contents - -If you'd like to open a new file with a given name and contents, -you can do so with query parameters: - -```txt -GET /{{org}}/{{repo}}/_new/{{filepath}} - ?filename={{filename}} - &value={{content}} -``` - -For example: - -```txt -GET https://git.example.com/johndoe/bliss/_new/articles/ - ?filename=hello-world.md - &value=Hello%2C%20World! -``` diff --git a/docs/content/doc/developers/integrations.zh-tw.md b/docs/content/doc/developers/integrations.zh-tw.md deleted file mode 100644 index 6991ec4ae8..0000000000 --- a/docs/content/doc/developers/integrations.zh-tw.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -date: "2019-04-15T17:29:00+08:00" -title: "整合" -slug: "integrations" -weight: 40 -toc: false -draft: false -menu: - sidebar: - parent: "developers" - name: "整合" - weight: 65 - identifier: "integrations" ---- - -# 整合 - -Gitea 有著很棒的第三方整合社群， 以及其它有著一流支援的專案。 - -我們持續的整理一份清單以追蹤他們！請到 [awesome-gitea](https://gitea.com/gitea/awesome-gitea) 查看。 - -如果您正在找尋有關 [CI/CD](https://gitea.com/gitea/awesome-gitea#user-content-devops)、[SDK](https://gitea.com/gitea/awesome-gitea#user-content-sdk) 或是其它佈景主題，您可以在存儲庫 [awesome-gitea](https://gitea.com/gitea/awesome-gitea) 找到他們。 diff --git a/docs/content/doc/developers/migrations.en-us.md b/docs/content/doc/developers/migrations.en-us.md deleted file mode 100644 index 168af1f7fa..0000000000 --- a/docs/content/doc/developers/migrations.en-us.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -date: "2019-04-15T17:29:00+08:00" -title: "Migrations Interfaces" -slug: "migrations-interfaces" -weight: 30 -toc: false -draft: false -menu: - sidebar: - parent: "developers" - name: "Migrations Interfaces" - weight: 55 - identifier: "migrations-interfaces" ---- - -# Migration Features - -Complete migrations were introduced in Gitea 1.9.0. It defines two interfaces to support migrating -repository data from other Git host platforms to Gitea or, in the future, migrating Gitea data to other Git host platforms. - -Currently, migrations from GitHub, GitLab, and other Gitea instances are implemented. - -First of all, Gitea defines some standard objects in packages [modules/migration](https://github.com/go-gitea/gitea/tree/main/modules/migration). -They are `Repository`, `Milestone`, `Release`, `ReleaseAsset`, `Label`, `Issue`, `Comment`, `PullRequest`, `Reaction`, `Review`, `ReviewComment`. - -## Downloader Interfaces - -To migrate from a new Git host platform, there are two steps to be updated. - -- You should implement a `Downloader` which will be used to get repository information. -- You should implement a `DownloaderFactory` which will be used to detect if the URL matches and create the above `Downloader`. - - You'll need to register the `DownloaderFactory` via `RegisterDownloaderFactory` on `init()`. - -You can find these interfaces in [downloader.go](https://github.com/go-gitea/gitea/blob/main/modules/migration/downloader.go). - -## Uploader Interface - -Currently, only a `GiteaLocalUploader` is implemented, so we only save downloaded -data via this `Uploader` to the local Gitea instance. Other uploaders are not supported at this time. - -You can find these interfaces in [uploader.go](https://github.com/go-gitea/gitea/blob/main/modules/migration/uploader.go). diff --git a/docs/content/doc/developers/migrations.zh-tw.md b/docs/content/doc/developers/migrations.zh-tw.md deleted file mode 100644 index 173c01a464..0000000000 --- a/docs/content/doc/developers/migrations.zh-tw.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -date: "2019-04-15T17:29:00+08:00" -title: "遷移介面" -slug: "migrations-interfaces" -weight: 30 -toc: false -draft: false -menu: - sidebar: - parent: "developers" - name: "遷移介面" - weight: 55 - identifier: "migrations-interfaces" ---- - -# 遷移功能 - -完整的遷移從 Gitea 1.9.0 開始提供。它定義了兩個介面用來從其它 Git 託管平臺遷移儲存庫資料到 Gitea，未來或許會提供遷移到其它 git 託管平臺。 -目前已實作了從 Github, Gitlab 和其它 Gitea 遷移資料。 - -Gitea 定義了一些基本物件於套件 [modules/migration](https://github.com/go-gitea/gitea/tree/master/modules/migration)。 -分別是 `Repository`, `Milestone`, `Release`, `ReleaseAsset`, `Label`, `Issue`, `Comment`, `PullRequest`, `Reaction`, `Review`, `ReviewComment`。 - -## Downloader 介面 - -從新的 Git 託管平臺遷移，有兩個新的步驟。 - -- 您必須實作一個 `Downloader`，它用來取得儲存庫資訊。 -- 您必須實作一個 `DownloaderFactory`，它用來偵測 URL 是否符合並建立上述的 `Downloader`。 - - 您需要在 `init()` 透過 `RegisterDownloaderFactory` 來註冊 `DownloaderFactory`。 - -您可以在 [downloader.go](https://github.com/go-gitea/gitea/blob/master/modules/migration/downloader.go) 中找到這些介面。 - -## Uploader 介面 - -目前只有 `GiteaLocalUploader` 被實作出來，所以我們只能通過 `Uploader` 儲存已下載的資料到本地的 Gitea 實例。 -目前尚未支援其它 Uploader。 - -您可以在 [uploader.go](https://github.com/go-gitea/gitea/blob/master/modules/migration/uploader.go) 中找到這些介面。 diff --git a/docs/content/doc/developers/oauth2-provider.en-us.md b/docs/content/doc/developers/oauth2-provider.en-us.md deleted file mode 100644 index 1ef30a7f0e..0000000000 --- a/docs/content/doc/developers/oauth2-provider.en-us.md +++ /dev/null @@ -1,139 +0,0 @@ ---- -date: "2019-04-19:44:00+01:00" -title: "OAuth2 provider" -slug: "oauth2-provider" -weight: 41 -toc: false -draft: false -menu: - sidebar: - parent: "developers" - name: "OAuth2 Provider" - weight: 41 - identifier: "oauth2-provider" ---- - -# OAuth2 provider - -**Table of Contents** - -{{< toc >}} - -Gitea supports acting as an OAuth2 provider to allow third party applications to access its resources with the user's consent. This feature is available since release 1.8.0. - -## Endpoints - -| Endpoint | URL | -| ------------------------ | ----------------------------------- | -| OpenID Connect Discovery | `/.well-known/openid-configuration` | -| Authorization Endpoint | `/login/oauth/authorize` | -| Access Token Endpoint | `/login/oauth/access_token` | -| OpenID Connect UserInfo | `/login/oauth/userinfo` | -| JSON Web Key Set | `/login/oauth/keys` | - -## Supported OAuth2 Grants - -At the moment Gitea only supports the [**Authorization Code Grant**](https://tools.ietf.org/html/rfc6749#section-1.3.1) standard with additional support of the following extensions: - -- [Proof Key for Code Exchange (PKCE)](https://tools.ietf.org/html/rfc7636) -- [OpenID Connect (OIDC)](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth) - -To use the Authorization Code Grant as a third party application it is required to register a new application via the "Settings" (`/user/settings/applications`) section of the settings. - -## Scopes - -Gitea supports the following scopes for tokens: - -| Name | Description | -| ---- | ----------- | -| **(no scope)** | Grants read-only access to public user profile and public repositories. | -| **repo** | Full control over all repositories. | -| **repo:status** | Grants read/write access to commit status in all repositories. | -| **public_repo** | Grants read/write access to public repositories only. | -| **admin:repo_hook** | Grants access to repository hooks of all repositories. This is included in the `repo` scope. | -| **write:repo_hook** | Grants read/write access to repository hooks | -| **read:repo_hook** | Grants read-only access to repository hooks | -| **admin:org** | Grants full access to organization settings | -| **write:org** | Grants read/write access to organization settings | -| **read:org** | Grants read-only access to organization settings | -| **admin:public_key** | Grants full access for managing public keys | -| **write:public_key** | Grant read/write access to public keys | -| **read:public_key** | Grant read-only access to public keys | -| **admin:org_hook** | Grants full access to organizational-level hooks | -| **admin:user_hook** | Grants full access to user-level hooks | -| **notification** | Grants full access to notifications | -| **user** | Grants full access to user profile info | -| **read:user** | Grants read access to user's profile | -| **user:email** | Grants read access to user's email addresses | -| **user:follow** | Grants access to follow/un-follow a user | -| **delete_repo** | Grants access to delete repositories as an admin | -| **package** | Grants full access to hosted packages | -| **write:package** | Grants read/write access to packages | -| **read:package** | Grants read access to packages | -| **delete:package** | Grants delete access to packages | -| **admin:gpg_key** | Grants full access for managing GPG keys | -| **write:gpg_key** | Grants read/write access to GPG keys | -| **read:gpg_key** | Grants read-only access to GPG keys | -| **admin:application** | Grants full access to manage applications | -| **write:application** | Grants read/write access for managing applications | -| **read:application** | Grants read access for managing applications | -| **sudo** | Allows to perform actions as the site admin. | - -## Client types - -Gitea supports both confidential and public client types, [as defined by RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749#section-2.1). - -For public clients, a redirect URI of a loopback IP address such as `http://127.0.0.1/` allows any port. Avoid using `localhost`, [as recommended by RFC 8252](https://datatracker.ietf.org/doc/html/rfc8252#section-8.3). - -## Example - -**Note:** This example does not use PKCE. - -1. Redirect to user to the authorization endpoint in order to get their consent for accessing the resources: - - ```curl - https://[YOUR-GITEA-URL]/login/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI& response_type=code&state=STATE - ``` - - The `CLIENT_ID` can be obtained by registering an application in the settings. The `STATE` is a random string that will be send back to your application after the user authorizes. The `state` parameter is optional but should be used to prevent CSRF attacks. - -  - - The user will now be asked to authorize your application. If they authorize it, the user will be redirected to the `REDIRECT_URL`, for example: - - ```curl - https://[REDIRECT_URI]?code=RETURNED_CODE&state=STATE - ``` - -2. Using the provided `code` from the redirect, you can request a new application and refresh token. The access token endpoints accepts POST requests with `application/json` and `application/x-www-form-urlencoded` body, for example: - - ```curl - POST https://[YOUR-GITEA-URL]/login/oauth/access_token - ``` - - ```json - { - "client_id": "YOUR_CLIENT_ID", - "client_secret": "YOUR_CLIENT_SECRET", - "code": "RETURNED_CODE", - "grant_type": "authorization_code", - "redirect_uri": "REDIRECT_URI" - } - ``` - - Response: - - ```json - { - "access_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJnbnQiOjIsInR0IjowLCJleHAiOjE1NTUxNzk5MTIsImlhdCI6MTU1NTE3NjMxMn0.0-iFsAwBtxuckA0sNZ6QpBQmywVPz129u75vOM7wPJecw5wqGyBkmstfJHAjEOqrAf_V5Z-1QYeCh_Cz4RiKug", - "token_type": "bearer", - "expires_in": 3600, - "refresh_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJnbnQiOjIsInR0IjoxLCJjbnQiOjEsImV4cCI6MTU1NzgwNDMxMiwiaWF0IjoxNTU1MTc2MzEyfQ.S_HZQBy4q9r5SEzNGNIoFClT43HPNDbUdHH-GYNYYdkRfft6XptJBkUQscZsGxOW975Yk6RbgtGvq1nkEcklOw" - } - ``` - - The `CLIENT_SECRET` is the unique secret code generated for this application. Please note that the secret will only be visible after you created/registered the application with Gitea and cannot be recovered. If you lose the secret you must regenerate the secret via the application's settings. - - The `REDIRECT_URI` in the `access_token` request must match the `REDIRECT_URI` in the `authorize` request. - -3. Use the `access_token` to make [API requests](https://docs.gitea.io/en-us/api-usage#oauth2) to access the user's resources. diff --git a/docs/content/doc/developers/oauth2-provider.zh-tw.md b/docs/content/doc/developers/oauth2-provider.zh-tw.md deleted file mode 100644 index 179c6342cd..0000000000 --- a/docs/content/doc/developers/oauth2-provider.zh-tw.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -date: "2019-04-19:44:00+01:00" -title: "OAuth2 提供者" -slug: "oauth2-provider" -weight: 41 -toc: false -draft: false -menu: - sidebar: - parent: "developers" - name: "OAuth2 提供者" - weight: 41 - identifier: "oauth2-provider" ---- - -# OAuth2 提供者 - -**目錄** - -{{< toc >}} - -Gitea 支援作為 OAuth2 提供者，能讓第三方程式能在使用者同意下存取 Gitea 的資源。此功能自 1.8.0 版開始提供。 - -## Endpoint - -| Endpoint | URL | -| ---------------------- | --------------------------- | -| Authorization Endpoint | `/login/oauth/authorize` | -| Access Token Endpoint | `/login/oauth/access_token` | - -## 支援的 OAuth2 Grant - -目前 Gitea 只支援 [**Authorization Code Grant**](https://tools.ietf.org/html/rfc6749#section-1.3.1) 標準並額外支援下列擴充標準： - -- [Proof Key for Code Exchange (PKCE)](https://tools.ietf.org/html/rfc7636) -- [OpenID Connect (OIDC)](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth) - -若想要讓第三方程式使用 Authorization Code Grant，需先在「設定」(`/user/settings/applications`)中註冊一個新的應用程式。 - -## Scope - -目前 Gitea 尚未支援 scope （參見 [#4300](https://github.com/go-gitea/gitea/issues/4300)），所有的第三方程式都可獲得該使用者及他所屬的組織中所有資源的存取權。 - -## 範例 - -**備註：** 此範例未使用 PKCE。 - -1. 重新導向使用者到 authorization endpoint 以獲得他同意授權存取資源： - <!-- 1. Redirect to user to the authorization endpoint in order to get their consent for accessing the resources: --> - - ```curl - https://[YOUR-GITEA-URL]/login/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI& response_type=code&state=STATE - ``` - - 在設定中註冊應用程式以獲得 `CLIENT_ID`。`STATE` 是一個隨機的字串，它將在使用者授權後發送回您的應用程式。`state` 參數是選用的，但應該要用它來防止 CSRF 攻擊。 - -  - - 使用者將會被詢問是否授權給您的應用程式。如果它們同意了，使用者將被重新導向到 `REDIRECT_URL`，例如： - - ```curl - https://[REDIRECT_URI]?code=RETURNED_CODE&state=STATE - ``` - -1. 使用重新導向提供的 `code`，您可以要求一個新的應用程式和 Refresh Token。Access Token Endpoint 接受 POST 請求使用 `application/json` 或 `application/x-www-form-urlencoded` 類型的請求內容，例如： - - ```curl - POST https://[YOUR-GITEA-URL]/login/oauth/access_token - ``` - - ```json - { - "client_id": "YOUR_CLIENT_ID", - "client_secret": "YOUR_CLIENT_SECRET", - "code": "RETURNED_CODE", - "grant_type": "authorization_code", - "redirect_uri": "REDIRECT_URI" - } - ``` - - 回應： - - ```json - { - "access_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJnbnQiOjIsInR0IjowLCJleHAiOjE1NTUxNzk5MTIsImlhdCI6MTU1NTE3NjMxMn0.0-iFsAwBtxuckA0sNZ6QpBQmywVPz129u75vOM7wPJecw5wqGyBkmstfJHAjEOqrAf_V5Z-1QYeCh_Cz4RiKug", - "token_type": "bearer", - "expires_in": 3600, - "refresh_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJnbnQiOjIsInR0IjoxLCJjbnQiOjEsImV4cCI6MTU1NzgwNDMxMiwiaWF0IjoxNTU1MTc2MzEyfQ.S_HZQBy4q9r5SEzNGNIoFClT43HPNDbUdHH-GYNYYdkRfft6XptJBkUQscZsGxOW975Yk6RbgtGvq1nkEcklOw" - } - ``` - - `CLIENT_SECRET` 是產生給此應用程式的唯一密鑰。請記住該密鑰只會在您於 Gitea 建立/註冊應用程式時出現一次。若您遺失密鑰，您必須在該應用程式的設定中重新產生密鑰。 - - `access_token` 請求中的 `REDIRECT_URI` 必須符合 `authorize` 請求中的 `REDIRECT_URI`。 - -1. 發送 [API requests](https://docs.gitea.io/en-us/api-usage#oauth2) 時使用 `access_token` 以存取使用者的資源。 |