Skip to content

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 requiresTemplate currently has
1A --- horizontal rule separating the user-facing description from the ending blocksNo 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>
4Technical details carries implementation-plan progress, the standards and framework alignment table, and the issue convergence sweepGuidance comment mentions only "files touched, design decisions, migration notes"
5Both 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.md as 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.md from MSXOrg/docs on GitHub rather than a local clone, which may be stale
  • Rewrite the ending of .github/pull_request_template.md as the --- rule, the Technical details details block, and the Relevant 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

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions