Skip to content

Commit 5c70e6a

Browse files
yalunny
ya
and
lunny
authored
Update docs issue-pull-request-templates.zh-cn.md (#21030)
Follow #20987, update docs issue-pull-request-templates.zh-cn.md <!-- Please check the following: 1. Make sure you are targeting the `main` branch, pull requests on release branches are only allowed for bug fixes. 2. Read contributing guidelines: https://github.com/go-gitea/gitea/blob/main/CONTRIBUTING.md 3. Describe what your pull request does and which issue you're targeting (if any) --> Co-authored-by: Lunny Xiao <[email protected]>
1 parent aa5de4d commit 5c70e6a

File tree

1 file changed

+280
-20
lines changed

1 file changed

+280
-20
lines changed

‎docs/content/doc/usage/issue-pull-request-templates.zh-cn.md

Lines changed: 280 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,296 @@
11
---
2-
date: "2018-05-10T16:00:00+02:00"
3-
title: "使用：Issue 和 Pull Request 模板"
2+
date: "2022-09-07T16:00:00+08:00"
3+
title: "使用：从模板创建工单与合并请求"
44
slug: "issue-pull-request-templates"
55
weight: 15
6-
toc: false
6+
toc: true
77
draft: false
88
menu:
99
sidebar:
1010
parent: "usage"
11-
name: "Issue 和 Pull Request 模板"
11+
name: "从模板创建工单与合并请求"
1212
weight: 15
1313
identifier: "issue-pull-request-templates"
1414
---
1515

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

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

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

22-
* ISSUE_TEMPLATE.md
23-
* issue_template.md
24-
* .gitea/ISSUE_TEMPLATE.md
25-
* .gitea/issue_template.md
26-
* .github/ISSUE_TEMPLATE.md
27-
* .github/issue_template.md
22+
{{< toc >}}
2823

29-
以下罗列了一些可供参考的 PR 模板:
24+
## 模板介绍
3025

31-
* PULL_REQUEST_TEMPLATE.md
32-
* pull_request_template.md
33-
* .gitea/PULL_REQUEST_TEMPLATE.md
34-
* .gitea/pull_request_template.md
35-
* .github/PULL_REQUEST_TEMPLATE.md
36-
* .github/pull_request_template.md
26+
Gitea 支持两种格式的模板：Markdown 和 YAML。
27+
28+
### Markdown 模板
29+
30+
在 Gitea 中存在两种用途的 Markdown 模板：
31+
32+
- `ISSUE_TEMPLATE/bug-report.md` 用于规范工单的 Markdown 文本描述
33+
- `PULL_REQUEST_TEMPLATE.md` 用于规范合并请求的 Markdown 文本描述
34+
35+
对于以上 Markdown 模板，我们推荐您将它们放置到项目目录 `.gitea` 进行收纳。
36+
37+
### YAML 模板
38+
39+
用 YAML 语法编写的模板相比 Markdown 可以实现更丰富的功能，利用表单实现诸如：问卷调查、字符校验。在 Gitea 中的 YAML 同样支持两种用途：
40+
41+
- `ISSUE_TEMPLATE/bug-report.yaml` 用于创建问卷调查形式的工单
42+
- `PULL_REQUEST_TEMPLATE.yaml` 用于创建表单形式的合并请求
43+
44+
对于以上 YAML 模板，我们同样推荐您将它们放置到项目目录 `.gitea` 进行收纳。
45+
46+
##### 表单支持通过 URL 查询参数传值
47+
48+
当新建工单页面 URL 以 `?title=Issue+Title&body=Issue+Text` 为查询参数，表单将使用其中的参数（key-value）填充表单内容。
49+
50+
### Gitea 支持的模板文件路径
51+
52+
工单模板文件名:
53+
54+
- `ISSUE_TEMPLATE.md`
55+
- `ISSUE_TEMPLATE.yaml`
56+
- `ISSUE_TEMPLATE.yml`
57+
- `issue_template.md`
58+
- `issue_template.yaml`
59+
- `issue_template.yml`
60+
- `.gitea/ISSUE_TEMPLATE.md`
61+
- `.gitea/ISSUE_TEMPLATE.yaml`
62+
- `.gitea/ISSUE_TEMPLATE.yml`
63+
- `.gitea/issue_template.md`
64+
- `.gitea/issue_template.yaml`
65+
- `.gitea/issue_template.md`
66+
- `.github/ISSUE_TEMPLATE.md`
67+
- `.github/ISSUE_TEMPLATE.yaml`
68+
- `.github/ISSUE_TEMPLATE.yml`
69+
- `.github/issue_template.md`
70+
- `.github/issue_template.yaml`
71+
- `.github/issue_template.yml`
72+
73+
合并请求模板:
74+
75+
- `PULL_REQUEST_TEMPLATE.md`
76+
- `PULL_REQUEST_TEMPLATE.yaml`
77+
- `PULL_REQUEST_TEMPLATE.yml`
78+
- `pull_request_template.md`
79+
- `pull_request_template.yaml`
80+
- `pull_request_template.yml`
81+
- `.gitea/PULL_REQUEST_TEMPLATE.md`
82+
- `.gitea/PULL_REQUEST_TEMPLATE.yaml`
83+
- `.gitea/PULL_REQUEST_TEMPLATE.yml`
84+
- `.gitea/pull_request_template.md`
85+
- `.gitea/pull_request_template.yaml`
86+
- `.gitea/pull_request_template.yml`
87+
- `.github/PULL_REQUEST_TEMPLATE.md`
88+
- `.github/PULL_REQUEST_TEMPLATE.yaml`
89+
- `.github/PULL_REQUEST_TEMPLATE.yml`
90+
- `.github/pull_request_template.md`
91+
- `.github/pull_request_template.yaml`
92+
- `.github/pull_request_template.yml`
93+
94+
#### 工单模板目录
95+
96+
由于工单存在多种类型，Gitea 支持将工单模板统一收纳到 `ISSUE_TEMPLATE` 目录。以下是 Gitea 支持的工单模板目录:
97+
98+
- `ISSUE_TEMPLATE`
99+
- `issue_template`
100+
- `.gitea/ISSUE_TEMPLATE`
101+
- `.gitea/issue_template`
102+
- `.github/ISSUE_TEMPLATE`
103+
- `.github/issue_template`
104+
- `.gitlab/ISSUE_TEMPLATE`
105+
- `.gitlab/issue_template`
106+
107+
目录支持混合存放 Markdown (`.md`) 或 YAML (`.yaml`/`.yml`) 格式的工单模板。另外，合并请求模板不支持目录存放。
108+
109+
## Markdown 模板语法
110+
111+
```md
112+
---
113+
114+
name: "Template Name"
115+
about: "This template is for testing!"
116+
title: "[TEST] "
117+
ref: "main"
118+
labels:
119+
120+
- bug
121+
- "help needed"
122+
123+
---
124+
125+
This is the template!
126+
```
127+
128+
上面的示例表示用户从列表中选择一个工单模板时，列表会展示模板名称 `Template Name` 和模板描述 `This template is for testing!`。 同时，标题会预先填充为 `[TEST]`，而正文将预先填充 `This is the template!`。 最后，Issue 还会被分配两个标签，`bug` 和 `help needed`，并且将问题指向 `main` 分支。
129+
130+
## YAML 模板语法
131+
132+
YAML 模板格式如下，相比 Markdown 模板提供了更多实用性的功能。
133+
134+
```yaml
135+
name: 表单名称
136+
about: 表单描述
137+
title: 默认标题
138+
body: 主体内容
139+
type: 定义表单元素类型
140+
id: 定义表单标号
141+
attributes: 扩展的属性
142+
validations: 内容校验
143+
```
144+
145+
下例 YAML 配置文件完整定义了一个用于提交 bug 的问卷调查。
146+
147+
```yaml
148+
name: Bug Report
149+
about: File a bug report
150+
title: "[Bug]: "
151+
body:
152+
- type: markdown
153+
attributes:
154+
value: |
155+
Thanks for taking the time to fill out this bug report!
156+
- type: input
157+
id: contact
158+
attributes:
159+
label: Contact Details
160+
description: How can we get in touch with you if we need more info?
161+
placeholder: ex. [email protected]
162+
validations:
163+
required: false
164+
- type: textarea
165+
id: what-happened
166+
attributes:
167+
label: What happened?
168+
description: Also tell us, what did you expect to happen?
169+
placeholder: Tell us what you see!
170+
value: "A bug happened!"
171+
validations:
172+
required: true
173+
- type: dropdown
174+
id: version
175+
attributes:
176+
label: Version
177+
description: What version of our software are you running?
178+
options:
179+
- 1.0.2 (Default)
180+
- 1.0.3 (Edge)
181+
validations:
182+
required: true
183+
- type: dropdown
184+
id: browsers
185+
attributes:
186+
label: What browsers are you seeing the problem on?
187+
multiple: true
188+
options:
189+
- Firefox
190+
- Chrome
191+
- Safari
192+
- Microsoft Edge
193+
- type: textarea
194+
id: logs
195+
attributes:
196+
label: Relevant log output
197+
description: Please copy and paste any relevant log output. This will be automatically formatted into code, so no need for backticks.
198+
render: shell
199+
- type: checkboxes
200+
id: terms
201+
attributes:
202+
label: Code of Conduct
203+
description: By submitting this issue, you agree to follow our [Code of Conduct](https://example.com)
204+
options:
205+
- label: I agree to follow this project's Code of Conduct
206+
required: true
207+
```
208+
209+
### Markdown 段落
210+
211+
您可以在 YAML 模板中使用 `markdown` 元素为开发者提供额外的上下文支撑，这部分内容会作为创建工单的提示但不会作为工单内容提交。
212+
213+
`attributes` 子项提供了以下扩展能力：
214+
215+
| 键 | 描述 | 必选 | 类型 | 默认值 | 有效值 |
216+
| ------- | ------------------------------ | ---- | ------ | ------ | ------ |
217+
| `value` | 渲染的文本。支持 Markdown 格式 | 必选 | 字符串 | - | - |
218+
219+
### Textarea 多行文本输入框
220+
221+
您可以使用 `textarea` 元素在表单中添加多行文本输入框。 除了输入文本，开发者还可以在 `textarea` 区域附加文件。
222+
223+
`attributes` 子项提供了以下扩展能力：
224+
225+
| 键 | 描述 | 必选 | 类型 | 默认值 | 有效值 |
226+
| ------------- | ----------------------------------------------------------------------------------------------------- | ---- | ------ | -------- | ------------------ |
227+
| `label` | 预期用户输入的简短描述，也以表单形式显示。 | 必选 | 字符串 | - | - |
228+
| `description` | 提供上下文或指导的文本区域的描述，以表单形式显示。 | 可选 | 字符串 | 空字符串 | - |
229+
| `placeholder` | 半透明的占位符，在文本区域空白时呈现 | 可选 | 字符串 | 空字符串 | - |
230+
| `value` | 在文本区域中预填充的文本。 | 可选 | 字符串 | - | - |
231+
| `render` | 如果提供了值，提交的文本将格式化为代码块。 提供此键时，文本区域将不会扩展到文件附件或 Markdown 编辑。 | 可选 | 字符串 | - | Gitea 支持的语言。 |
232+
233+
`validations` 子项提供以下文本校验参数：
234+
235+
| 键 | 描述 | 必选 | 类型 | 默认值 | 有效值 |
236+
| ---------- | ---------------------------- | ---- | ------ | ------ | ------ |
237+
| `required` | 防止在元素完成之前提交表单。 | 可选 | 布尔型 | false | - |
238+
239+
### Input 单行输入框
240+
241+
您可以使用 `input` 元素添加单行文本字段到表单。
242+
243+
`attributes` 子项提供了以下扩展能力：
244+
245+
| 键 | 描述 | 必选 | 类型 | 默认值 | 有效值 |
246+
| ------------- | ---------------------------------------------- | ---- | ------ | -------- | ------ |
247+
| `label` | 预期用户输入的简短描述，也以表单形式显示。 | 必选 | 字符串 | - | - |
248+
| `description` | 提供上下文或指导的字段的描述，以表单形式显示。 | 可选 | 字符串 | 空字符串 | - |
249+
| `placeholder` | 半透明的占位符，在字段空白时呈现。 | 可选 | 字符串 | 空字符串 | - |
250+
| `value` | 字段中预填的文本。 | 可选 | 字符串 | - | - |
251+
252+
`validations` 子项提供以下文本校验参数：
253+
254+
| 键 | 描述 | 必选 | 类型 | 默认值 | 有效值 |
255+
| ----------- | -------------------------------- | ---- | ------ | ------ | -------------------------------------------------------------- |
256+
| `required` | 防止在未填内容时提交表单。 | 可选 | 布尔型 | false | - |
257+
| `is_number` | 防止在未填数字时提交表单。 | 可选 | 布尔型 | false | - |
258+
| `regex` | 直到满足了与正则表达式匹配的值。 | 可选 | 字符串 | - | [正则表达式](https://en.wikipedia.org/wiki/Regular_expression) |
259+
260+
### Dropdown 下拉菜单
261+
262+
您可以使用 `dropdown` 元素在表单中添加下拉菜单。
263+
264+
`attributes` 子项提供了以下扩展能力：
265+
266+
| 键 | 描述 | 必选 | 类型 | 默认值 | 有效值 |
267+
| ------------- | --------------------------------------------------------- | ---- | ---------- | -------- | ------ |
268+
| `label` | 预期用户输入的简短描述，以表单形式显示。 | 必选 | 字符串 | - | - |
269+
| `description` | 提供上下文或指导的下拉列表的描述，以表单形式显示。 | 可选 | 字符串 | 空字符串 | - |
270+
| `multiple` | 确定用户是否可以选择多个选项。 | 可选 | 布尔型 | false | - |
271+
| `options` | 用户可以选择的选项列表。 不能为空，所有选择必须是不同的。 | 必选 | 字符串数组 | - | - |
272+
273+
`validations` 子项提供以下文本校验参数：
274+
275+
| 键 | 描述 | 必选 | 类型 | 默认值 | 有效值 |
276+
| ---------- | ---------------------------- | ---- | ------ | ------ | ------ |
277+
| `required` | 防止在元素完成之前提交表单。 | 可选 | 布尔型 | false | - |
278+
279+
### Checkboxes 复选框
280+
281+
您可以使用 `checkboxes` 元素添加一组复选框到表单。
282+
283+
`attributes` 子项提供了以下扩展能力：
284+
285+
| 键 | 描述 | 必选 | 类型 | 默认值 | 有效值 |
286+
| ------------- | ----------------------------------------------------- | ---- | ------ | -------- | ------ |
287+
| `label` | 预期用户输入的简短描述，以表单形式显示。 | 必选 | 字符串 | - | - |
288+
| `description` | 复选框集的描述，以表单形式显示。 支持 Markdown 格式。 | 可选 | 字符串 | 空字符串 | - |
289+
| `options` | 用户可以选择的复选框列表。 有关语法，请参阅下文。 | 必选 | 数组 | - | - |
290+
291+
对于 `options`，您可以设置以下参数：
292+
293+
| 键 | 描述 | 必选 | 类型 | 默认值 | 有效值 |
294+
| ---------- | --------------------------------------------------------------------------------- | ---- | ------ | ------ | ------ |
295+
| `label` | 选项的标识符，显示在表单中。 支持 Markdown 用于粗体或斜体文本格式化和超文本链接。 | 必选 | 字符串 | - | - |
296+
| `required` | 防止在元素完成之前提交表单。 | 可选 | 布尔型 | false | - |

0 commit comments

Comments
 (0)