Docusaurus-ify 1.20 (#26052)

See https://github.com/go-gitea/gitea/pull/26051

---------

Signed-off-by: jolheiser <john.olheiser@gmail.com>
Co-authored-by: JonRB <4564448+eeyrjmr@users.noreply.github.com>

docs/content/contributing/guidelines-backend.en-us.md

@@ -0,0 +1,120 @@
+---
+date: "2021-11-01T23:41:00+08:00"
+title: "Guidelines for Backend Development"
+slug: "guidelines-backend"
+sidebar_position: 20
+toc: false
+draft: false
+aliases:
+  - /en-us/guidelines-backend
+menu:
+  sidebar:
+    parent: "contributing"
+    name: "Guidelines for Backend"
+    sidebar_position: 20
+    identifier: "guidelines-backend"
+---
+
+# Guidelines for Backend Development
+
+## 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 front-end and 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 {
+        // 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`.

docs/content/contributing/guidelines-backend.zh-cn.md

@@ -0,0 +1,119 @@
+---
+date: "2023-05-25T23:41:00+08:00"
+title: "后端开发指南"
+slug: "guidelines-backend"
+sidebar_position: 20
+toc: false
+draft: false
+aliases:
+  - /zh-cn/guidelines-backend
+menu:
+  sidebar:
+    parent: "contributing"
+    name: "后端开发指南"
+    sidebar_position: 20
+    identifier: "guidelines-backend"
+---
+
+# 后端开发指南
+
+## 背景
+
+Gitea使用Golang作为后端编程语言。它使用了许多第三方包，并且自己也编写了一些包。
+例如，Gitea使用[Chi](https://github.com/go-chi/chi)作为基本的Web框架。[Xorm](https://xorm.io)是一个用于与数据库交互的ORM框架。
+因此，管理这些包非常重要。在开始编写后端代码之前，请参考以下准则。
+
+## 包设计准则
+
+### 包列表
+
+为了保持易于理解的代码并避免循环依赖，拥有良好的代码结构是很重要的。Gitea后端分为以下几个部分：
+
+- `build`：帮助构建Gitea的脚本。
+- `cmd`：包含所有Gitea的实际子命令，包括web、doctor、serv、hooks、admin等。`web`将启动Web服务。`serv`和`hooks`将被Git或OpenSSH调用。其他子命令可以帮助维护Gitea。
+- `tests`：常用的测试函数
+- `tests/integration`：集成测试，用于测试后端回归。
+- `tests/e2e`：端到端测试，用于测试前端和后端的兼容性和视觉回归。
+- `models`：包含由xorm用于构建数据库表的数据结构。它还包含查询和更新数据库的函数。应避免与其他Gitea代码的依赖关系。在某些情况下，比如日志记录时可以例外。
+  - `models/db`：基本的数据库操作。所有其他`models/xxx`包都应依赖于此包。`GetEngine`函数只能从models/中调用。
+  - `models/fixtures`：单元测试和集成测试中使用的示例数据。一个`yml`文件表示一个将在测试开始时加载到数据库中的表。
+  - `models/migrations`：存储不同版本之间的数据库迁移。修改数据库结构的PR**必须**包含一个迁移步骤。
+- `modules`：在Gitea中处理特定功能的不同模块。工作正在进行中：其中一些模块应该移到`services`中，特别是那些依赖于models的模块，因为它们依赖于数据库。
+  - `modules/setting`：存储从ini文件中读取的所有系统配置，并在各处引用。但是在可能的情况下，应将其作为函数参数使用。
+  - `modules/git`：用于与`Git`命令行或Gogit包交互的包。
+- `public`：编译后的前端文件（JavaScript、图像、CSS等）
+- `routers`：处理服务器请求。由于它使用其他Gitea包来处理请求，因此其他包（models、modules或services）不能依赖于routers。
+  - `routers/api`：包含`/api/v1`相关路由，用于处理RESTful API请求。
+  - `routers/install`：只能在系统处于安装模式（INSTALL_LOCK=false）时响应。
+  - `routers/private`：仅由内部子命令调用，特别是`serv`和`hooks`。
+  - `routers/web`：处理来自Web浏览器或Git SMART HTTP协议的HTTP请求。
+- `services`：用于常见路由操作或命令执行的支持函数。使用`models`和`modules`来处理请求。
+- `templates`：用于生成HTML输出的Golang模板。
+
+### 包依赖关系
+
+由于Golang不支持导入循环，我们必须仔细决定包之间的依赖关系。这些包之间有一些级别。以下是理想的包依赖关系方向。
+
+`cmd` -> `routers` -> `services` -> `models` -> `modules`
+
+从左到右，左侧的包可以依赖于右侧的包，但右侧的包不能依赖于左侧的包。在同一级别的子包中，可以根据该级别的规则进行依赖。
+
+**注意事项**
+
+为什么我们需要在`models`之外使用数据库事务？以及如何使用？
+某些操作在数据库记录插入/更新/删除失败时应该允许回滚。
+因此，服务必须能够创建数据库事务。以下是一些示例：
+
+```go
+// services/repository/repository.go
+func CreateXXXX() error {
+    return db.WithTx(func(ctx context.Context) error {
+        // do something, if err is returned, it will rollback automatically
+        if err := issues.UpdateIssue(ctx, repoID); err != nil {
+            // ...
+            return err
+        }
+        // ...
+        return nil
+    })
+}
+```
+
+在`services`中**不应该**直接使用`db.GetEngine(ctx)`，而是应该在`models/`下编写一个函数。
+如果该函数将在事务中使用，请将`context.Context`作为函数的第一个参数。
+
+```go
+// models/issues/issue.go
+func UpdateIssue(ctx context.Context, repoID int64) error {
+    e := db.GetEngine(ctx)
+
+    // ...
+}
+```
+
+### 包名称
+
+对于顶层包，请使用复数作为包名，例如`services`、`models`，对于子包，请使用单数，例如`services/user`、`models/repository`。
+
+### 导入别名
+
+由于有一些使用相同包名的包，例如`modules/user`、`models/user`和`services/user`，当这些包在一个Go文件中被导入时，很难知道我们使用的是哪个包以及它是变量名还是导入名。因此，我们始终建议使用导入别名。为了与常见的驼峰命名法的包变量区分开，建议使用**snake_case**作为导入别名的命名规则。
+例如：`import user_service "code.gitea.io/gitea/services/user"`
+
+### 重要注意事项
+
+- 永远不要写成`x.Update(exemplar)`，而没有明确的`WHERE`子句：
+  - 这将导致表中的所有行都被使用exemplar的非零值进行更新，包括ID。
+  - 通常应该写成`x.ID(id).Update(exemplar)`。
+- 如果在迁移过程中使用`x.Insert(exemplar)`向表中插入记录，而ID是预设的：
+  - 对于MSSQL变体，你将需要执行``SET IDENTITY_INSERT `table` ON``（否则迁移将失败）
+  - 对于PostgreSQL，你还需要更新ID序列，否则迁移将悄无声息地通过，但后续的插入将失败：
+    ``SELECT setval('table_name_id_seq', COALESCE((SELECT MAX(id)+1 FROM `table_name`), 1), false)``
+
+### 未来的任务
+
+目前，我们正在进行一些重构，以完成以下任务：
+
+- 纠正不符合规则的代码。
+- `models`中的文件太多了，所以我们正在将其中的一些移动到子包`models/xxx`中。
+- 由于它们依赖于`models`，因此应将某些`modules`子包移动到`services`中。

docs/content/contributing/guidelines-frontend.en-us.md

@@ -0,0 +1,135 @@
+---
+date: "2021-10-13T16:00:00+02:00"
+title: "Guidelines for Frontend Development"
+slug: "guidelines-frontend"
+sidebar_position: 30
+toc: false
+draft: false
+aliases:
+  - /en-us/guidelines-frontend
+menu:
+  sidebar:
+    parent: "contributing"
+    name: "Guidelines for Frontend"
+    sidebar_position: 30
+    identifier: "guidelines-frontend"
+---
+
+# Guidelines for Frontend Development
+
+## 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.
+12. Gitea's tailwind-style CSS classes use `gt-` prefix (`gt-relative`), while Gitea's own private framework-level CSS classes use `g-` prefix (`g-modal-confirm`).
+
+### 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.

docs/content/contributing/guidelines-frontend.zh-cn.md

@@ -0,0 +1,134 @@
+---
+date: "2023-05-25T16:00:00+02:00"
+title: "前端开发指南"
+slug: "guidelines-frontend"
+sidebar_position: 20
+toc: false
+draft: false
+aliases:
+  - /zh-cn/guidelines-frontend
+menu:
+  sidebar:
+    parent: "contributing"
+    name: "前端开发指南"
+    sidebar_position: 20
+    identifier: "guidelines-frontend"
+---
+
+# 前端开发指南
+
+## 背景
+
+Gitea 在其前端中使用[Fomantic-UI](https://fomantic-ui.com/introduction/getting-started.html)（基于[jQuery](https://api.jquery.com)）和 [Vue3](https://vuejs.org/)。
+
+HTML 页面由[Go HTML Template](https://pkg.go.dev/html/template)渲染。
+
+源文件可以在以下目录中找到：
+
+* **CSS 样式**： `web_src/css/`
+* **JavaScript 文件**： `web_src/js/`
+* **Vue 组件**： `web_src/js/components/`
+* **Go HTML 模板**： `templates/`
+
+## 通用准则
+
+我们推荐使用[Google HTML/CSS Style Guide](https://google.github.io/styleguide/htmlcssguide.html)和[Google JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html)。
+
+## Gitea 特定准则：
+
+1. 每个功能（Fomantic-UI/jQuery 模块）应放在单独的文件/目录中。
+2. HTML 的 id 和 class 应使用 kebab-case，最好包含2-3个与功能相关的关键词。
+3. 在 JavaScript 中使用的 HTML 的 id 和 class 应在整个项目中是唯一的，并且应包含2-3个与功能相关的关键词。建议在仅在 JavaScript 中使用的 class 中使用 `js-` 前缀。
+4. 不应覆盖框架提供的 class 的 CSS 样式。始终使用具有2-3个与功能相关的关键词的新 class 名称来覆盖框架样式。Gitea 中的帮助 CSS 类在 `helpers.less` 中。
+5. 后端可以通过使用`ctx.PageData["myModuleData"] = map[]{}`将复杂数据传递给前端，但不要将整个模型暴露给前端，以避免泄露敏感数据。
+6. 简单页面和与 SEO 相关的页面使用 Go HTML 模板渲染生成静态的 Fomantic-UI HTML 输出。复杂页面可以使用 Vue3。
+7. 明确变量类型，优先使用`elem.disabled = true`而不是`elem.setAttribute('disabled', 'anything')`，优先使用`$el.prop('checked', var === 'yes')`而不是`$el.prop('checked', var)`。
+8. 使用语义化元素，优先使用`<button class="ui button">`而不是`<div class="ui button">`。
+9. 避免在 CSS 中使用不必要的`!important`，如果无法避免，添加注释解释为什么需要它。
+10. 避免在一个事件监听器中混合不同的事件，优先为每个事件使用独立的事件监听器。
+11. 推荐使用自定义事件名称前缀`ce-`。
+12. Gitea 的 tailwind-style CSS 类使用`gt-`前缀（`gt-relative`），而 Gitea 自身的私有框架级 CSS 类使用`g-`前缀（`g-modal-confirm`）。
+
+### 可访问性 / ARIA
+
+在历史上，Gitea大量使用了可访问性不友好的框架 Fomantic UI。
+Gitea使用一些补丁使Fomantic UI更具可访问性（参见`aria.js`和`aria.md`），
+但仍然存在许多问题需要大量的工作和时间来修复。
+
+### 框架使用
+
+不建议混合使用不同的框架，这会使代码难以维护。
+一个 JavaScript 模块应遵循一个主要框架，并遵循该框架的最佳实践。
+
+推荐的实现方式：
+
+* Vue + Vanilla JS
+* Fomantic-UI（jQuery）
+* Vanilla JS
+
+不推荐的实现方式：
+
+* Vue + Fomantic-UI（jQuery）
+* jQuery + Vanilla JS
+
+为了保持界面一致，Vue 组件可以使用 Fomantic-UI 的 CSS 类。
+尽管不建议混合使用不同的框架，
+但如果混合使用是必要的，并且代码设计良好且易于维护，也可以工作。
+
+### async 函数
+
+只有当函数内部存在`await`调用或返回`Promise`时，才将函数标记为`async`。
+
+不建议使用`async`事件监听器，这可能会导致问题。
+原因是`await`后的代码在事件分发之外执行。
+参考：https://github.com/github/eslint-plugin-github/blob/main/docs/rules/async-preventdefault.md
+
+如果一个事件监听器必须是`async`，应在任何`await`之前使用`e.preventDefault()`，
+建议将其放在函数的开头。
+
+如果我们想在非异步上下文中调用`async`函数，
+建议使用`const _promise = asyncFoo()`来告诉读者
+这是有意为之的，我们想调用异步函数并忽略Promise。
+一些 lint 规则和 IDE 也会在未处理返回的 Promise 时发出警告。
+
+### HTML 属性和 dataset
+
+禁止使用`dataset`，它的驼峰命名行为使得搜索属性变得困难。
+然而，仍然存在一些特殊情况，因此当前的准则是：
+
+* 对于旧代码：
+  * 应将`$.data()`重构为`$.attr()`。
+  * 在极少数情况下，可以使用`$.data()`将一些非字符串数据绑定到元素上，但强烈不推荐使用。
+
+* 对于新代码：
+  * 不应使用`node.dataset`，而应使用`node.getAttribute`。
+  * 不要将任何用户数据绑定到 DOM 节点上，使用合适的设计模式描述节点和数据之间的关系。
+
+### 显示/隐藏元素
+
+* 推荐在Vue组件中使用`v-if`和`v-show`来显示/隐藏元素。
+* Go 模板代码应使用 Gitea 的 `.gt-hidden` 和 `showElem()/hideElem()/toggleElem()` 来显示/隐藏元素，请参阅`.gt-hidden`的注释以获取更多详细信息。
+
+### Go HTML 模板中的样式和属性
+
+建议使用以下方式：
+
+```html
+<div class="gt-name1 gt-name2 {{if .IsFoo}}gt-foo{{end}}" {{if .IsFoo}}data-foo{{end}}></div>
+```
+
+而不是：
+
+```html
+<div class="gt-name1 gt-name2{{if .IsFoo}} gt-foo{{end}}"{{if .IsFoo}} data-foo{{end}}></div>
+```
+
+以使代码更易读。
+
+### 旧代码
+
+许多旧代码已经存在于本文撰写之前。建议重构旧代码以遵循指南。
+
+### Vue3 和 JSX
+
+Gitea 现在正在使用 Vue3。我们决定不引入 JSX，以保持 HTML 代码和 JavaScript 代码分离。

docs/content/contributing/guidelines-refactoring.en-us.md

@@ -0,0 +1,49 @@
+---
+date: "2023-02-14T00:00:00+00:00"
+title: "Guidelines for Refactoring"
+slug: "guidelines-refactoring"
+sidebar_position: 40
+toc: false
+draft: false
+aliases:
+  - /en-us/guidelines-refactoring
+menu:
+  sidebar:
+    parent: "contributing"
+    name: "Guidelines for Refactoring"
+    sidebar_position: 40
+    identifier: "guidelines-refactoring"
+---
+
+# Guidelines for Refactoring
+
+## 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.

docs/content/contributing/guidelines-refactoring.zh-cn.md

@@ -0,0 +1,49 @@
+---
+date: "2023-05-25T00:00:00+00:00"
+title: "重构指南"
+slug: "guidelines-refactoring"
+sidebar_position: 20
+toc: false
+draft: false
+aliases:
+  - /zh-cn/guidelines-refactoring
+menu:
+  sidebar:
+    parent: "contributing"
+    name: "重构指南"
+    sidebar_position: 20
+    identifier: "guidelines-refactoring"
+---
+
+# 重构指南
+
+## 背景
+
+自2014年2月12日编写了第一行代码以来，Gitea已经发展成为一个庞大的项目。
+因此，代码库变得越来越大。代码库越大，维护就越困难。
+存在许多过时的机制，许多框架混合在一起，一些遗留代码可能会导致错误并阻碍新功能的开发。
+为了使代码库更易于维护，使Gitea变得更好，开发人员应牢记使用现代机制来重构旧代码。
+
+本文档是关于重构代码库的指南集合。
+
+## 重构建议
+
+* 设计更多关于未来的内容，而不仅仅解决当前问题。
+* 减少模糊性，减少冲突，提高可维护性。
+* 描述重构，例如：
+  * 为什么需要重构。
+  * 如何解决旧问题。
+  * 重构的优点/缺点是什么。
+* 只做必要的更改，尽量保留旧逻辑。
+* 引入一些中间步骤，使重构更容易审查，完整的重构计划可以在几个PR中完成。
+* 如果存在分歧，应该请TOC（技术监督委员会）参与决策。
+* 添加必要的测试以确保重构的正确性。
+* 非错误重构优先在里程碑的开始时进行，这样可以更容易地在发布之前发现问题。
+
+## 审查和合并建议
+
+* 重构的PR不应该长时间保持打开状态（通常为7天），应尽快进行审查。
+* 重构的PR应尽快合并，不应被其他PR阻塞。
+* 如果TOC没有异议，重构的PR可以在7天后由一名核心成员（非作者）批准后合并。
+* 如果最终结果良好，容忍一些不完美/临时的步骤。
+* 如果重构是必要的，容忍一些回归错误，并尽快修复错误。

docs/content/contributing/localization.de-de.md

@@ -0,0 +1,64 @@
+---
+date: "2021-01-22T00:00:00+02:00"
+title: "Übersetzungs Richtlinien"
+slug: "localization"
+sidebar_position: 70
+toc: false
+draft: false
+menu:
+  sidebar:
+    parent: "contributing"
+    name: "Übersetzungsrichtlinien"
+    sidebar_position: 70
+    identifier: "localization"
+---
+
+## Allgemeines
+
+Anrede: Wenig förmlich:
+
+* "Du"-Form
+* Keine "Amtsdeusch"-Umschreibungen, einfach so als ob man den Nutzer direkt persönlich ansprechen würde
+
+Genauer definiert:
+
+* "falsch" anstatt "nicht korrekt/inkorrekt"
+* Benutzerkonto oder Konto? Oder Account?
+* "Wende dich an ..." anstatt "kontaktiere ..."
+* In der selben Zeit übersetzen (sonst wird aus "is" "war")
+* Richtige Anführungszeichen verwenden. Also `"` statt `''` oder `'` oder \` oder `´`
+  * `„` für beginnende Anführungszeichen, `“` für schließende Anführungszeichen
+
+Es gelten Artikel und Worttrennungen aus dem Duden.
+
+## Formulierungen in Modals und Buttons
+
+Es sollten die gleichen Formulierungen auf Buttons und Modals verwendet werden.
+
+Beispiel: Wenn der Button mit `löschen` beschriftet ist, sollte im Modal die Frage lauten `Willst du das wirklich löschen?` und nicht `Willst du das wirklich entfernen?`. Gleiches gilt für Success/Errormeldungen nach der Aktion.
+
+## Trennungen
+
+* Pull-Request
+* Time-Tracker
+* E-Mail-Adresse (siehe Duden)
+
+## Artikeldefinitionen für Anglizismen
+
+* _Der_ Commit (m.)
+* _Der_ Branch (m.), plural: die Branches
+* _Das_ Issue (n.)
+* _Der_ Fork (m.)
+* _Das_ Repository (n.), plural: die Repositories
+* _Der_ Pull-Request (m.)
+* _Der_ Token (m.), plural: die Token
+* _Das_ Review (n.)
+* _Der_ Key (m.)
+* _Der_ Committer (m.), plural: die Committer
+
+## Weiterführende Links
+
+Diese beiden Links sind sehr empfehlenswert:
+
+* http://docs.translatehouse.org/projects/localization-guide/en/latest/guide/translation_guidelines_german.html
+* https://docs.qgis.org/2.18/en/docs/documentation_guidelines/do_translations.html

docs/content/contributing/localization.en-us.md

@@ -0,0 +1,39 @@
+---
+date: "2016-12-01T16:00:00+02:00"
+title: "Localization"
+slug: "localization"
+sidebar_position: 70
+toc: false
+draft: false
+aliases:
+  - /en-us/localization
+menu:
+  sidebar:
+    parent: "contributing"
+    name: "Localization"
+    sidebar_position: 70
+    identifier: "localization"
+---
+
+# Localization
+
+Gitea's localization happens through our [Crowdin project](https://crowdin.com/project/gitea).
+
+For changes to an **English** translation, a pull request can be made that changes the appropriate key in
+the [english locale](https://github.com/go-gitea/gitea/blob/main/options/locale/locale_en-US.ini).
+
+For changes to a **non-English** translation, refer to the Crowdin project above.
+
+## Supported Languages
+
+Any language listed in the above Crowdin project will be supported as long as 25% or more has been translated.
+
+After a translation has been accepted, it will be reflected in the main repository after the next Crowdin sync, which is generally after any PR is merged.
+
+At the time of writing, this means that a changed translation may not appear until the following Gitea release.
+
+If you use a bleeding edge build, it should appear as soon as you update after the change is synced.
+
+# How to Contribute
+
+Different Languages have different translation guidelines. Please visit the respective page for more information.

docs/content/contributing/localization.zh-cn.md

@@ -0,0 +1,34 @@
+---
+date: "2016-12-01T16:00:00+02:00"
+title: "本地化"
+slug: "localization"
+sidebar_position: 70
+toc: false
+draft: false
+aliases:
+  - /zh-cn/localization
+menu:
+  sidebar:
+    parent: "contributing"
+    name: "本地化"
+    sidebar_position: 70
+    identifier: "localization"
+---
+
+# 本地化
+
+Gitea的本地化是通过我们的[Crowdin项目](https://crowdin.com/project/gitea)进行的。
+
+对于对**英语翻译**的更改，可以发出pull-request，来更改[英语语言环境](https://github.com/go-gitea/gitea/blob/main/options/locale/locale_en-US.ini)中合适的关键字。
+
+有关对**非英语**翻译的更改，请参阅上面的 Crowdin 项目。
+
+## 支持的语言
+
+上述 Crowdin 项目中列出的任何语言一旦翻译了 25% 或更多都将得到支持。
+
+翻译被接受后，它将在下一次 Crowdin 同步后反映在主存储库中，这通常是在任何 PR 合并之后。
+
+在撰写本文时，这意味着更改后的翻译可能要到 Gitea 的下一个版本才会出现。
+
+如果使用开发版本，则在同步更改内容后，它应该会在更新后立即显示。

docs/content/contributing/localization.zh-tw.md

@@ -0,0 +1,34 @@
+---
+date: "2016-12-01T16:00:00+02:00"
+title: "在地化"
+slug: "localization"
+sidebar_position: 70
+toc: false
+draft: false
+aliases:
+  - /zh-tw/localization
+menu:
+  sidebar:
+    parent: "contributing"
+    name: "在地化"
+    sidebar_position: 70
+    identifier: "localization"
+---
+
+# 在地化
+
+我們在 [Crowdin 專案](https://crowdin.com/project/gitea)上進行在地化工作。
+
+**英語系**的翻譯，可在修改[英文語言檔](https://github.com/go-gitea/gitea/blob/main/options/locale/locale_en-US.ini)後提出合併請求。
+
+**非英語系**的翻譯，請前往上述的 Crowdin 專案。
+
+## 已支援的語言
+
+上述 Crowdin 專案中列出的語言在翻譯超過 25% 後將被支援。
+
+翻譯被認可後將在下次 Crowdin 同步後進入到主儲存庫，通常是在任何合併請求被合併之後。
+
+這表示更改的翻譯要到下次 Gitea 發佈後才會出現。
+
+如果您使用的是最新建置，它將會在同步完成、您更新後出現。

docs/content/contributing/translation.zh-cn.md

@@ -0,0 +1,17 @@
+---
+date: "2023-05-25T00:00:00+02:00"
+title: "翻译指南"
+sidebar_position: 70
+toc: true
+draft: false
+menu:
+  sidebar:
+    parent: "contributing"
+    name: "翻译指南"
+    sidebar_position: 70
+    identifier: "translation-guidelines"
+---
+
+本页面用于提供一套通用规则，以确保翻译的一致性。
+
+* [German](/de-de/übersetzungs-richtlinien/)