跳到主要内容

Issue Template

GitCode provides an Issue template feature, which helps project maintainers understand and solve problems more quickly by configuring different content templates. It also enhances the interaction experience for users when they propose suggestions or report issues. This article will详细介绍 how to create and configure Issue templates.

What is an Issue Template?


An Issue template is a pre-defined structured format used to standardize the information provided by users when creating an Issue. Through the template, users can more clearly describe the problem or requirement, while project maintainers can efficiently obtain key information, thus accelerating the problem-solving process.

Template Configuration Location


You can place the Issue template in the .gitcode/ folder of the project (create it if it doesn't exist), or in the docs/ or .gitcode/ISSUE_TEMPLATE/ directory, and create an ISSUE_TEMPLATE.md file within it. You can create multiple template files in the .gitcode/ISSUE_TEMPLATE/ folder, and GitCode will display the created templates when an Issue is created for use.

issue-tem-web

issue-tem-new

提示

The template configuration must be placed in the default branch of the repository. If you create the template in another branch, the configuration will not take effect, and the related functions will not be available for collaborative users.

Here is an example of a repository file tree that uses GitCode Issue templates, showing the configuration location and file structure of the Issue templates:

➜ git:(main) tree -L 2 .
.
├── .gitcode # Compatible with the .github directory (prefer the .gitcode directory)
│ ├── ISSUE_TEMPLATE # Directory for Issue template configuration
│ │ ├── feature.yml # Issue form template for feature suggestions
│ │ ├── bug.yml # Issue form template for bug reports
│ │ ├── question.md # Markdown template for question consultation
│ │ └── config.yml # Template selector configuration file
│ └── issue_template.md # Blank Issue template (optional)
├── LICENSE
├── README.md
└── src
├── index.js
└── utils.js

5 directories, 8 files

How to Create an Issue Template


Currently, GitCode Issue templates support the following two types of input:

  • Markdown: Traditional Issue templates composed of several .md files. It generally provides guidelines for the title and body of user Issues, with weaker restrictions on users.
  • Form YAML: You can create Issue templates with customizable web form fields. You can use issue forms in your repository to encourage contributors to include specific structured information. Issue templates are written in YAML. For more details, see “YAML Form Syntax”. If you are unfamiliar with YAML and want detailed information, see “Learn YAML in Five Minutes”.

Markdown Template Configuration

In .md files, you can define basic properties of the template, such as the template name, title, default assignee, labels, etc., by configuring front-matter information. The main content will serve as the preset description when users create an Issue.

Here is a simple example of a Markdown template:

---
name: Bug Report (.md template)
about: Report an issue to help us improve
title: [BUG]
labels: ["bug"]
assignees: "f1325"
---

### Bug Type
<!-- Please describe the type of bug, such as UI, functionality, experience, etc. -->

### Reproduction Steps
<!-- Please describe the steps to reproduce the bug in detail -->
提示

If you need to use a separator within the template, do not use the three hyphen symbol “---”, to avoid conflicts with the separator symbol in the template rules. It is recommended to use four hyphens “----” instead.

image-pr-tem

This template automatically generates a title starting with [BUG] when a user creates an Issue, adds the bug label, and assigns it to the specified person. At the same time, the template provides two structured fields, Bug Type and Reproduction Steps, guiding users to clearly describe the issue.

image-20241231160817838

Currently, GitCode supports the following markdown front-matter configurations:

FieldDescriptionNotes
nameTemplate nameUse double quotes if it contains Chinese
aboutTemplate explanationUse double quotes if it contains Chinese
titleDefault title for the IssueUse double quotes if it contains Chinese
labelsLabels for the Issue, supports multipleMultiple labels should use brackets; if the label does not exist, it will not be displayed when creating an Issue
assigneesDefault assignee for the IssueUsername of the assignee

YAML Form Template Configuration

YAML format templates support more complex configurations, including pre-set assignees, labels, and custom form types (such as input boxes, dropdowns, radio buttons, checkboxes, code blocks, etc.).

Here is an example of a YAML template:

name: Bug Report (.yaml template)
description: Report an issue to help us improve
title: "[BUG] "
labels: ["bug"]
assignees:
- f3125
body:
- type: markdown
attributes:
value: |
## Thank you for your report!
Please check if this issue has already been reported before submitting.

- type: input
id: what-happened
attributes:
label: What happened?
description: Please describe the problem in as much detail as possible.
placeholder: Please enter detailed information here
validations:
required: true

- type: checkboxes
id: terms
attributes:
label: Confirmation
description: Please confirm the following information.
options:
- label: I have searched existing Issues and confirmed this is a new issue.
required: true
- label: I have read the relevant documentation.
required: false

- type: dropdown
id: version
attributes:
label: Affected Version
description: Please select the affected software version.
options:
- 1.0
- 2.0
- 3.0
- I'm not sure
validations:
required: true

The sample form effect is as follows:

image-20241231160915891

The specific field explanations are as follows:

FieldDescriptionNotes
nameTemplate name, requiredUsed to define the name of the template
descriptionTemplate explanation, requiredUsed to explain the purpose of the template
titleDefault title for the Issue, optionalUse double quotes if it contains Chinese
labelsLabels for the Issue, optional, supports multipleMultiple labels should use brackets; if the label does not exist, it will not be displayed when creating an Issue
assigneesDefault assignee for the Issue, optionalUsername of the assignee; if the user does not exist, it will be ignored
bodyForm configuration content, requiredSupports various form types; for detailed configuration, refer to YAML Form Syntax

Configuring the Template Selector (config.yml)

By adding a config.yml file in the .gitcode/ISSUE_TEMPLATE directory, you can customize the template selector that users see when creating an Issue.

Here is an example:

blank_issues_enabled: false  # Disable the option to create blank Issues
contact_links:
- name: GitCode Help Center
url: https://docs.gitcode.com/
about: We are always here to help you and answer any questions you may have about using GitCode

Field explanations in config.yml are as follows:

  • blank_issues_enabled: false: Disables the option for users to create blank Issues without using a template. If you allow creating blank Issues, change the value to true.
  • contact_links: Provides external resource links that users can access before creating an Issue to get help or information.
    • name: Link name, displayed on the Issue creation page.
    • url: Link address.
    • about: Brief description of the link.

Example effect:

image-20241231161034533

Whether it's a simple Markdown template or a complex YAML form template, they can help you better manage Issues in your project. We hope this article provides you with clear configuration guidance to help your project run efficiently.