Issue 表单语法

您可以为 Issue 表单定义不同的输入类型、验证、默认指派人和默认标签。

本文内容

注意

Issue 表单目前处于公开预览阶段，可能会发生更改。

关于 Issue 表单的 YAML 语法

您可以通过将 YAML 表单定义文件添加到存储库的/.github/ISSUE_TEMPLATE文件夹中来创建自定义 Issue 表单。如果您不熟悉 YAML 并想了解更多信息，请参阅“Y 分钟内学习 YAML”。您可以为 Issue 表单定义不同的输入类型、验证、默认指派人和默认标签。

当贡献者填写 Issue 表单时，他们对每个输入的响应将转换为 Markdown 并添加到 Issue 的正文中。贡献者可以编辑使用 Issue 表单创建的 Issue，其他人可以像通过其他方法创建的 Issue 一样与这些 Issue 进行交互。

Issue 表单不支持拉取请求。您可以为您的存储库创建拉取请求模板供协作者使用。有关更多信息，请参阅“为您的存储库创建拉取请求模板”。

此 YAML 配置文件示例使用多个输入定义了一个用于报告错误的 Issue 表单。

注意

required字段键仅在公共存储库中受支持。在私有和内部存储库中，所有字段都是可选的。

YAML
name: Bug Report
description: File a bug report.
title: "[Bug]: "
labels: ["bug", "triage"]
projects: ["octo-org/1", "octo-org/44"]
assignees:
  - octocat
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 protected]
    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)
      default: 0
    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

顶级语法

所有 Issue 表单配置文件都必须以name、description和body键值对开头。

YAML
name:
description:
body:

您可以为每个 Issue 表单设置以下顶级键。

键描述必需类型
nameIssue 表单模板的名称。必须与所有其他模板（包括 Markdown 模板）唯一。必需字符串
descriptionIssue 表单模板的描述，显示在模板选择器界面中。必需字符串
body表单中输入类型的定义。必需数组
assignees将自动指派给使用此模板创建的 Issue 的人员。可选数组或逗号分隔的字符串
labels将自动添加到使用此模板创建的 Issue 的标签。如果存储库中尚不存在标签，则不会自动将其添加到 Issue。可选数组或逗号分隔的字符串
title将在 Issue 提交表单中预先填充的默认标题。可选字符串
projects使用此模板创建的任何 Issue 都将自动添加到其中的项目。此键的格式为PROJECT-OWNER/PROJECT-NUMBER。
注意：打开 Issue 的人必须对指定的项目具有写入权限。如果您不希望使用此模板的人员具有写入访问权限，请考虑启用项目的自动添加工作流程。有关更多信息，请参阅“自动添加项目”。
可选数组或逗号分隔的字符串

有关可用的body输入类型及其语法，请参阅“GitHub 表单架构的语法”。

将 Markdown Issue 模板转换为 YAML Issue 表单模板

您可以在存储库中同时使用 Markdown 和 YAML Issue 模板。如果您想将 Markdown Issue 模板转换为 YAML Issue 表单模板，则必须创建一个新的 YAML 文件来定义 Issue 表单。您可以手动将现有的 Markdown Issue 模板转置为 YAML Issue 表单。有关更多信息，请参阅“配置存储库的 Issue 模板”。

如果您想为 YAML Issue 表单使用相同的文件名，则必须在将新文件提交到存储库时删除 Markdown Issue 模板。

下面是一个 Markdown Issue 模板和相应的 YAML Issue 表单模板示例。

Markdown Issue 模板

Markdown
---
name: 🐞 Bug
about: File a bug/issue
title: '[BUG] <title>'
labels: Bug, Needs Triage
assignees: ''

---

<!--
Note: Please search to see if an issue already exists for the bug you encountered.
-->

### Current Behavior:
<!-- A concise description of what you're experiencing. -->

### Expected Behavior:
<!-- A concise description of what you expected to happen. -->

### Steps To Reproduce:
<!--
Example: steps to reproduce the behavior:
1. In this environment...
1. With this config...
1. Run '...'
1. See error...
-->

### Environment:
<!--
Example:
- OS: Ubuntu 20.04
- Node: 13.14.0
- npm: 7.6.3
-->

### Anything else:
<!--
Links? References? Anything that will give us more context about the issue that you are encountering!
-->

YAML Issue 表单模板

YAML
name: 🐞 Bug
description: File a bug/issue
title: "[BUG] <title>"
labels: ["Bug", "Needs Triage"]
body:
- type: checkboxes
  attributes:
    label: Is there an existing issue for this?
    description: Please search to see if an issue already exists for the bug you encountered.
    options:
    - label: I have searched the existing issues
      required: true
- type: textarea
  attributes:
    label: Current Behavior
    description: A concise description of what you're experiencing.
  validations:
    required: false
- type: textarea
  attributes:
    label: Expected Behavior
    description: A concise description of what you expected to happen.
  validations:
    required: false
- type: textarea
  attributes:
    label: Steps To Reproduce
    description: Steps to reproduce the behavior.
    placeholder: |
      1. In this environment...
      1. With this config...
      1. Run '...'
      1. See error...
  validations:
    required: false
- type: textarea
  attributes:
    label: Environment
    description: |
      examples:
        - **OS**: Ubuntu 20.04
        - **Node**: 13.14.0
        - **npm**: 7.6.3
    value: |
        - OS:
        - Node:
        - npm:
    render: markdown
  validations:
    required: false
- type: textarea
  attributes:
    label: Anything else?
    description: |
      Links? References? Anything that will give us more context about the issue you are encountering!

      Tip: You can attach images or log files by clicking this area to highlight it and then dragging files in.
  validations:
    required: false

进一步阅读