从模板创建工单与合并请求

开发者可以利用问题模板创建工单与合并请求，其目的在于规范参与者的语言表达。

模板介绍

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.yml
  • .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 模板语法

  1. ---
  3. name: "Template Name"
  4. about: "This template is for testing!"
  5. title: "[TEST] "
  6. ref: "main"
  7. labels:
  9. - bug
  10. - "help needed"
  12. ---
  14. This is the template!

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

YAML 模板语法

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

  1. name: 表单名称
  2. about: 表单描述
  3. title: 默认标题
  4. body: 主体内容
  5.   type: 定义表单元素类型
  6.     id: 定义表单标号
  7.     attributes: 扩展的属性
  8.     validations: 内容校验

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

  1. name: Bug Report
  2. about: File a bug report
  3. title: "[Bug]: "
  4. body:
  5.   - type: markdown
  6.     attributes:
  7.       value: |
  8.         Thanks for taking the time to fill out this bug report!
  9.   - type: input
  10.     id: contact
  11.     attributes:
  12.       label: Contact Details
  13.       description: How can we get in touch with you if we need more info?
  14.       placeholder: ex. email@example.com
  15.     validations:
  16.       required: false
  17.   - type: textarea
  18.     id: what-happened
  19.     attributes:
  20.       label: What happened?
  21.       description: Also tell us, what did you expect to happen?
  22.       placeholder: Tell us what you see!
  23.       value: "A bug happened!"
  24.     validations:
  25.       required: true
  26.   - type: dropdown
  27.     id: version
  28.     attributes:
  29.       label: Version
  30.       description: What version of our software are you running?
  31.       options:
  32.         - 1.0.2 (Default)
  33.         - 1.0.3 (Edge)
  34.     validations:
  35.       required: true
  36.   - type: dropdown
  37.     id: browsers
  38.     attributes:
  39.       label: What browsers are you seeing the problem on?
  40.       multiple: true
  41.       options:
  42.         - Firefox
  43.         - Chrome
  44.         - Safari
  45.         - Microsoft Edge
  46.   - type: textarea
  47.     id: logs
  48.     attributes:
  49.       label: Relevant log output
  50.       description: Please copy and paste any relevant log output. This will be automatically formatted into code, so no need for backticks.
  51.       render: shell
  52.   - type: checkboxes
  53.     id: terms
  54.     attributes:
  55.       label: Code of Conduct
  56.       description: By submitting this issue, you agree to follow our [Code of Conduct](https://example.com)
  57.       options:
  58.         - label: I agree to follow this project's Code of Conduct
  59.           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直到满足了与正则表达式匹配的值。可选字符串-正则表达式

Dropdown 下拉菜单

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

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

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

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

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

Checkboxes 复选框

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

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

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

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

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