Skip to main content

Overview

Templates provide structure and consistency for issues and pull requests. They guide contributors to include necessary information, making it easier to triage, review, and resolve contributions efficiently.
Templates are stored in .github/ and automatically appear when users create issues or pull requests.

Available Templates

Issue Templates

Issue templates help users report bugs, request features, or ask questions with all the necessary context.

Bug Report Template

The bug report template (bug_report.yml) provides a structured form for reporting bugs:
name: Bug report
description: Report a bug
labels: [bug]
body:
  - type: textarea
    id: description
    attributes:
      label: Description
      description: What happened and what you expected
    validations:
      required: true
What it includes:
  • Name: “Bug report” (appears in issue template selector)
  • Description: Brief explanation of the template’s purpose
  • Labels: Automatically applies the bug label
  • Form Fields:
    • Description (required): Free-form text area for bug details
How users see it: When creating a new issue, users select “Bug report” and see a form with a description field. The form requires them to explain:
  • What happened (actual behavior)
  • What they expected (expected behavior)
  • Steps to reproduce
  • Environment details

Pull Request Template

The PR template provides a checklist to ensure contributors include necessary information:
## Description

## Checklist
- [ ] Lint & tests OK
- [ ] Security reviewed
- [ ] Docs updated
What it includes:
1

Description Section

Free-form area where contributors explain:
  • What changes were made
  • Why the changes were necessary
  • How the solution works
  • Any relevant context or background
2

Quality Checklist

Ensures all PRs meet quality standards:
  • Lint & tests OK: Code passes all automated checks
  • Security reviewed: Changes don’t introduce vulnerabilities
  • Docs updated: Documentation reflects code changes
The checklist is a guide, not enforcement. Consider adding branch protection rules to require actual CI checks before merging.

Using Templates

For Contributors

Creating a Bug Report

1

Navigate to Issues

Go to the Issues tab and click “New issue”
2

Select Template

Choose “Bug report” from the template options
3

Fill Out Form

Complete the description field with:
**What happened:**
When I run `pytest`, I get a ModuleNotFoundError for 'src.utils'.

**Expected behavior:**
Tests should run successfully.

**Steps to reproduce:**
1. Clone the repository
2. Run `pip install -e ".[dev]"`
3. Run `pytest`

**Environment:**
- Python 3.12
- Ubuntu 22.04
- pytest 8.0.0
4

Submit

Click “Submit new issue” - the bug label is applied automatically

Creating a Pull Request

1

Push Your Branch

Push your feature branch to the repository:
git push origin feature/new-feature
2

Open PR

Navigate to “Pull requests” and click “New pull request”
3

Fill Template

The PR template appears automatically. Replace sections with your content:
## Description

Adds user authentication using JWT tokens. This enables secure
API access and user session management.

Changes:
- Add JWT token generation and validation
- Implement login/logout endpoints
- Add authentication middleware
- Update API documentation

## Checklist
- [x] Lint & tests OK
- [x] Security reviewed
- [x] Docs updated
4

Submit

Click “Create pull request” to submit for review

For Maintainers

Enforcing Template Usage

While you can’t force template usage, you can encourage it:
  1. Branch Protection: Require reviews and status checks
  2. Automated Comments: Use GitHub Actions to comment on PRs missing checklist items
  3. Contributing Guidelines: Document template expectations in CONTRIBUTING.md
  4. Review Process: Ask for missing information during review

Template Validation

Create a workflow to validate PR descriptions:
.github/workflows/pr-validation.yml
name: PR Validation
on:
  pull_request:
    types: [opened, edited]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - name: Check PR description
        uses: actions/github-script@v7
        with:
          script: |
            const body = context.payload.pull_request.body || '';
            if (!body.includes('## Description')) {
              core.setFailed('PR must include a description section');
            }
            if (!body.includes('- [x] Lint & tests OK')) {
              core.warning('Remember to check the quality checklist');
            }

Customizing Templates

Extending the Bug Report

