Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update docs issue-pull-request-templates.zh-cn.md #21030

Merged
merged 3 commits into from Sep 7, 2022
Merged

Update docs issue-pull-request-templates.zh-cn.md #21030

Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2fbdccc
Update docs issue-pull-request-templates.zh-cn.md
Sep 2, 2022
fbd20c5
Writing good descriptions
Sep 7, 2022
cc0f2ce
Merge branch 'main' into docs-template
lunny Sep 7, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
300 changes: 280 additions & 20 deletions docs/content/doc/usage/issue-pull-request-templates.zh-cn.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,36 +1,296 @@
---
date: "2018-05-10T16:00:00+02:00"
title: "使用：Issue 和 Pull Request 模板"
date: "2022-09-07T16:00:00+08:00"
title: "使用：从模板创建工单与合并请求"
slug: "issue-pull-request-templates"
weight: 15
toc: false
toc: true
draft: false
menu:
sidebar:
parent: "usage"
name: "Issue 和 Pull Request 模板"
name: "从模板创建工单与合并请求"
weight: 15
identifier: "issue-pull-request-templates"
---

# 使用 Issue 和 Pull Request 模板
# 从模板创建工单与合并请求

对于一些项目，在创建 issue 或 pull request 时有一个标准的询问列表需要提交者填写。Gitea 支持添加此类模板至 repository 的主分支，以便提交者在创建 issue 或 pull request 时可以自动生成一个需要完成的表单，这么做可以减少一些前期关于 issue 抑或 pull request 细节上的沟通成本。
开发者可以利用问题模板创建工单与合并请求，其目的在于规范参与者的语言表达。

以下罗列了一些可供参考的 issue 模板:
**目录**

* ISSUE_TEMPLATE.md
* issue_template.md
* .gitea/ISSUE_TEMPLATE.md
* .gitea/issue_template.md
* .github/ISSUE_TEMPLATE.md
* .github/issue_template.md
{{< toc >}}

以下罗列了一些可供参考的 PR 模板:
## 模板介绍

* PULL_REQUEST_TEMPLATE.md
* pull_request_template.md
* .gitea/PULL_REQUEST_TEMPLATE.md
* .gitea/pull_request_template.md
* .github/PULL_REQUEST_TEMPLATE.md
* .github/pull_request_template.md
Gitea 支持两种格式的模板：Markdown 和 YAML。

### Markdown 模板

在 Gitea 中存在两种用途的 Markdown 模板：

- `ISSUE_TEMPLATE/bug-report.md` 用于规范工单的 Markdown 文本描述
- `PULL_REQUEST_TEMPLATE.md` 用于规范合并请求的 Markdown 文本描述

对于以上 Markdown 模板，我们推荐您将它们放置到项目目录 `.gitea` 进行收纳。

### YAML 模板

用 YAML 语法编写的模板相比 Markdown 可以实现更丰富的功能，利用表单实现诸如：问卷调查、字符校验。在 Gitea 中的 YAML 同样支持两种用途：

- `ISSUE_TEMPLATE/bug-report.yaml` 用于创建问卷调查形式的工单
- `PULL_REQUEST_TEMPLATE.yaml` 用于创建表单形式的合并请求

对于以上 YAML 模板，我们同样推荐您将它们放置到项目目录 `.gitea` 进行收纳。

##### 表单支持通过 URL 查询参数传值

当新建工单页面 URL 以 `?title=Issue+Title&body=Issue+Text` 为查询参数，表单将使用其中的参数（key-value）填充表单内容。

### Gitea 支持的模板文件路径

工单模板文件名:

- `ISSUE_TEMPLATE.md`
- `ISSUE_TEMPLATE.yaml`
- `ISSUE_TEMPLATE.yml`
- `issue_template.md`
- `issue_template.yaml`
- `issue_template.yml`
- `.gitea/ISSUE_TEMPLATE.md`
- `.gitea/ISSUE_TEMPLATE.yaml`
- `.gitea/ISSUE_TEMPLATE.yml`
- `.gitea/issue_template.md`
- `.gitea/issue_template.yaml`
- `.gitea/issue_template.md`
- `.github/ISSUE_TEMPLATE.md`
- `.github/ISSUE_TEMPLATE.yaml`
- `.github/ISSUE_TEMPLATE.yml`
- `.github/issue_template.md`
- `.github/issue_template.yaml`
- `.github/issue_template.yml`

合并请求模板:

