YAML Issue Template Configs

Overview

YAML is a data serialization language designed to be directly writable and readable by humans. *

YAML files are used in this repository to configure issue templates as they allow the creation of appealing and easy-to-use templates. There are .yaml files located under .github/ISSUE_TEMPLATES section for each template. The development of issue templates should done through issue-templates branch. This page will document using YAML to configure possible new templates or edit the existent ones.

Commenting In YAML

Similar to Python commenting in YAML requires a '#' symbol at the beginning of the line.

# This line is commented.

Template Root

Our root object (which continues for the entire document) will be a map, which is equivalent to a dictionary, hash, or object in other languages. *

For configuring our templates we need can set some of the keys of our template. Some of the important elements are

• name name of the template
• description description for template
• title a placeholder for issue title
• projects: predefined list of projects that the template is related to

To link a project one should follow the following format "OWNER/PROJECT-ID". Replace the OWNER and PROJECT-ID parts without removing quotations.

• labels predefined list of labels attached to the template if exist
• assignees predefined assignee list if exist
• body the content of the issue

See this for more information.

Body Elements

The body part of the configuration is a form.

A form is a set of elements for requesting user input. *

There are several form elements to look up for.

Component	Description
markdown	Markdown text that is displayed in the form to provide extra context to the user, but is not submitted.
textarea	A multi-line text field. Can provide in the markdown format.
input	A single-line text field.
dropdown	A dropdown menu with options
checkboxes	A set of checkboxes.

See this for more information.

Template Rules

The repository has several rules for each template to maintain standards. Make sure to follow them.

This section is open to changes.

• Each template should include the label 'template issue'. For task-related issues, etc one should also remember to all constant labels to the template like workload and priority labels if they are constant. For example, weekly meeting assignments are generally workload 2 and priority medium.
• Have input elements for reviewer and deadline sections if the issue is a task.
• Description field in the form of a textarea should be there in each template. If the template provides a base text for the description you can configure them in the value attribute of the textarea and leave the changing parts with XX.
• Acceptance criteria should also be there if can be applied to the issue. You can provide the acceptance criteria section using checkboxes component.

Example Issue Template

The repository currently has an example issue template. It almost utilizes all the capabilities of YAML configuration. Check weekly_meeting_notes.yaml for source code and you can also test it through issues section.

Reference

• https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms
• https://learnxinyminutes.com/docs/yaml/