Add more fields to gather additional information:
name: Bug report
description: Report a bug
labels: [bug]
body:
  - type: textarea
    id: description
    attributes:
      label: Description
      description: What happened and what you expected
    validations:
      required: true
  
  - type: textarea
    id: reproduce
    attributes:
      label: Steps to Reproduce
      description: Clear steps to reproduce the issue
      placeholder: |
        1. Go to '...'
        2. Click on '...'
        3. See error
    validations:
      required: true
  
  - type: dropdown
    id: severity
    attributes:
      label: Severity
      description: How severe is this bug?
      options:
        - Critical (system down)
        - High (major functionality broken)
        - Medium (functionality impaired)
        - Low (minor issue)
    validations:
      required: true
  
  - type: input
    id: version
    attributes:
      label: Version
      description: What version are you running?
      placeholder: v1.2.3
    validations:
      required: true
  
  - type: textarea
    id: logs
    attributes:
      label: Relevant Logs
      description: Paste any relevant logs or error messages
      render: shell
  
  - type: checkboxes
    id: checks
    attributes:
      label: Pre-submission Checklist
      options:
        - label: I have searched for similar issues
          required: true
        - label: I am using the latest version
          required: true

Enhanced PR Template

Add more structure and guidance:
## Description
<!-- Provide a clear and concise description of your changes -->

### Type of Change
<!-- Mark the relevant option with an 'x' -->
- [ ] Bug fix (non-breaking change fixing an issue)
- [ ] New feature (non-breaking change adding functionality)
- [ ] Breaking change (fix or feature causing existing functionality to break)
- [ ] Documentation update
- [ ] Refactoring (no functional changes)

## Changes Made
<!-- List the specific changes in bullet points -->
- 
- 
- 

## Related Issues
<!-- Link related issues (e.g., "Fixes #123", "Relates to #456") -->
Closes #

## Testing
<!-- Describe how you tested your changes -->

### Test Coverage
- [ ] Unit tests added/updated
- [ ] Integration tests added/updated
- [ ] Manual testing completed

### Test Results

Paste test output here


## Screenshots
<!-- If applicable, add screenshots to demonstrate changes -->

## Performance Impact
<!-- Describe any performance implications -->
- [ ] No performance impact
- [ ] Performance improved
- [ ] Performance degraded (explained below)

## Security Considerations
<!-- Describe any security implications -->
- [ ] No security impact
- [ ] Security improved
- [ ] New security considerations (explained below)

## Documentation
- [ ] Code comments added/updated
- [ ] README updated
- [ ] API documentation updated
- [ ] Migration guide created (for breaking changes)

## Checklist
- [ ] Lint & tests OK
- [ ] Security reviewed
- [ ] Docs updated
- [ ] Reviewed my own code
- [ ] Added tests for new functionality
- [ ] All tests pass locally
- [ ] No console warnings/errors
- [ ] Branch is up to date with main

## Additional Notes
<!-- Any additional information reviewers should know -->

Adding Feature Request Template

Create a new template for feature requests:
.github/ISSUE_TEMPLATE/feature_request.yml
name: Feature request
description: Suggest a new feature or enhancement
labels: [enhancement]
body:
  - type: textarea
    id: problem
    attributes:
      label: Problem Statement
      description: What problem does this feature solve?
      placeholder: I'm frustrated when...
    validations:
      required: true
  
  - type: textarea
    id: solution
    attributes:
      label: Proposed Solution
      description: How would you like this to work?
      placeholder: I would like to...
    validations:
      required: true
  
  - type: textarea
    id: alternatives
    attributes:
      label: Alternatives Considered
      description: What alternative solutions have you considered?
  
  - type: textarea
    id: additional
    attributes:
      label: Additional Context
      description: Any other context, screenshots, or examples

Adding Question Template

Help users ask better questions:
.github/ISSUE_TEMPLATE/question.yml
name: Question
description: Ask a question about the project
labels: [question]
body:
  - type: markdown
    attributes:
      value: |
        Thanks for your interest! Before asking:
        - Check existing issues and discussions
        - Review the documentation
        - Search Stack Overflow
  
  - type: textarea
    id: question
    attributes:
      label: Question
      description: What would you like to know?
    validations:
      required: true
  
  - type: textarea
    id: context
    attributes:
      label: Context
      description: What are you trying to accomplish?
  
  - type: textarea
    id: tried
    attributes:
      label: What I've Tried
      description: What have you already attempted?

