为仓库配置议题模板

您可以自定义贡献者在仓库中打开新议题时可使用的模板。

本文内容

可以为组织或个人帐户的问题模板创建默认问题模板和默认配置文件。 有关详细信息，请参阅“创建默认的社区运行状况文件”。

创建议题模板

  1. 在 GitHub 上，导航到存储库的主页面。

  2. 在存储库名称下，单击 “设置”。 如果看不到“设置”选项卡，请选择“”下拉菜单，然后单击“设置”。

    存储库标头的屏幕截图，其中显示了选项卡。 “设置”选项卡以深橙色边框突出显示。

  3. 在“功能”部分的“问题”下，单击“设置模板” 。 可能需要启用“问题”并刷新页面，然后才能看到按钮。

存储库设置的“功能”部分的屏幕截图，其中勾选了“问题”设置，并显示了绿色的“设置模板”按钮。

  1. 使用“添加模板”下拉菜单，单击要创建的模板类型。

    展开的“添加模板”下拉菜单的屏幕截图，其中显示了标准“Bug 报告”和“功能请求”模板。 此外，还列出了“自定义模板”。

  2. 要在提交到存储库之前预览或编辑模板，请单击模板旁边的“预览和编辑”。

  3. 要编辑模板，请单击 ，然后在字段中键入以编辑其内容。

    问题模板预览的屏幕截图。 在模板名称的右侧，铅笔图标以深橙色轮廓显示。

  4. 要自动设置默认问题标题，将问题分配给对存储库具有读取权限的人，或将标签应用于从模板提出的问题，请使用“可选附加信息”下的字段。 还可使用 YAML frontmatter 格式中的 title、labels 或 assignees 将这些详细信息添加到问题模板中。

  5. 完成编辑和预览模板后，请单击页面右上角的“提供更改”。

  6. 在“提交消息”字段中，键入描述更改的提交消息。

  7. 在提交消息字段的下方，选择是直接将模板提交到默认分支，还是创建新分支并打开拉取请求。 有关拉取请求的详细信息，请参阅 关于拉取请求。

  8. 单击“提交更改”。 将这些更改合并到默认分支后，贡献者在仓库中打开新议题时便可使用该模板。

创建议题表单

Note

问题表单目前为 公共预览版，可能随时更改。

通过议题表单，您可以创建具有可自定义 Web 表单字段的议题模板。 您可以通过在仓库中使用议题表单鼓励贡献者包含特定的结构化信息。 议题表单使用 GitHub 表单架构以 YAML 编写。 有关详细信息，请参阅“GitHub 表单架构的语法”。 如果你不熟悉 YAML 并且想要了解详细信息，请参阅“在五分钟内了解 YAML”。

要在存储库中使用问题表单，必须创建一个新文件并将它添加到存储库中的 .github/ISSUE_TEMPLATE 文件夹。

下面是议题表单配置文件的示例。

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@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)
      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

下面是议题表单的呈现版本。

呈现的问题表单的屏幕截图，其中包含文本字段和下拉菜单的组合。

  1. 选择要创建议题表单的仓库。 您可以使用您有写入权限的现有仓库，或者创建一个新的仓库。 有关创建仓库的详细信息，请参阅 创建新仓库。
  2. 在存储库中，创建一个名为 .github/ISSUE_TEMPLATE/FORM-NAME.yml 的文件，然后将 FORM-NAME 替换为问题表单的名称。 有关在 GitHub 上创建新文件的详细信息，请参阅 创建新文件。
  3. 在新文件的正文中，键入议题表单的内容。 有关详细信息，请参阅“议题表单的语法”。
  4. 将文件提交到仓库的默认分支。 有关详细信息，请参阅“创建新文件”。

配置模板选择器

可以通过向 .github/ISSUE_TEMPLATE 文件夹添加 config.yml 文件来自定义用户在存储库中创建新问题时看到的问题模板选择器。

你可通过将 blank_issues_enabled 设置为 false 来鼓励贡献者使用问题模板。 如果将 blank_issues_enabled 设置为 true，则用户可以选择打开空白问题。

Note

如果使用旧工作流在 .github 文件夹中手动创建 issue_template.md 文件，并在“config.yml”文件中启用空白问题，则当用户选择打开空白问题时，将使用 issue_template.md 中的模板__。 如果您禁用空白议题，将永远不会使用模板。

如果你愿意在 GitHub 之外接收某些报告，可使用 contact_links 将用户引导到外部网站。

下面是“config.yml”文件的一个示例。

YAML
blank_issues_enabled: false
contact_links:
  - name: GitHub Community Support
    url: https://github.com/orgs/community/discussions
    about: Please ask and answer questions here.
  - name: GitHub Security Bug Bounty
    url: https://bounty.github.com/
    about: Please report security vulnerabilities here.

当文件合并到仓库的默认分支时，您的配置文件将自定义模板选择器。

  1. 在 GitHub 上，导航到存储库的主页面。

  2. 在文件列表上方，选择“Add file ”下拉菜单，然后单击“ Create new file”********。

    也可在左侧的文件树状视图中单击 。

    存储库主页的屏幕截图。 在文件列表上方，标有“添加文件”的按钮以深橙色框出。 在存储库的文件树状视图中，带加号图标的按钮也以深橙色框出。

  3. 在“文件名”字段中，键入 .github/ISSUE_TEMPLATE/config.yml。

  4. 在新文件的正文中，键入配置文件的内容。

  5. 单击“提交更改...”

  6. 在“提交消息”字段中，输入简短、有意义的提交消息，以描述对文件的更改。 您可以在提交消息中将提交归于多个作者。 有关详细信息，请参阅“创建有多个作者的提交”。

  7. 在提交消息字段下面，确定是要将提交添加到当前分支还是新分支。 如果当前分支是默认分支，则应选择为提交创建新分支，然后创建拉取请求。 有关详细信息，请参阅“创建拉取请求”。

    GitHub 拉取请求的屏幕截图，其中显示了一个单选按钮，用于直接提交到主分支或创建新分支。 已选择“新建分支”。

  8. 单击“提交更改”或“建议更改” 。

更改模板顺序

要设置问题模板在模板选择器中的显示顺序，可以更改模板文件名。 .github/ISSUE_TEMPLATE 中的模板按字母数字列出，按文件类型分组，并且 YAML 文件显示在 Markdown 文件之前。

要控制模板的顺序，请给文件名添加数字前缀。 例如：1-bug.yml、2-feature-request.yml 和 3-epic.yml。

如果有 10 个或更多模板，字母数字排序意味着 11-bug.yml 将位于 1-feature.yml 和 2-support.yml 之间。 要保留预期排序，可以在数字文件名前额外加上一个 0。 例如：01-feature.yml、02-support.yml 和 11-bug.yml。

其他阅读材料