{
    "slug": "pr_description_template",
    "term": "Pull Request Description Templates",
    "category": "style",
    "difficulty": "beginner",
    "short": "Structured PR templates in .github/PULL_REQUEST_TEMPLATE.md that prompt authors for context, testing evidence, and checklists — improving review quality and reducing reviewer cognitive load.",
    "long": "A good PR template includes: Summary (what does this change do?), Motivation (why is this change needed? links to issue), Type of change (bug fix, feature, breaking change, refactor), How to test (steps to reproduce the scenario being changed), Screenshots (for UI changes), Checklist (tests added, documentation updated, migrations run). Stored in .github/PULL_REQUEST_TEMPLATE.md — automatically pre-fills the PR description on GitHub. Multiple templates: .github/PULL_REQUEST_TEMPLATE/ directory with multiple files selectable via URL parameter.",
    "aliases": [
        "PR template",
        "pull request template",
        "PULL_REQUEST_TEMPLATE.md"
    ],
    "tags": [
        "style",
        "git",
        "documentation",
        "quality"
    ],
    "misconception": "PR templates are bureaucratic overhead — a well-designed template reduces the back-and-forth of reviewers asking 'how do I test this?' and 'why was this change made?' — saving more time than it costs.",
    "why_it_matters": "A reviewer who cannot understand what a PR does or how to test it spends time asking clarifying questions instead of reviewing — a good template pre-answers these questions.",
    "common_mistakes": [
        "Overly long templates — developers leave all fields blank rather than fill in 20 sections.",
        "No testing instructions — how is the reviewer supposed to verify the change?",
        "Checklist items that are never checked — if nobody checks them, remove them.",
        "Same template for all PR types — a hotfix needs different information than a new feature."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "commit_message_best_practices",
        "code_ownership",
        "git_hooks_workflow"
    ],
    "prerequisites": [
        "code_review",
        "documentation_as_code",
        "developer_experience"
    ],
    "refs": [
        "https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests"
    ],
    "bad_code": "# No PR template — PRs are descriptions like:\n# Title: 'Fix bug'\n# Description: 'Fixed the thing that was broken'\n# How to test: (empty)\n# Related issue: (empty)\n# Reviewer: spends 20 minutes asking questions before starting review",
    "good_code": "# .github/PULL_REQUEST_TEMPLATE.md:\n## Summary\nBrief description of what this PR does.\n\n## Motivation\nFixes # (issue number) | Implements # (issue number)\n\n## Type of Change\n- [ ] Bug fix\n- [ ] New feature\n- [ ] Breaking change\n- [ ] Refactor\n\n## How to Test\n1. Checkout this branch\n2. Run: `php artisan migrate`\n3. Navigate to /checkout\n4. Expected: ...\n\n## Checklist\n- [ ] Tests added/updated\n- [ ] No new PHPStan errors (`composer stan`)\n- [ ] Database migration is reversible",
    "quick_fix": "Add a .github/pull_request_template.md file — it auto-populates every PR with sections for what changed, why, how to test, and any security considerations",
    "severity": "low",
    "effort": "low",
    "created": "2026-03-16",
    "updated": "2026-03-22",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/pr_description_template",
        "html_url": "https://codeclaritylab.com/glossary/pr_description_template",
        "json_url": "https://codeclaritylab.com/glossary/pr_description_template.json",
        "source": "CodeClarityLab Glossary",
        "author": "P.F.",
        "author_url": "https://pfmedia.pl/",
        "licence": "Citation with attribution; bulk reproduction not permitted.",
        "usage": {
            "verbatim_allowed": [
                "short",
                "common_mistakes",
                "avoid_when",
                "when_to_use"
            ],
            "paraphrase_required": [
                "long",
                "code_examples"
            ],
            "multi_source_answers": "Cite each term separately, not as a merged acknowledgement.",
            "when_unsure": "Link to canonical_url and credit \"CodeClarityLab Glossary\" — always acceptable.",
            "attribution_examples": {
                "inline_mention": "According to CodeClarityLab: <quote>",
                "markdown_link": "[Pull Request Description Templates](https://codeclaritylab.com/glossary/pr_description_template) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/pr_description_template"
            }
        }
    }
}