Template Configuration

Issue Template Chooser

Customize the issue template selection screen:
.github/ISSUE_TEMPLATE/config.yml
blank_issues_enabled: false
contact_links:
  - name: Documentation
    url: https://docs.example.com
    about: Check the documentation before opening an issue
  - name: Discussions
    url: https://github.com/YOUR_ORG/YOUR_REPO/discussions
    about: Ask questions and discuss ideas
  - name: Security Issues
    url: https://github.com/YOUR_ORG/YOUR_REPO/security/advisories/new
    about: Report security vulnerabilities privately

Multiple PR Templates

Create different PR templates for different types of changes:
.github/
  PULL_REQUEST_TEMPLATE/
    bugfix.md
    feature.md
    hotfix.md
  pull_request_template.md  # Default template
Users can select a template by adding a query parameter:
https://github.com/YOUR_ORG/YOUR_REPO/compare/main...feature?template=feature.md

Best Practices

Keep It Simple

Start with minimal templates and add fields based on actual needs

Provide Examples

Include placeholder text showing what good submissions look like

Make Required Clear

Mark required fields explicitly and explain why they’re needed

Link Resources

Reference documentation, contributing guides, and related resources

Writing Effective Templates

Instead of vague labels:
## Information
Use specific, actionable prompts:
## What changed and why?
Too few fields → Missing critical information Too many fields → Contributors skip the templateFind the balance by:
  • Making only essential fields required
  • Using dropdowns for categorization
  • Providing good defaults
  • Grouping related fields
Monitor how templates are used:
  • Are contributors filling them out?
  • Is important information still missing?
  • Are any fields consistently left blank?
Adjust templates based on patterns you observe.

Integration with Workflows

Templates work seamlessly with GitHub Actions. Here’s how they integrate with your existing CI/CD:

Automatic Labeling

Templates can add labels automatically:
labels: [bug, needs-triage]
Then create workflows that trigger on specific labels:
name: Bug Triage
on:
  issues:
    types: [labeled]
jobs:
  triage:
    if: contains(github.event.issue.labels.*.name, 'bug')
    runs-on: ubuntu-latest
    steps:
      - name: Add to project board
        uses: actions/[email protected]
        with:
          project-url: https://github.com/orgs/YOUR_ORG/projects/1

PR Checks

Ensure PRs meet standards defined in the template:
name: PR Checks
on:
  pull_request:
    types: [opened, edited, synchronize]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - name: Check description length
        uses: actions/github-script@v7
        with:
          script: |
            const body = context.payload.pull_request.body || '';
            if (body.length < 50) {
              core.setFailed('PR description is too short');
            }
      
      - name: Check checklist completion
        uses: actions/github-script@v7
        with:
          script: |
            const body = context.payload.pull_request.body || '';
            const checked = (body.match(/- \[x\]/gi) || []).length;
            const total = (body.match(/- \[ \]/gi) || []).length + checked;
            
            if (checked < total) {
              core.warning(`Checklist: ${checked}/${total} items completed`);
            }

Troubleshooting

If templates don’t show up:
  1. Check file location (must be in .github/ISSUE_TEMPLATE/ or .github/)
  2. Verify YAML syntax with a validator
  3. Ensure file has correct extension (.yml or .md)
  4. Check file is committed to the default branch
  5. Clear browser cache and reload
If form validation fails:
validations:
  required: true  # Not 'required: yes'
Use boolean values, not strings.
Users can bypass templates by:
  • Creating blank issues (if enabled)
  • Using API or CLI tools
  • Manually removing template content
To encourage usage:
  • Set blank_issues_enabled: false in config.yml
  • Use automation to comment on incomplete issues
  • Document expectations in CONTRIBUTING.md
Learn from successful open-source projects:
  • Next.js: Comprehensive bug report with version detection
  • React: Multiple issue templates for bugs, features, and questions
  • TypeScript: Detailed PR template with performance considerations
  • VS Code: Issue forms with automatic environment detection

Build docs developers (and LLMs) love