- `PULL_REQUEST_TEMPLATE.md`
- `PULL_REQUEST_TEMPLATE.yaml`
- `PULL_REQUEST_TEMPLATE.yml`
- `pull_request_template.md`
- `pull_request_template.yaml`
- `pull_request_template.yml`
- `.gitea/PULL_REQUEST_TEMPLATE.md`
- `.gitea/PULL_REQUEST_TEMPLATE.yaml`
- `.gitea/PULL_REQUEST_TEMPLATE.yml`
- `.gitea/pull_request_template.md`
- `.gitea/pull_request_template.yaml`
- `.gitea/pull_request_template.yml`
- `.github/PULL_REQUEST_TEMPLATE.md`
- `.github/PULL_REQUEST_TEMPLATE.yaml`
- `.github/PULL_REQUEST_TEMPLATE.yml`
- `.github/pull_request_template.md`
- `.github/pull_request_template.yaml`
- `.github/pull_request_template.yml`

#### 工单模板目录

由于工单存在多种类型，Gitea 支持将工单模板统一收纳到 `ISSUE_TEMPLATE` 目录。以下是 Gitea 支持的工单模板目录:

- `ISSUE_TEMPLATE`
- `issue_template`
- `.gitea/ISSUE_TEMPLATE`
- `.gitea/issue_template`
- `.github/ISSUE_TEMPLATE`
- `.github/issue_template`
- `.gitlab/ISSUE_TEMPLATE`
- `.gitlab/issue_template`

目录支持混合存放 Markdown (`.md`) 或 YAML (`.yaml`/`.yml`) 格式的工单模板。另外，合并请求模板不支持目录存放。

## Markdown 模板语法

```md
---

name: "Template Name"
about: "This template is for testing!"
title: "[TEST] "
ref: "main"
labels:

- bug
- "help needed"

---

This is the template!
```

上面的示例表示用户从列表中选择一个工单模板时，列表会展示模板名称 `Template Name` 和模板描述 `This template is for testing!`。 同时，标题会预先填充为 `[TEST]`，而正文将预先填充 `This is the template!`。 最后，Issue 还会被分配两个标签，`bug` 和 `help needed`，并且将问题指向 `main` 分支。

## YAML 模板语法

YAML 模板格式如下，相比 Markdown 模板提供了更多实用性的功能。

```yaml
name: 表单名称
about: 表单描述
title: 默认标题
body: 主体内容
type: 定义表单元素类型
id: 定义表单标号
attributes: 扩展的属性
validations: 内容校验
```

下例 YAML 配置文件完整定义了一个用于提交 bug 的问卷调查。

```yaml
name: Bug Report
about: File a bug report
title: "[Bug]: "
body:
- type: markdown
attributes:
value: |
Thanks for taking the time to fill out this bug report!
- type: input
id: contact
attributes:
label: Contact Details
description: How can we get in touch with you if we need more info?
placeholder: ex. email@example.com
validations:
required: false
- type: textarea
id: what-happened
attributes:
label: What happened?
description: Also tell us, what did you expect to happen?
placeholder: Tell us what you see!
value: "A bug happened!"
validations:
required: true
- type: dropdown
id: version
attributes:
label: Version
description: What version of our software are you running?
options:
- 1.0.2 (Default)
- 1.0.3 (Edge)
validations:
required: true
- type: dropdown
id: browsers
attributes:
label: What browsers are you seeing the problem on?
multiple: true
options:
- Firefox
- Chrome
- Safari
- Microsoft Edge
- type: textarea
id: logs
attributes:
label: Relevant log output
description: Please copy and paste any relevant log output. This will be automatically formatted into code, so no need for backticks.
render: shell
- type: checkboxes
id: terms
attributes:
label: Code of Conduct
description: By submitting this issue, you agree to follow our [Code of Conduct](https://example.com)
options:
- label: I agree to follow this project's Code of Conduct
required: true
```

### Markdown 段落

您可以在 YAML 模板中使用 `markdown` 元素为开发者提供额外的上下文支撑，这部分内容会作为创建工单的提示但不会作为工单内容提交。

`attributes` 子项提供了以下扩展能力：

| 键 | 描述 | 必选 | 类型 | 默认值 | 有效值 |
| ------- | ------------------------------ | ---- | ------ | ------ | ------ |
| `value` | 渲染的文本。支持 Markdown 格式 | 必选 | 字符串 | - | - |

### Textarea 多行文本输入框

您可以使用 `textarea` 元素在表单中添加多行文本输入框。 除了输入文本，开发者还可以在 `textarea` 区域附加文件。

`attributes` 子项提供了以下扩展能力：

