mirror of
https://github.com/go-gitea/gitea.git
synced 2026-08-04 17:17:03 +02:00
fix
This commit is contained in:
wxiaoguang
+11
-10
@@ -2,16 +2,17 @@
|
||||
|
||||
This document explains how to contribute changes to the Gitea project. Topic-specific guides live in separate files so the essentials are easier to find.
|
||||
|
||||
| Topic | Document |
|
||||
| :---- | :------- |
|
||||
| Setup and requirements | [docs/setup.md](docs/setup.md) |
|
||||
| Building and the development workflow | [docs/development.md](docs/development.md) |
|
||||
| Running the tests | [docs/testing.md](docs/testing.md) |
|
||||
| Backend architecture and API v1 | [docs/guidelines-backend.md](docs/guidelines-backend.md) |
|
||||
| Frontend architecture and UI guidelines | [docs/guidelines-frontend.md](docs/guidelines-frontend.md) |
|
||||
| Refactoring | [docs/guidelines-refactoring.md](docs/guidelines-refactoring.md) |
|
||||
| Maintainers, TOC, labels, merge queue, commit format for mergers | [docs/community-governance.md](docs/community-governance.md) |
|
||||
| Release cycle, backports, tagging releases | [docs/release-management.md](docs/release-management.md) |
|
||||
| Topic | Document |
|
||||
|:-----------------------|:-----------------------------------------------------------------|
|
||||
| Setup and requirements | [docs/build-setup.md](docs/build-setup.md) |
|
||||
| Development workflow | [docs/development.md](docs/development.md) |
|
||||
| Build from source | [docs/build-source.md](docs/build-source.md) |
|
||||
| Running the tests | [docs/testing.md](docs/testing.md) |
|
||||
| Frontend guidelines | [docs/guidelines-frontend.md](docs/guidelines-frontend.md) |
|
||||
| Backend guidelines | [docs/guidelines-backend.md](docs/guidelines-backend.md) |
|
||||
| Refactoring | [docs/guidelines-refactoring.md](docs/guidelines-refactoring.md) |
|
||||
| Community Governance | [docs/community-governance.md](docs/community-governance.md) |
|
||||
| Release management | [docs/release-management.md](docs/release-management.md) |
|
||||
|
||||
<details><summary>Table of Contents</summary>
|
||||
|
||||
|
||||
+1
-1
@@ -2,7 +2,7 @@
|
||||
|
||||
This document describes how to build Gitea from source and the day-to-day
|
||||
development workflow. For prerequisites and how to obtain the code, see
|
||||
[setup.md](setup.md). For running tests, see [testing.md](testing.md). For the
|
||||
[build-setup.md](build-setup.md). For running tests, see [testing.md](testing.md). For the
|
||||
contribution workflow and review process, see [CONTRIBUTING.md](../CONTRIBUTING.md).
|
||||
|
||||
Area-specific guidelines:
|
||||
|
||||
@@ -62,11 +62,6 @@ Operations that must roll back together should run inside `db.WithTx()` (or
|
||||
Functions that participate in a transaction take a `context.Context` as their first
|
||||
parameter so the transaction can be propagated.
|
||||
|
||||
### Implementing `io.Closer`
|
||||
|
||||
Types that implement `io.Closer` must tolerate `Close()` being called more than once
|
||||
without panicking.
|
||||
|
||||
### XORM gotchas
|
||||
|
||||
- Never call `x.Update(exemplar)` without an explicit `WHERE` clause — it updates
|
||||
|
||||
+14
-21
@@ -6,9 +6,8 @@ and testing see [development.md](development.md) and [testing.md](testing.md).
|
||||
|
||||
## Background
|
||||
|
||||
The frontend uses [Vue 3](https://vuejs.org/), [Fomantic-UI](https://fomantic-ui.com/)
|
||||
(built on jQuery), [htmx](https://htmx.org/) for partial page updates, and
|
||||
[Tailwind CSS](https://tailwindcss.com/). Pages are rendered with Go HTML templates.
|
||||
The frontend uses [Vue 3](https://vuejs.org/), [Fomantic-UI](https://fomantic-ui.com/) (built on jQuery)
|
||||
and [Tailwind CSS](https://tailwindcss.com/). Pages are rendered with Go HTML templates.
|
||||
Source files live in:
|
||||
|
||||
- `web_src/css/`: CSS styles
|
||||
@@ -28,15 +27,14 @@ reference an existing published version.
|
||||
|
||||
Mixing frameworks arbitrarily makes code hard to maintain. Recommended combinations:
|
||||
|
||||
- Vue with vanilla JavaScript
|
||||
- Fomantic-UI (jQuery)
|
||||
- Vue3
|
||||
- Vanilla JavaScript
|
||||
- Fomantic-UI (jQuery), deprecated, we vendored a specific version with a lot of changes.
|
||||
|
||||
Avoid combinations such as Vue with Fomantic-UI, jQuery with htmx, or htmx with heavy
|
||||
JavaScript dependencies. Vue components may reuse Fomantic-UI CSS classes for visual
|
||||
consistency. Use Go templates for simple or SEO-relevant pages and Vue for complex,
|
||||
interactive pages. Gitea uses Vue 3 **without** JSX to keep HTML and JavaScript
|
||||
separate.
|
||||
Avoid combinations such as Vue with Fomantic-UI.
|
||||
Vue components may reuse Fomantic-UI CSS classes for visual consistency.
|
||||
Use Go templates for simple or SEO-relevant pages and Vue for complex, interactive pages.
|
||||
Gitea uses Vue 3 **without** JSX to keep HTML and JavaScript separate.
|
||||
|
||||
> [!NOTE]
|
||||
> Fomantic-UI is not an accessibility-friendly framework. Gitea patches some ARIA
|
||||
@@ -47,12 +45,9 @@ separate.
|
||||
|
||||
- Keep features in their own files or directories.
|
||||
- Use kebab-case for HTML `id`s and classes, ideally with 2-3 feature keywords.
|
||||
- Prefix classes used only as JavaScript hooks with `js-`, and keep them unique
|
||||
across the project.
|
||||
- Create a new class name when overriding framework styles instead of editing the
|
||||
framework's own classes.
|
||||
- Pass complex data to the frontend via `ctx.PageData["myModuleData"]` rather than
|
||||
embedding models directly, to avoid leaking sensitive fields.
|
||||
- Prefix classes to avoid short-name conflicts between different frameworks.
|
||||
- Create a new class name when overriding framework styles instead of editing the framework's own classes,
|
||||
or fix the framework's source to fix all cases.
|
||||
- Prefer semantic elements such as `<button>` over generic `<div>`s.
|
||||
- Avoid `!important`; when it is unavoidable, document why.
|
||||
- Prefix custom DOM events with `ce-`.
|
||||
@@ -67,15 +62,14 @@ helpers over per-child margins. Gitea also ships a small set of custom helpers:
|
||||
Write class attributes as a single readable unit in templates:
|
||||
|
||||
```html
|
||||
<div class="tw-flex tw-items-center {{if .IsFoo}}tw-hidden{{end}}"></div>
|
||||
<div class="flex-text-inline {{if .IsFoo}}tw-hidden{{end}}"></div>
|
||||
```
|
||||
|
||||
## TypeScript
|
||||
|
||||
- Use `import type` for type-only imports.
|
||||
- Prefer `@ts-expect-error` over `@ts-ignore`.
|
||||
- Use the `!` non-null assertion (rather than `?.`/`??`) when a value is known to
|
||||
always exist.
|
||||
- Use the `!` non-null assertion (rather than `?.`/`??`) when a value is known to always exist.
|
||||
- Only mark a function `async` when it actually uses `await` or returns a `Promise`.
|
||||
Avoid async event listeners; if unavoidable, call `e.preventDefault()` before the
|
||||
first `await`. For a deliberately un-awaited call, assign it: `const _promise = asyncFoo()`.
|
||||
@@ -83,8 +77,7 @@ Write class attributes as a single readable unit in templates:
|
||||
## Data fetching
|
||||
|
||||
Use the `GET`, `POST`, `PUT`, `PATCH`, and `DELETE` wrappers from
|
||||
[`web_src/js/modules/fetch.ts`](../web_src/js/modules/fetch.ts); they add the CSRF
|
||||
token automatically.
|
||||
[`web_src/js/modules/fetch.ts`](../web_src/js/modules/fetch.ts).
|
||||
|
||||
## DOM attributes
|
||||
|
||||
|
||||
+1
-1
@@ -4,7 +4,7 @@ Gitea has four kinds of automated tests: backend unit tests, integration tests,
|
||||
end-to-end (e2e) tests, and migration tests. Local runs default to SQLite, so no
|
||||
extra services are required to get started.
|
||||
|
||||
For prerequisites see [setup.md](setup.md); for the build workflow see
|
||||
For prerequisites see [build-setup.md](build-setup.md); for the build workflow see
|
||||
[development.md](development.md).
|
||||
|
||||
## Unit tests
|
||||
|
||||
Reference in New Issue
Block a user