Setting Up CONTRIBUTING, ISSUE_TEMPLATE, and PULL_REQUEST_TEMPLATE Files in GitHub: A Complete Guide

Adding CONTRIBUTING.md, ISSUE_TEMPLATE.md, and PULL_REQUEST_TEMPLATE.md to your repository root or .github directory automatically surfaces contribution guidelines and pre-populates issue and PR forms, reducing maintainer overhead and improving contribution quality.

The tiimgreen/github-cheat-sheet repository demonstrates how strategic placement of these three files creates a self-service contribution pipeline. When properly configured, these templates guide contributors through your workflow before maintainers ever see the submission, ensuring every issue includes reproduction steps and every PR references related tickets.

Where to Place Repository Template Files

GitHub scans for these files in two locations: the repository root or a hidden .github/ directory at the top level.

• Root directory: Works immediately but clutters the file listing when you have many top-level configuration files.
• .github/ directory: Keeps the repository root tidy while centralizing all GitHub-specific configurations. This is the recommended approach for active projects with multiple workflows, actions, or documentation files.

According to the source code in tiimgreen/github-cheat-sheet, GitHub automatically detects these files regardless of which location you choose, though the .github/ convention has become the industry standard for maintaining clean repository structures.

Creating a CONTRIBUTING.md File

The CONTRIBUTING.md file serves as your repository's constitution for external contributors. When present, GitHub displays a prominent "Contributing" link on both the new-issue and new-pull-request pages, routing potential contributors to your guidelines before they submit.

In tiimgreen/github-cheat-sheet/CONTRIBUTING.md, the file establishes clear norms:

# Contributing to GitHub‑Cheat‑Sheet

## How to propose a change

1. Fork the repository.
2. Create a branch (`git checkout -b my‑feature`).
3. Add your changes, **including tests and documentation**.
4. Run the test suite (`npm test` or `make test` – adjust to your language).
5. Submit a Pull Request.

## Style guide

- Use `###` for top‑level headings.
- Wrap shell commands in triple‑backticks with `bash`.
- End the PR description with a "Read more about …" link.

Key elements to include:

• Workflow steps: Fork, branch, test, and PR submission process.
• Style requirements: Coding standards, commit message formats, and documentation expectations.
• External links: References to GitHub documentation or project-specific resources.

Setting Up Issue Templates

Issue templates eliminate vague bug reports by pre-populating the submission form with structured sections. Place ISSUE_TEMPLATE.md in the root or .github/ directory, or create a .github/ISSUE_TEMPLATE/ folder containing multiple specialized templates.

When you use the directory approach, GitHub presents a selector allowing contributors to choose between bug reports, feature requests, or documentation issues. The tiimgreen/github-cheat-sheet README references this pattern for organizing diverse feedback types.

Single template example:

<!-- .github/ISSUE_TEMPLATE.md -->

### Description

A clear and concise description of the issue.

### Steps to Reproduce

1. Environment details (OS, version, dependencies)
2. Minimal code example
3. Expected vs. actual behavior

### Checklist

- [ ] I have searched existing issues to avoid duplicates.
- [ ] I have provided a minimal reproduction case.

**Read more about writing good issues**: [GitHub Docs](https://help.github.com/articles/about-issue-and-pull-request-templates/)

Multiple template structure:

• .github/ISSUE_TEMPLATE/bug_report.md – Contains YAML frontmatter defining the template name, description, default labels, and assignees.
• .github/ISSUE_TEMPLATE/feature_request.md – Focuses on use cases and implementation ideas.

Configuring Pull Request Templates

The PULL_REQUEST_TEMPLATE.md file automatically populates the PR description field with your required sections, ensuring contributors document testing procedures and reference related issues before submission.

As implemented in the cheat-sheet repository guidance, effective PR templates include:

<!-- .github/PULL_REQUEST_TEMPLATE.md -->

### What does this PR do?

- Brief description of the change.

### Related issues

Closes # (or references) ...

### How was this tested?

- List of steps taken to verify the change.

### Checklist

- [ ] Tests added (if applicable)
- [ ] Documentation updated
- [ ] `npm test` (or equivalent) passes

**Read more about PR best practices**: [GitHub Pull Request Templates](https://help.github.com/articles/about-pull-request-templates/)

GitHub applies this template automatically when a user initiates a pull request, regardless of whether they use the web interface, GitHub Desktop, or the CLI.

Best Practices for GitHub Repository Templates

Centralize contribution guidance in CONTRIBUTING.md. Maintain coding standards and procedural documentation separately from issue/PR templates. This separation allows you to update workflow rules without modifying multiple template files.

Use explicit section headings. Structure templates with ### headings for "Description," "Steps to Reproduce," and "Expected Behavior" to render clean, scannable forms.

Implement checklists for quality gates. Include Markdown task lists (- [ ]) for common requirements like "Tests added" or "Documentation updated." This creates visual confirmation that contributors have completed prerequisite steps.

Leverage multiple templates for different workflows. When your project receives distinct types of feedback (bug fixes, feature proposals, security reports), create separate files in .github/ISSUE_TEMPLATE/ to route each type to the appropriate maintainers with pre-applied labels.

Document templates in your README. Reference your issue and PR templates in the repository's main documentation so contributors know these standards exist before they click "New Issue."

Summary

• Place CONTRIBUTING.md, ISSUE_TEMPLATE.md, and PULL_REQUEST_TEMPLATE.md in the .github/ directory to keep your repository root organized.
• CONTRIBUTING.md automatically generates links on GitHub's issue and PR creation pages, directing contributors to your guidelines.
• Issue templates pre-populate bug reports with structured fields, while PR templates ensure contributors document testing and references.
• Multiple templates are supported through subdirectories: .github/ISSUE_TEMPLATE/ and .github/PULL_REQUEST_TEMPLATE/.
• Version control integration means template updates immediately apply to all future contributions, maintaining consistent standards as your project evolves.

Frequently Asked Questions

What happens if I put templates in both the root and .github directory?

GitHub prioritizes files in the .github/ directory over those in the root. If both locations contain an ISSUE_TEMPLATE.md, the version in .github/ will be used exclusively. To avoid confusion, maintain templates in only one location, preferably the .github/ folder.

Can I have different templates for bugs and features?

Yes. Create a .github/ISSUE_TEMPLATE/ directory and add separate Markdown files for each template type, such as bug_report.md and feature_request.md. Include YAML frontmatter at the top of each file defining the name, about description, default labels, and assignees. GitHub will display a template chooser when users create new issues.

Do these files work for private repositories?

Absolutely. GitHub processes CONTRIBUTING.md, issue templates, and PR templates identically across public and private repositories. The files function the same way regardless of repository visibility, though only users with access to the private repo will see the templates when creating issues or pull requests.

How do I update templates without breaking existing issues?

Since these files are version-controlled, changes only affect new issues and pull requests created after the update. Existing issues retain their original descriptions. If you need to modify template language, simply edit the file and commit; the changes take effect immediately for the next contributor without impacting historical tickets.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}