GitHub Issue and PR Templates¶

GitHub

Introduction¶

GitHub issue and pull request templates are powerful features that help standardize and streamline contributions to your project. They provide structured forms for contributors to fill out when creating issues or pull requests, ensuring that you receive all the necessary information upfront and reducing back-and-forth communication.

This guide explains how GitHub templates work, how they’re configured in this project, and how you can customize them for your own needs.

What Are GitHub Templates?¶

GitHub templates are pre-defined forms that automatically populate when someone creates a new issue or pull request in your repository. They help:

  • Guide contributors on what information to provide

  • Collect consistent, structured data for each submission

  • Improve the quality of bug reports and feature requests

  • Streamline the review process

  • Reduce incomplete submissions

Templates in This Project¶

This project includes several template types:

Issue Templates¶

We’ve created three distinct issue templates using GitHub’s YAML-based issue forms:

  1. Bug Report (bug-report.yml): For reporting errors or unexpected behavior

  2. Feature Request (feature-request.yml): For suggesting new features or enhancements

  3. Documentation Request (documentation-request.yml): For requesting new or improved documentation

Each template collects specific information relevant to that type of issue, using various form components like dropdowns, text areas, and checkboxes.

Pull Request Template¶

We use a standard Markdown-based pull request template (PULL_REQUEST_TEMPLATE.md) that prompts contributors to:

  • Describe the changes they’ve made

  • Reference related issues

  • Confirm they’ve tested their changes

  • List any required follow-up work

How Templates Work¶

When a contributor clicks “New Issue” on your repository, they’ll see options for each of your configured templates:

[Bug Report]  [Feature Request]  [Documentation Request]  [Open a blank issue]

They select the appropriate template, which presents them with a form to complete. Once submitted, the issue is created with all the structured information and any automatically applied labels.

Pull request templates work similarly but are automatically loaded when someone creates a new pull request.

Template Configuration¶

Issue Templates Structure¶

Issue templates are stored in the .github/ISSUE_TEMPLATE/ directory as YAML files. Each template has:

  • A name and description

  • An optional title prefix

  • Optional automatic labels

  • A body with form elements

Anatomy of a Template¶

Here’s an example of the structure for our feature request template:

name: Feature Request
description: Suggest a new feature or enhancement
title: "[FEATURE]: "
labels: ["enhancement", "feature-request"]

body:
  - type: markdown
    attributes:
      value: |
        ## Feature Request
        Thanks for taking the time to suggest a new feature!

  - type: input
    id: feature-title
    attributes:
      label: Feature Title
      description: A concise name for this feature
      placeholder: e.g., Add Dark Mode Support
    validations:
      required: true

  # Additional form elements...

Form Elements¶

Issue templates can include various input types:

  • markdown: For explanatory text and formatting

  • input: For single-line text input

  • textarea: For multi-line text input

  • dropdown: For selecting from predefined options

  • checkboxes: For multiple-choice selections

How to Customize Templates¶

If you’ve created your own project from this template, you can customize the issue and PR templates to suit your needs:

  1. Navigate to the .github/ISSUE_TEMPLATE/ directory in your repository

  2. Edit the existing YAML files or create new ones

  3. For PR templates, edit the PULL_REQUEST_TEMPLATE.md file in the repository root

Advanced Configuration¶

For more advanced needs, you can create a config.yml file in the .github/ISSUE_TEMPLATE/ directory to:

  • Control whether blank issues are allowed

  • Add external links for specific types of issues

  • Customize the template selection experience

Example:

blank_issues_enabled: false
contact_links:
  - name: Security Vulnerabilities
    url: https://example.com/security
    about: Please report security vulnerabilities here instead of GitHub issues

Starting point for new issue templates¶

The templates included in this project are designed to be a good starting point, but you should customize them based on your specific project needs and workflow.

Further Resources¶