Issue 模版
GitCode 提供了 Issue 模板功能,通过配置不同内容的 Issue 模板,可以帮助项目维护者更快地理解和解决问题,同时提升用户提出建议或反馈问题时的互动体验。本文将详细介绍如何创建和配置 Issue 模板。
什么是 Issue 模板?
Issue 模板是一种预定义的结构化格式,用于规范用户在创建 Issue 时提供的信息。通过模板,用户可以更清晰地描述问题或需求,而项目维护者也能更高效地获取关键信息,从而加快问题解决的速度。
模版配置位置
你可以将 Issue 模板放在项目的 .gitcode/
文件夹中(如不存在可自行创建),也可以放置在 docs/
或 .gitcode/ISSUE_TEMPLATE/
目录下,并在其中创建 ISSUE_TEMPLATE.md
文件。你可以在 .gitcode/ISSUE_TEMPLATE/
文件夹中创建多个模板文件,GitCode 将在该项目创建 Issue 时显示创建的模板以供使用。
模板配置必须放置在仓库的默认分支中。如果您在其他分支中创建模板,配置将不会生效,相关功能也无法被协作用户使用。
以下是一个使用了 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 的复现步骤 -->
如果需要在模版内使用分隔符,请勿使用3个"-"符号 “---”,以此避免与模版规则中的功能分割符号冲突,建议使用4个"-"符号“----”。
该模板在用户创建 Issue 时,自动生成以 [BUG]
开头的标题,并添加 bug
标签和指定负责人。同时,模板提供 BUG 类型
和 复现步骤
两个结构化字段,引导用户清晰描述问题。
目前 GitCode 支持以下几种 markdown 的 front-matter 配置:
字段 |
---|