PR templates

The repo ships four pull-request templates under .github/. The default fires automatically when you open a PR; the three specialty templates require a URL query parameter to apply.

The four templates

Template	File	Auto-applied?	When to use
Default	`.github/PULL_REQUEST_TEMPLATE.md`	Yes (if no `?template=` param)	Generic work that doesn’t fit one of the three below
Feature	`.github/PULL_REQUEST_TEMPLATE/feature.md`	No — `?template=feature.md`	New functionality, new endpoint, new UI surface
Bug fix	`.github/PULL_REQUEST_TEMPLATE/bugfix.md`	No — `?template=bugfix.md`	Fixing existing broken behaviour
Hotfix	`.github/PULL_REQUEST_TEMPLATE/hotfix.md`	No — `?template=hotfix.md`	Critical production incident — fast path

GitHub’s convention: a single PULL_REQUEST_TEMPLATE.md is the default; a PULL_REQUEST_TEMPLATE/ directory holds named alternatives that you opt into via the URL.

Picking a specialty template — the awkward truth

GitHub does not show a template picker when you open a pull request. The dropdown UI you may remember from other GitHub repos only exists for issues. When you click Compare & pull request, GitHub goes straight to the default template, every time, no matter what’s in .github/PULL_REQUEST_TEMPLATE/.

There are two ways to actually use one of the specialty templates:

Option A: edit the URL before opening the PR

When you click Compare & pull request, you land on a URL like:


https://github.com/E-DigitalGroup/tunnelflight/compare/main...your-branch?expand=1

Before the form is submitted, edit the URL bar and append &template=<name>.md:


https://github.com/E-DigitalGroup/tunnelflight/compare/main...your-branch?expand=1&template=feature.md

The body field now pre-fills with the specialty template. This is the only “supported” way per GitHub’s own docs.

Option B (more reliable): copy-paste

Just open the relevant template file in another tab, copy the body, and paste it over the default. Less elegant but more reliable (especially if you forget the URL trick).

Why is it like this?

GitHub never built a PR-side template picker, and the team configured both a default file and a directory of alternatives. The default wins silently. Removing the default PULL_REQUEST_TEMPLATE.md wouldn’t help — GitHub would just not pre-fill any template, and PR authors would type into an empty body. Pick-via-URL is the only ergonomic answer until GitHub ships a chooser.

What each template prompts for

Default

A general-purpose checklist:

Summary — one paragraph
Type of Change — checkbox set (bug fix / new feature / breaking change / docs update / refactor / perf / other)
Related Issues — Closes #(issue number)
What Changed? — bullets
How to Test? — steps + edge cases
Screenshots (if UI)
Checklist — self-review reminders

Good fit when you can’t clearly say “this is a feature” or “this is a bug fix” — e.g. mixed work, refactors, documentation, or infrastructure.

Feature (`feature.md`)

Heavier emphasis on what’s new, architecture decisions, and how to verify the new capability end-to-end. Sections:

What’s New? — checkbox list (new endpoints / UI / config / etc.)
Implementation Details — architecture changes, dependencies, DB migrations, breaking changes
How to Test the Feature? — manual steps + happy/edge paths
Documentation — call out that /business-logic/ pages need updates (this is where the docs-update flag tends to fire)

Use this for anything that adds capability the platform didn’t have.

Bug fix (`bugfix.md`)

Front-loads root cause analysis:

Bug Description — symptom, error messages, affected users
Root Cause — what actually caused it
The Fix — what changed
Reproduction — pre-fix steps to reproduce, post-fix verification

Use this when you can name a specific broken behaviour that existed before and works after.

Hotfix (`hotfix.md`)

Designed for production incidents — fast-path review, signed off quickly:

Urgency Level — Critical / High / Medium
Critical Issue Description — what broke, when, related deploy
Immediate Impact — number of users, business impact
Rollback Plan — what to do if the fix itself misbehaves

Use sparingly — most fixes should go through the standard bugfix template. Hotfix is for now, not soon.

House style

A few patterns the team converges on regardless of template:

Fill it in. Empty or template-default PR bodies are the most common review-thread snag. PR #584 has been open six days with the template never filled in — don’t be that PR.
Specifics over generics. “Updated the user model” → “Added a lastLoginAt column to users plus a Knex migration; backfilled null values to created_at.”
Link the related issue. Closes #NNN actually closes it on merge. Refs #NNN cross-links without closing.
Test plan as a checkbox list. Reviewers tick off as they verify.