Issue Template

GitCode provides the Issue template feature, which helps project maintainers understand and resolve issues more quickly by configuring different content templates. It also enhances the interaction experience for users when they suggest improvements or report problems. This article will detail how to create and configure Issue templates.

What is an Issue Template?

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

Template Configuration Location

You can place the Issue template in the .gitcode/ folder under the root directory of your project, or create an ISSUE_TEMPLATE.md file in the docs/ or .gitcode/ISSUE_TEMPLATE/ folder. If you create multiple template files in the .gitcode/ISSUE_TEMPLATE/ folder, GitCode will provide a list of these templates for contributors to choose from when creating an Issue.

提示

Template configurations must be placed in the default branch of the repository. If you create templates in other branches, the configuration will not take effect, and related functions cannot be used by collaborative users.

The following is an example of a repository file tree using a GitCode Issue template, showing the configuration location and file structure of the Issue template:

➜ git:(main) tree -L 2 .
.
├── .gitcode  # Compatible with the .github directory (prefer the .gitcode directory)
│   ├── ISSUE_TEMPLATE    # Issue template configuration directory
│   │   ├── feature.yml   # Issue form template for feature suggestions
│   │   ├── bug.yml       # Issue form template for bug feedback
│   │   ├── question.md   # Markdown template for problem consultation
│   │   └── config.yml    # Template selector configuration file
│   └── issue_template.md # Optional blank Issue template
├── 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 filling formats:

Markdown: Traditional Issue templates, consisting of several .md files. They generally provide normative prompts 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. By using issue forms in your repository, you can 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 to learn more, see “Learn YAML in Five Minutes”.

Markdown Template Configuration

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

Here is a simple Markdown template example:

---
name: Bug Report (.md Template)
about: Report a problem 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 -->

When this template is used to create an Issue, it automatically generates a title starting with [BUG], adds the bug label, and assigns a designated person. At the same time, the template provides two structured fields, Bug Type and Reproduction Steps, guiding users to clearly describe the problem.

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

Field	Description	Notes
`name`	Template name	Double quotes are required if the name contains Chinese
`about`	Template explanation	Double quotes are required if the description contains Chinese
`title`	Preset title for the Issue	Double quotes are required if the title contains Chinese
`labels`	Labels for the Issue, supports multiple	Multiple labels require square brackets; if the label does not exist, it will not display when creating an Issue
`assignees`	Default assignee for the Issue	Username of the assignee; if the user does not exist, it will be ignored

Form YAML Configuration Template

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

Here is a YAML template example:

name: Bug Report (.yaml Template)
description: Report a problem 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 been reported before before submitting.
  
  - type: input
    id: what-happened
    attributes:
      label: What happened?
      description: Please describe the problem as detailed as possible.
      placeholder: Please enter the detailed information here
    validations:
      required: true
  
  - type: checkboxes
    id: terms
    attributes:
      label: Confirmation items
      description: Please confirm the following information.
      options:
        - label: I have searched for existing Issues and am sure this is a new one.
          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 example form effect is as follows:

The specific field definitions are as follows:

Field	Description	Notes
`name`	Template name, required	Used to define the name of the template
`description`	Template explanation, required	Used to explain the purpose of the template
`title`	Preset title for the Issue, optional	Double quotes are required if the title contains Chinese
`labels`	Labels for the Issue, supports multiple, optional	Multiple labels require square brackets; if the label does not exist, it will not display when creating an Issue
`assignees`	Default assignee for the Issue, optional	Username of the assignee; if the user does not exist, it will be ignored
`body`	Form configuration content, required	Supports various form types; for detailed configurations, 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 will always provide help and answer any questions you may have during your use of GitCode

The field explanations in config.yml are as follows:

blank_issues_enabled: false: Disables the option for users to create blank Issues without templates. If you allow blank Issues, change the value to true.
contact_links: Provides external resource links. Users can access these resources 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:

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

What is an Issue Template?​

Template Configuration Location​

How to Create an Issue Template​

Markdown Template Configuration​

Form YAML Configuration Template​

Configuring the Template Selector (config.yml)​