Issue 模版

GitCode 提供了 Issue 模板功能，通过配置不同内容的 Issue 模板，可以帮助项目维护者更快地理解和解决问题，同时提升用户提出建议或反馈问题时的互动体验。本文将详细介绍如何创建和配置 Issue 模板。

什么是 Issue 模板？

Issue 模板是一种预定义的结构化格式，用于规范用户在创建 Issue 时提供的信息。通过模板，用户可以更清晰地描述问题或需求，而项目维护者也能更高效地获取关键信息，从而加快问题解决的速度。

模版配置位置

Issue 模板文件需要放置在项目的 .gitcode/ISSUE_TEMPLATE 目录下（兼容 .github 目录），您可以创建一个或多个 .md、.yml 或 .yaml 文件，每个文件将作为一个独立的模板。

提示

模板配置必须放置在仓库的默认分支中。如果您在其他分支中创建模板，配置将不会生效，相关功能也无法被协作用户使用。

以下是一个使用了 GitCode Issue 模版的仓库文件树示例，可以看到 Issue 模板的配置位置和文件结构：

➜ git:(main) tree -L 2 .
.
├── .gitcode  # 兼容 .github 目录（优先选择 .gitcode 目录）
│   ├── ISSUE_TEMPLATE    # Issue 模板配置目录
│   │   ├── feature.yml   # 适用于功能建议的 Issue 表单模板
│   │   ├── bug.yml       # 适用于 Bug 反馈的 Issue 表单模板
│   │   ├── question.md   # 适用于问题咨询的 Markdown 模板
│   │   └── config.yml    # 模板选择器配置文件
│   └── issue_template.md # Issue 空白模板（可选）
├── LICENSE
├── README.md
└── src
    ├── index.js
    └── utils.js

5 directories, 8 files

如何创建 Issue 模板

当前GitCode Issue模板支持如下两种填写类型：

Markdown：传统的 Issue 模板，由若干 .md 文件组成。一般用户 Issue 的标题和正文的规范提示，对用户限制较弱。
表单YAML：你可以创建具有可自定义 Web 表单字段的Issue模板。您可以通过在仓库中使用议题表单鼓励贡献者包含特定的结构化信息。 Issue模版使用 YAML 编写。有关详细信息，请参阅“YAML 表单语法”。如果你不熟悉 YAML 并且想要了解详细信息，请参阅“在五分钟内了解 YAML”。

Markdown 模版配置

在 .md 文件中，您可以通过配置 front-matter 信息来定义模板的基本属性，例如模板名称、标题、默认指派人、标签等。正文内容将作为用户创建 Issue 时的预设描述。

以下是一个简单的 Markdown 模板示例：

---
name: Bug 报告（.md模版）
about: 报告一个问题帮助我们改进
title: [BUG]
labels: ["bug"]
assignees: "f1325"
---

### BUG 类型
<!-- 请描述 BUG 的类型，例如 UI、功能、体验等 -->

### 复现步骤
<!-- 请详细描述 BUG 的复现步骤 -->

该模板在用户创建 Issue 时，自动生成以 [BUG] 开头的标题，并添加 bug 标签和指定负责人。同时，模板提供 BUG 类型 和 复现步骤 两个结构化字段，引导用户清晰描述问题。

目前 GitCode 支持以下几种 markdown 的 front-matter 配置：

字段	说明	备注
`name`	模板名称	含中文时需使用双引号
`about`	模板解释说明	含中文时需使用双引号
`title`	Issue 预设标题	含中文时需使用双引号
`labels`	Issue 的标签，支持多个	多个标签需使用中括号，若标签不存在则创建 Issue 时不显示
`assignees`	Issue 默认指派人	指派人的 username

表单YAML配置模板

YAML 格式的模板支持更复杂的配置，包括预设指派人、标签以及自定义表单类型（如输入框、下拉菜单、单选、多选、代码块等）。

以下是一个 YAML 模板示例：

name: Bug 报告（.yaml模版）
description: 报告一个问题帮助我们改进
title: "[BUG] "
labels: ["bug"]
assignees:
  - f3125
body:
  - type: markdown
    attributes:
      value: |
        ## 感谢您的报告！
        请在提交前检查该问题是否已被报告过。
  
  - type: input
    id: what-happened
    attributes:
      label: 发生了什么？
      description: 请尽可能详细地描述问题。
      placeholder: 请在这里输入详细信息
    validations:
      required: true
  
  - type: checkboxes
    id: terms
    attributes:
      label: 确认项
      description: 请确认以下信息。
      options:
        - label: 我已经搜索过现有的 Issue，确信这是一个新问题。
          required: true
        - label: 我已经阅读了相关文档。
          required: false
  
  - type: dropdown
    id: version
    attributes:
      label: 受影响的版本
      description: 请选择受影响的软件版本。
      options:
        - 1.0
        - 2.0
        - 3.0
        - 我不确定
    validations:
      required: true

示例表单效果如下：

具体字段释义如下：

字段	说明	备注
`name`	模板名称，必填	用于定义模板的名称
`description`	模板解释说明，必填	用于解释模板的作用
`title`	Issue 预设标题，可选	含中文时需使用双引号
`labels`	Issue 的标签，支持多个，可选	多个标签需使用中括号，若标签不存在则创建 Issue 时不显示
`assignees`	Issue 默认指派人，可选	指派人的 username，若用户不存在则忽略
`body`	表单配置内容，必填	支持多种表单类型，具体配置可参考 YAML 表单语法

配置模版选择器（config.yml）

通过在 .gitcode/ISSUE_TEMPLATE 目录下添加 config.yml 文件，您可以自定义用户在创建 Issue 时看到的模板选择器。

以下是一个示例：

blank_issues_enabled: false  # 禁用创建空白 Issue 的选项
contact_links:
  - name: GitCode 帮助中心
    url: https://docs.gitcode.com/
    about: 我们将随时为你提供帮助，解答你在 GitCode 使用过程中的各种疑问

config.yml 中的字段说明如下：

blank_issues_enabled: false：禁用用户创建不使用模板的空白 Issue。若允许创建空白 Issue，可将值改为 true。
contact_links：提供外部资源链接，用户在创建 Issue 前可访问这些资源获取帮助或信息。
- name：链接名称，显示在 Issue 创建页面。
- url：链接地址。
- about：链接的简短描述。

示例效果：

无论是简单的 Markdown 模板，还是复杂的 YAML 表单模板，都能帮助您更好地管理项目中的 Issue。希望本文能为您提供清晰的配置指导，助力您的项目高效运行。

什么是 Issue 模板？​

模版配置位置​

如何创建 Issue 模板​

Markdown 模版配置​

表单YAML配置模板​

配置模版选择器（config.yml）​