| 键 | 描述 | 必选 | 类型 | 默认值 | 有效值 |
| ------------- | ----------------------------------------------------------------------------------------------------- | ---- | ------ | -------- | ------------------ |
| `label` | 预期用户输入的简短描述，也以表单形式显示。 | 必选 | 字符串 | - | - |
| `description` | 提供上下文或指导的文本区域的描述，以表单形式显示。 | 可选 | 字符串 | 空字符串 | - |
| `placeholder` | 半透明的占位符，在文本区域空白时呈现 | 可选 | 字符串 | 空字符串 | - |
| `value` | 在文本区域中预填充的文本。 | 可选 | 字符串 | - | - |
| `render` | 如果提供了值，提交的文本将格式化为代码块。 提供此键时，文本区域将不会扩展到文件附件或 Markdown 编辑。 | 可选 | 字符串 | - | Gitea 支持的语言。 |

`validations` 子项提供以下文本校验参数：

| 键 | 描述 | 必选 | 类型 | 默认值 | 有效值 |
| ---------- | ---------------------------- | ---- | ------ | ------ | ------ |
| `required` | 防止在元素完成之前提交表单。 | 可选 | 布尔型 | false | - |

### Input 单行输入框

您可以使用 `input` 元素添加单行文本字段到表单。

`attributes` 子项提供了以下扩展能力：

| 键 | 描述 | 必选 | 类型 | 默认值 | 有效值 |
| ------------- | ---------------------------------------------- | ---- | ------ | -------- | ------ |
| `label` | 预期用户输入的简短描述，也以表单形式显示。 | 必选 | 字符串 | - | - |
| `description` | 提供上下文或指导的字段的描述，以表单形式显示。 | 可选 | 字符串 | 空字符串 | - |
| `placeholder` | 半透明的占位符，在字段空白时呈现。 | 可选 | 字符串 | 空字符串 | - |
| `value` | 字段中预填的文本。 | 可选 | 字符串 | - | - |

`validations` 子项提供以下文本校验参数：

| 键 | 描述 | 必选 | 类型 | 默认值 | 有效值 |
| ----------- | -------------------------------- | ---- | ------ | ------ | -------------------------------------------------------------- |
| `required` | 防止在未填内容时提交表单。 | 可选 | 布尔型 | false | - |
| `is_number` | 防止在未填数字时提交表单。 | 可选 | 布尔型 | false | - |
| `regex` | 直到满足了与正则表达式匹配的值。 | 可选 | 字符串 | - | [正则表达式](https://en.wikipedia.org/wiki/Regular_expression) |

### Dropdown 下拉菜单

您可以使用 `dropdown` 元素在表单中添加下拉菜单。

`attributes` 子项提供了以下扩展能力：

| 键 | 描述 | 必选 | 类型 | 默认值 | 有效值 |
| ------------- | --------------------------------------------------------- | ---- | ---------- | -------- | ------ |
| `label` | 预期用户输入的简短描述，以表单形式显示。 | 必选 | 字符串 | - | - |
| `description` | 提供上下文或指导的下拉列表的描述，以表单形式显示。 | 可选 | 字符串 | 空字符串 | - |
| `multiple` | 确定用户是否可以选择多个选项。 | 可选 | 布尔型 | false | - |
| `options` | 用户可以选择的选项列表。 不能为空，所有选择必须是不同的。 | 必选 | 字符串数组 | - | - |

`validations` 子项提供以下文本校验参数：

| 键 | 描述 | 必选 | 类型 | 默认值 | 有效值 |
| ---------- | ---------------------------- | ---- | ------ | ------ | ------ |
| `required` | 防止在元素完成之前提交表单。 | 可选 | 布尔型 | false | - |

### Checkboxes 复选框

您可以使用 `checkboxes` 元素添加一组复选框到表单。

`attributes` 子项提供了以下扩展能力：

| 键 | 描述 | 必选 | 类型 | 默认值 | 有效值 |
| ------------- | ----------------------------------------------------- | ---- | ------ | -------- | ------ |
| `label` | 预期用户输入的简短描述，以表单形式显示。 | 必选 | 字符串 | - | - |
| `description` | 复选框集的描述，以表单形式显示。 支持 Markdown 格式。 | 可选 | 字符串 | 空字符串 | - |
| `options` | 用户可以选择的复选框列表。 有关语法，请参阅下文。 | 必选 | 数组 | - | - |

对于 `options`，您可以设置以下参数：

| 键 | 描述 | 必选 | 类型 | 默认值 | 有效值 |
| ---------- | --------------------------------------------------------------------------------- | ---- | ------ | ------ | ------ |
| `label` | 选项的标识符，显示在表单中。 支持 Markdown 用于粗体或斜体文本格式化和超文本链接。 | 必选 | 字符串 | - | - |
| `required` | 防止在元素完成之前提交表单。 | 可选 | 布尔型 | false | - |