From ae52df6a64477bcd5076ddddbee64bb22b3897a0 Mon Sep 17 00:00:00 2001 From: silverwind Date: Thu, 28 Jul 2022 03:22:47 +0200 Subject: Add markdownlint (#20512) Add `markdownlint` linter and fix issues. Config is based on the one from electron's repo with a few rules relaxed. --- docs/content/doc/developers/api-usage.en-us.md | 1 - docs/content/doc/developers/guidelines-backend.md | 14 +++++++------- docs/content/doc/developers/guidelines-frontend.md | 17 +++++++++-------- docs/content/doc/developers/hacking-on-gitea.en-us.md | 17 ++++++++--------- docs/content/doc/developers/migrations.en-us.md | 8 ++++---- docs/content/doc/developers/migrations.zh-tw.md | 2 +- docs/content/doc/developers/oauth2-provider.md | 1 + 7 files changed, 30 insertions(+), 30 deletions(-) (limited to 'docs/content/doc/developers') diff --git a/docs/content/doc/developers/api-usage.en-us.md b/docs/content/doc/developers/api-usage.en-us.md index 57702a6ee8..dd2822e9f1 100644 --- a/docs/content/doc/developers/api-usage.en-us.md +++ b/docs/content/doc/developers/api-usage.en-us.md @@ -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//tokens {"id":1,"name":"test","sha1":"9fcb1158165773dd010fca5f0cf7174316c3e37d","token_last_eight":"16c3e37d"} diff --git a/docs/content/doc/developers/guidelines-backend.md b/docs/content/doc/developers/guidelines-backend.md index 1248d41432..4280aa80fb 100644 --- a/docs/content/doc/developers/guidelines-backend.md +++ b/docs/content/doc/developers/guidelines-backend.md @@ -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 diff --git a/docs/content/doc/developers/guidelines-frontend.md b/docs/content/doc/developers/guidelines-frontend.md index 0fced64b14..87272d023f 100644 --- a/docs/content/doc/developers/guidelines-frontend.md +++ b/docs/content/doc/developers/guidelines-frontend.md @@ -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. diff --git a/docs/content/doc/developers/hacking-on-gitea.en-us.md b/docs/content/doc/developers/hacking-on-gitea.en-us.md index 9d15f66dac..abefb1ca96 100644 --- a/docs/content/doc/developers/hacking-on-gitea.en-us.md +++ b/docs/content/doc/developers/hacking-on-gitea.en-us.md @@ -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`. diff --git a/docs/content/doc/developers/migrations.en-us.md b/docs/content/doc/developers/migrations.en-us.md index b749f4f604..168af1f7fa 100644 --- a/docs/content/doc/developers/migrations.en-us.md +++ b/docs/content/doc/developers/migrations.en-us.md @@ -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). diff --git a/docs/content/doc/developers/migrations.zh-tw.md b/docs/content/doc/developers/migrations.zh-tw.md index 0d892cae91..173c01a464 100644 --- a/docs/content/doc/developers/migrations.zh-tw.md +++ b/docs/content/doc/developers/migrations.zh-tw.md @@ -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 介面 diff --git a/docs/content/doc/developers/oauth2-provider.md b/docs/content/doc/developers/oauth2-provider.md index ce6e9aad8c..9e6ab11742 100644 --- a/docs/content/doc/developers/oauth2-provider.md +++ b/docs/content/doc/developers/oauth2-provider.md @@ -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) -- cgit v1.2.3