YAML Form Syntax

The platform supports creating custom Issue templates using YAML syntax, which allows project maintainers to predefine fields that contributors need to fill in. Using YAML to build templates makes it easier to create and maintain templates, and also provides clear guidance for contributors to ensure they provide all necessary information. This simple help document hopes to be of assistance to you.

Basic Structure

A basic Issue template usually contains the following parts:

• name: The name of the template (required).
• description: The description of the template, guiding contributors on why and how to use this template (required).
• title: The preset Issue title (optional).
• labels: Tags automatically added to the Issue (optional).
• assignees: Users automatically assigned (optional).
• body: The body of the template, containing a series of fields to collect information (optional).

YAML Template Example

name: Bug Report
description: Use this template to report bugs in the software.
title: "[BUG] Specific Issue Name"
labels: ["bug"]
assignees: 
  - username1
  - username2

body:
  - type: markdown
    attributes:
      value: |
        ## Description of the Bug
        Please describe the bug you encountered as thoroughly as possible.

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

  - type: textarea
    id: reproduction
    attributes:
      label: Steps to Reproduce
      description: Briefly describe how to reproduce this issue.
      placeholder: 1. Go to '...'
                  2. Click '....'
                  3. Scroll down to '....'
                  4. See the error
    validations:
      required: true

  - type: checkboxes
    id: version
    attributes:
      label: Affected Version
      description: Check all affected versions.
      options:
        - label: v1.0
          required: false
        - label: v2.0
          required: false

  - type: dropdown
    id: os
    attributes:
      label: Operating System
      description: The operating system you are using.
      options:
        - label: Windows
        - label: macOS
        - label: Linux
        - label: Other
    validations:
      required: true

Form Element Definitions

Key	Description	Required	Type	Default	Valid Values
type	The type of the element.	Required	String	-	checkboxes dropdown input markdown textarea
id	The identifier of the element, unless type is set to markdown. It can only contain letters, numbers, -, and _. It must be unique within the form definition. If an id is configured, it serves as the canonical identifier for the field in the URL query parameter prefill.	Optional	String	-	-
attributes	A set of key-value pairs defining the element's properties.	Required	Map	-	-
validations	A set of key-value pairs setting constraints on the element.	Optional	Map	-	-

Explanation of Form Element Types

You can choose one of the following types of form elements. Each type has its own attributes and validations:

• markdown: Used to add static text to provide additional context for users, but does not submit anything.
• input: A single-line text field suitable for short text input.
• textarea: A multi-line text field suitable for longer descriptions or explanations; contributors can also attach files in this field.
• checkboxes: Multiple checkboxes allowing users to select multiple options.
• dropdown: A dropdown menu allowing users to select one option from multiple options.

markdown

Used to add static text to provide additional context for users, but does not submit anything.

Attributes Definition

Key	Description	Required	Type	Default	Valid Values
value	The rendered text. Supports Markdown format.	Required	String	-	-

YAML processing treats the hash symbol as a comment. To insert a Markdown heading, enclose the text in quotes. For multi-line text, you can use the pipe operator.

Here is an example:

body:
- type: markdown
  attributes:
    value: "## Thank you for your feedback on our project, which will make us better"
- type: markdown
  attributes:
    value: |
      Thank you for taking a few minutes to give us feedback on our shortcomings.

input

A single-line text field suitable for short text input.

Attributes Definition

Key	Description	Required	Type	Default	Valid Values
label	A short description expected from the user, also displayed in the form.	Required	String	-	-
description	A description of the field providing context or guidance, displayed in the form.	Optional	String	Empty string	-
placeholder	A semi-transparent placeholder shown when the field is empty.	Optional	String	Empty string	-
value	Pre-filled text in the field.	Optional	String	-	-

Validations Definition

Key	Description	Required	Type	Default	Valid Values
required	Prevents the form from being submitted before the element is completed. Applies only to public projects.	Optional	Boolean	false	-

Here is an example:

body:
- type: input
  id: input
  attributes:
    label: Frequency of the bug
    description: "How often do you encounter this bug?"
    placeholder: "For example: Once every two days when I access the login page"
  validations:
    required: true

textarea

A multi-line text field suitable for longer descriptions or explanations, where contributors can also attach files.

Attributes Definition

Key	Description	Required	Type	Default	Valid Values
label	A short description expected from the user, also displayed in the form.	Required	String	-	-
description	A description of the field providing context or guidance, displayed in the form.	Optional	String	Empty string	-
placeholder	A semi-transparent placeholder shown when the field is empty.	Optional	String	Empty string	-
value	Pre-filled text in the field.	Optional	String	-	-
render	If provided, the submitted text will be formatted as a code block. When this key is provided, the text area will not expand for file attachments or Markdown editing.	Optional	String	-	Known languages. For more information, see language type definitions.

Validations Definition

Key	Description	Required	Type	Default	Valid Values
required	Prevents the form from being submitted before the element is completed. Applies only to public projects.	Optional	Boolean	false	-

Here is an example:

body:
- type: textarea
  id: repro
  attributes:
    label: Steps to Reproduce
    description: "How did you trigger this bug? Please walk us through the steps to reproduce it."
    value: |
      1.
      2.
      3.
      ...
    render: bash
  validations:
    required: true

checkboxes

Multiple checkboxes allowing users to select multiple options.

Attributes Definition

Key	Description	Required	Type	Default	Valid Values
label	A short description expected from the user, also displayed in the form.	Required	String	-	-
description	A description of the checkboxes, displayed in the form. Supports Markdown formatting.	Optional	String	Empty string	-
options	A list of checkboxes the user can select from. See below for syntax.	Required	Array	-	-

For each item in the options array, you can set the following keys.

Key	Description	Required	Type	Default	Valid Values
label	The identifier of the option, displayed in the form. Supports Markdown for bold or italic text formatting and hyperlinks.	Required	String	-	-
required	Prevents the form from being submitted before the element is completed. Applies only to public projects.	Optional	Boolean	false	-

Validations Definition

Key	Description	Required	Type	Default	Valid Values
required	Prevents the form from being submitted before the element is completed. Applies only to public projects.	Optional	Boolean	false	-

Here is an example:

body:
- type: checkboxes
  id: operating-systems
  attributes:
    label: Which operating system are you using?
    description: Select at least one.
    options:
      - label: macOS
      - label: Windows
      - label: Linux

dropdown

A dropdown menu allowing users to select one option from multiple options.

Attributes Definition

Key	Description	Required	Type	Default	Valid Values
label	A short description expected from the user, also displayed in the form.	Required	String	-	-
description	A description of the field providing context or guidance, displayed in the form.	Optional	String	Empty string	-
multiple	Determines whether the user can select multiple options.	Optional	Boolean	false	-
options	The options the user can select from. Must not be empty, and all options must be different.	Optional	String array	-	-
default	The index of the default selected option in the options array. When a default option is specified, "None" or "n/a" cannot be included as an option.	Optional	int	-	-

Validations Definition

Key	Description	Required	Type	Default	Valid Values
required	Prevents the form from being submitted before the element is completed. Applies only to public projects.	Optional	Boolean	false	-

Here is an example:

body:
- type: dropdown
  id: download
  attributes:
    label: How did you find out about this software?
    options:
      - AtomGit
      - CSDN
      - Github
    default: 0
  validations:
    required: true