domi/forgejo-domi
1
0
Fork 0
forked from forgejo/forgejo
Code Pull requests Activity

Add markdownlint (#20512)

Browse source 
Add `markdownlint` linter and fix issues. Config is based on the one
from electron's repo with a few rules relaxed.
This commit is contained in:
silverwind 2022-07-28 03:22:47 +02:00 • committed by GitHub
parent 6554d5197f
commit ae52df6a64
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
68 changed files with 1339 additions and 823 deletions
Download patch file Download diff file Expand all files Collapse all files

1
docs/content/doc/developers/api-usage.en-us.md
View file

@ -48,7 +48,6 @@ A new token can be generated with a `POST` request to
Note that `/users/:name/tokens` is a special endpoint and requires you
to authenticate using `BasicAuth` and a password, as follows:
```sh
$ curl -XPOST -H "Content-Type: application/json" -k -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"}

14
docs/content/doc/developers/guidelines-backend.md
View file

@ -21,8 +21,8 @@ menu:
## 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.
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
@ -43,9 +43,9 @@ To maintain understandable code and avoid circular dependencies it is important
- `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/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.
@ -61,7 +61,7 @@ From left to right, left packages could depend on right packages, but right pack
**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.
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
@ -84,7 +84,7 @@ func CreateXXXX() error {\
}
```
You should **not** use `db.GetEngine(ctx)` in `services` directly, but just write a function under `models/`.
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

17
docs/content/doc/developers/guidelines-frontend.md
View file

@ -26,6 +26,7 @@ Gitea uses [Less CSS](https://lesscss.org), [Fomantic-UI](https://fomantic-ui.co
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:
* **Less styles:** `web_src/less/`
* **JavaScript files:** `web_src/js/`
* **Vue components:** `web_src/js/components/`
@ -41,36 +42,37 @@ We recommend [Google HTML/CSS Style Guide](https://google.github.io/styleguide/h
2. HTML ids and classes should use kebab-case.
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. jQuery events across different features could use their own namespaces if there are potential conflicts.
5. 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.
5. 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.
6. The backend can pass complex data to the frontend by using `ctx.PageData["myModuleData"] = map[]{}`
7. Simple pages and SEO-related pages use Go HTML Template render to generate static Fomantic-UI HTML output. Complex pages can use Vue2 (or Vue3 in future).
### 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.
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
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.
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 we want to call an `async` function in a non-async context,
@ -88,10 +90,9 @@ However, there are still some special cases, so the current guideline is:
* `$.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.
* `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.
### 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.

17
docs/content/doc/developers/hacking-on-gitea.en-us.md
View file

@ -35,7 +35,7 @@ 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
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 >}}.
@ -69,7 +69,7 @@ One of these three distributions of Make will run on Windows:
- [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.
- 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`.
@ -212,7 +212,7 @@ SVG icons are built using the `make svg` target which compiles the icon sources
### 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 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.
@ -312,7 +312,6 @@ may need adjustment to the local environment.
Take a look at [`integrations/README.md`](https://github.com/go-gitea/gitea/blob/main/integrations/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
@ -345,13 +344,13 @@ for more information.
## GoLand
Clicking the `Run Application` arrow on the function `func main()` in `/main.go`
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.
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`.

8
docs/content/doc/developers/migrations.en-us.md
View file

@ -16,11 +16,11 @@ menu:
# 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.
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).
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
@ -29,7 +29,7 @@ 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'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).

2
docs/content/doc/developers/migrations.zh-tw.md
View file

@ -18,7 +18,7 @@ menu:
完整的遷移從 Gitea 1.9.0 開始提供。它定義了兩個介面用來從其它 Git 託管平臺遷移儲存庫資料到 Gitea，未來或許會提供遷移到其它 git 託管平臺。
目前已實作了從 Github, Gitlab 和其它 Gitea 遷移資料。
Gitea 定義了一些基本物件於套件 [modules/migration](https://github.com/go-gitea/gitea/tree/master/modules/migration)。
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 介面

1
docs/content/doc/developers/oauth2-provider.md
View file

@ -34,6 +34,7 @@ Gitea supports acting as an OAuth2 provider to allow third party applications to
## 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)