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 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.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

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

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