PR template doesn't exist (docs create a circular reference)

Resolved 💬 2 comments Opened Apr 28, 2026 by HaleTom Closed Apr 28, 2026

What is the type of issue?

  • [x] Documentation is confusing
  • [x] Documentation is missing

What is the issue?

Issue #19856 was closed as completed, but the fix was insufficient. The circular reference between contributing.md and the PR template still exists, and the "What? Why? How?" structure that contributing.md tells contributors to use is still absent from the template.

What was changed: The PR template wording was updated slightly (now says "replace this text with a detailed and high quality description" and "Include a link to a bug report or enhancement request").

What was not changed — the three remaining problems:

  1. The circular reference is unbroken. The PR template at .github/pull_request_template.md says:

> _"External code contributions are by invitation only. Please read the dedicated 'Contributing' markdown file for details"_

Then docs/contributing.md says:

> _"Fill in the PR template (or include similar information) - What? Why? How?"_

An invited contributor following these instructions lands in a loop: _"read contributing.md"_ → _"fill in the PR template"_ → _"read contributing.md"_ → … and never finds the "What? Why? How?" sections.

  1. contributing.md still doesn't link to the template. The "Opening a pull request" section says "Fill in the PR template" but does not link to — or even name — .github/pull_request_template.md. A contributor reading contributing.md cannot navigate to the template from the document that tells them to use it.
  1. The "What? Why? How?" structure still doesn't exist in the template. The template contains no headings, no sections, no "What?", "Why?", or "How?" prompts. It asks contributors to "replace this text with a detailed and high quality description" — a freeform request, not a structured one. Yet contributing.md promises contributors they will find a specific "What? Why? How?" structure to fill in.

Where did you find it?

View original on GitHub ↗

This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