Repository navigation
Align the pull request template with the ending block structure PR Format requires #40
Description
The repository's .github/pull_request_template.md does not produce the ending block structure that PR Format requires, so pull requests opened from it need manual restructuring to comply.
Context and request
.github/pull_request_template.md is inherited by every repository generated from this template, and it is the first thing a contributor or agent sees when opening a pull request. PR Format specifies an exact ending structure — a horizontal rule, a collapsible Technical details block, then a collapsible Relevant issues (or links) block — because those blocks are what the release-note tooling and the review gate read. The current template drifts from that in five concrete ways:
| # | PR Format requires | Template currently has |
|---|---|---|
| 1 | A --- horizontal rule separating the user-facing description from the ending blocks |
No separator |
| 2 | <details><summary>Technical details</summary> — collapsible, sentence case |
## Technical Details — a plain heading, title case, rendered inline as a body section |
| 3 | <details><summary>Relevant issues (or links)</summary> |
<details><summary>Related issues</summary> |
| 4 | Technical details carries implementation-plan progress, the standards and framework alignment table, and the issue convergence sweep | Guidance comment mentions only "files touched, design decisions, migration notes" |
| 5 | Both ending blocks are required structure | "Delete this section if there is nothing noteworthy" invites removing Technical details |
A contributor who fills in the template as written produces a non-conforming pull request; one who follows PR Format has to delete and rewrite the scaffold. Neither is the intended experience.
Acceptance criteria
- Filling in
.github/pull_request_template.mdas written produces a description whose ending structure matches the PR Format specification byte for byte in block order, wrapper elements, and summary text. - The guidance comments name implementation-plan progress, the standards and framework alignment table, and the issue convergence sweep as Technical details contents.
- The template no longer suggests deleting a required block.
- The user-facing section scaffold (
## New:,## Changed:,## Fixed:,## Breaking Changes) and the existing title and label guidance are preserved. - Comments still instruct the author to delete them and any unused section before marking the pull request ready.
Non-goals
- Changing PR Format itself. This issue moves the template toward the specification, not the other way around.
- Adding issue templates. This repository has none, and that is a separate question.
Technical decisions
Follow the specification, not another repository's copy: MSXOrg/docs has no .github/pull_request_template.md, so there is no reference implementation to converge on. src/docs/Ways-of-Working/PR-Format.md in that repository is the source of truth, and its "Required ending blocks" fenced example is the literal target.
Keep <!-- markdownlint-disable MD041 --> on line 1: The template opens with an HTML comment rather than a top-level heading, and the inline disable is what keeps it lint-clean. MSXOrg/docs sets MD041: false globally instead; the inline directive is narrower and is kept.
Scope is one file: .github/pull_request_template.md. No workflow, linter, or documentation change is implied.
Implementation plan
- Re-read
src/docs/Ways-of-Working/PR-Format.mdfromMSXOrg/docson GitHub rather than a local clone, which may be stale - Rewrite the ending of
.github/pull_request_template.mdas the---rule, theTechnical detailsdetails block, and theRelevant issues (or links)details block, in that order - Update the guidance comments to name implementation-plan progress, the alignment table, and the convergence sweep, and to stop offering deletion of a required block
- Verify the rendered template against the PR Format "Required ending blocks" example, block by block
- Verify the file still lints clean under
.github/linters/.markdown-lint.yml
Activity
MariusStorhaug commentedon Aug 2, 2026
Swept the organization to size this. Every PSModule repository is affected, and the cause is datable.
96 of 96 repositories with a
.github/pull_request_template.mdcarry the pre-change structure. Zero conform. The sweep matched on theRelevant issuessummary text:This is not neglect — it is a standard change that never propagated. The ending-block structure was introduced in MSXOrg/docs#95, commit
f3aede8, on 2026-07-25. Every template in the organization predates it, so all 96 were correct when they were written and none were updated when the standard moved.That reframes this issue in two ways:
.github/pull_request_template.mdhere is still the right root fix, because the other 95 inherit from it — but the fix only reaches them through whatever propagation this template has, and that propagation is what needs confirming as part of closing this.One detail worth carrying into the fix: the drift is not cosmetic.
## Technical Detailsrenders as a visible body section, so implementation detail lands in the middle of what PR Format defines as the release note. Every PR opened from this template puts reviewer-facing content in front of users.MariusStorhaug commentedon Oct 31, 2026
Verified the current default tree at ff935a5: the recursive tree is complete and contains no local PR template. Template-PSModule therefore relies on the PSModule organization fallback rather than inheriting a copied file from its own source tree. PSModule/.github#82, scoped by native Task PSModule/.github#81, aligns that organization-owned fallback with the complete source candidate in MSXOrg/docs#209.
This does not justify recreating the deleted local file or closing this issue solely because its old target is absent. Its acceptance criteria should be reconciled around the inherited fallback outcome and any remaining evidence of propagation to repositories that retain local copies. The historical 96-repository observation is not current rollout verification. The organization fallback PR closes only its own Task; this issue stays open, and no consumer fleet or duplicate template is introduced.
MariusStorhaug commentedon Oct 31, 2026
User-directed distribution reversal: the user selected "Remove central defaults too; use canonical PR-format guidance only" after requesting that no repository contain the PR-template file. The existing scoped PSModule/.github#82 and native Task PSModule/.github#81 are now revised to delete the central
.github/pull_request_template.mdoutright, remove automatic-fallback claims, and retain only canonical authoring links. No local or central replacement is added.This supersedes the earlier comment's inheritance-based proposed outcome; old scaffold-copy evidence is history, not current distribution authority. The no-file default already observed in Template-PSModule should not be reversed by recreating its deleted local template. This issue remains open for owner reconciliation of its old file-target acceptance criteria and any genuinely remaining repository-copy removal scope, not closure merely because the original path is absent. No consumer fleet or Feature/Bug issue-form change is performed in the central removal PR.