Pull Request Templates

Pull Request (PR) templates help standardize contributions by providing a checklist and structure for submitters to follow. This ensures important information is included and improves review efficiency.

PR Template Index

Because GitHub does not provide a native UI selector for multiple templates without query parameters, this index helps you choose the correct specialized template.

Usage

1. Pick the appropriate template below.
2. Click its link to open a pre-filled PR creation page (replace REPO_OWNER and REPO_NAME if not already substituted by GitHub).
3. If you already opened a PR, you can copy/paste the content manually.

Note: Links rely on the template= query parameter which only works when creating a NEW pull request (not editing an existing one).

FAQ

Q: I already opened the PR; can I swap templates?
A: Manually copy the contents from the target template file and edit the PR description.

Q: Why not keep a single giant template?
A: Focus improves quality; reviewers quickly see what matters for that change type.

Q: What if my change spans multiple categories?
A: Use the dominant type (usually feature or patch) and add an "Additional Scope" subsection.

Q: Do I still need semantic titles?
A: Yes; enforced by commit/PR lint workflow.

Instructions

1. Create folder .github/PULL_REQUEST_TEMPLATE/ in your repository if it doesn't exist.
2. Add the desired markdown files from below into that folder:
3. docs.md - Documentation changes
4. feature.md - New features
5. patch.md - Bug fixes
6. refactor.md - Code restructuring without behavior change
7. test.md - New or updated tests

Documentation PR Template

## docs: <short imperative summary>
<!-- Replace above line with semantic title. To auto-load: &template=docs.md in compare URL. -->

## Scope of Documentation Change
What area is affected? (README, design doc, inline comments, diagrams, lab instructions.)

## Motivation
Why was this update needed?

## Content Summary
List major additions/updates:
- 
- 

## Verification
Rendered preview checked?
- [ ] Markdown renders correctly
- [ ] Links verified
- [ ] Diagrams / images display

## Related Code (If Any)
Reference any PRs whose behavior this documents.

## Related Issues
Links / references.

## Checklist
- [ ] Semantic title
- [ ] Linked Issue (or rationale documented)
- [ ] Accurate & current
- [ ] No typos / grammar scan
- [ ] Removed stale/outdated sections

New Feature PR Template

## feat: <short imperative summary>
<!-- Replace above line with semantic title. To auto-load this template when creating a PR: add &template=feature.md to the compare URL. -->

## Summary
What feature does this add? Why is it needed?

## Design Overview
- Core idea:
- Data structures / algorithms:
- Interfaces added/changed:

## Implementation Notes
Key decisions, trade-offs, alternative approaches rejected.

## Testing
Evidence:
- Added tests: <!-- list files -->
- Manual verification steps:

## Performance (If Applicable)
Baseline vs new (qualitative or measured):

## Documentation
- [ ] README updated
- [ ] Design doc added/updated
- [ ] Code comments added

## Related Issues
Closes issue number <!-- e.g., Closes issue 12 -->

## Checklist
- [ ] Semantic title
- [ ] Linked Issue
- [ ] Tests added
- [ ] Docs updated
- [ ] No style/lint violations
- [ ] No dead/debug code

Bugfix PR Template

## fix: <short imperative summary>
<!-- Replace above line with semantic title. To auto-load: &template=patch.md in compare URL. -->

## Problem
Describe the defect / incorrect behavior.

## Root Cause Analysis
Brief explanation of underlying issue.

## Fix Description
What changed and why it resolves the issue.

## Related Issues
Closes issue number <!-- e.g., Closes issue 34 -->

## Checklist
- [ ] Semantic title
- [ ] Linked Issue
- [ ] Verified no new warnings
- [ ] Docs updated (if behavior visible)
- [ ] Root cause described

Refactor PR Template

## refactor: <short imperative summary>
<!-- Replace above line with semantic title. To auto-load: &template=refactor.md in compare URL. -->

## Intent
Why refactor? (clarity, reuse, testability, performance groundwork, etc.)

## Scope
Modules / files affected. Confirm no functional behavior intended to change.

## Before vs After
Describe structural differences (e.g., extracted functions, reduced duplication).

## Testing Strategy
- Existing tests pass? (list command)

## Verification of No Behavior Change
Evidence (logs, output equality, diff tools, benchmarks if relevant):

## Follow-Ups (If Any)
Future cleanups unlocked by this change.

## Related Issues
Links / references.

## Checklist
- [ ] Semantic title
- [ ] Linked Issue (or rationale documented)
- [ ] No functional change (stated clearly)
- [ ] Tests pass
- [ ] Docs / comments updated
- [ ] Dead code removed

New or Updated Test PR Template

Choosing the Right Template

Situation	Template	Notes
Adding a new capability	Feature	If schema/contracts change, mention ADR or update docs
Fixing incorrect behavior	Bugfix	Include root cause section clearly
Improving structure only	Refactor	Must state “no behavior change intended”
Updating docs only	Documentation	Link to code PR if paired
Adding tests separate from implementation	Test	Reference implementation PR

Cross-reference: See Deliverables > 4.5 PR Quality Checklist for mandatory review gates.

## test: <short imperative summary>
<!-- Replace above line with semantic title. To auto-load: &template=test.md in compare URL. -->

## Purpose
What behavior or regression is this test ensuring?

## Test Additions / Changes
- New test files:
- Modified tests:
- Removed tests (if any):

## Coverage / Scenarios
List critical paths / edge cases exercised:
- Edge case 1
- Edge case 2
- Edge case 3

## Related Implementation PR (If Separate)
Link if tests are split from feature/fix work.

## Checklist
- [ ] Semantic title
- [ ] Linked Issue
- [ ] Tests are deterministic
- [ ] Edge cases covered
- [ ] No flaky sleeps / timing assumptions
- [ ] No redundant overlapping tests