Skip to content

Align the pull request template with the ending block structure PR Format requires #40

Open

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

  1. MariusStorhaug commented on Aug 2, 2026

    @MariusStorhaug
    MemberAuthor

    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.md carry the pre-change structure. Zero conform. The sweep matched on the Relevant issues summary text:

    $repos = gh repo list PSModule --limit 100 --json name --jq '.[].name'
    foreach ($r in $repos) {
        $t = gh api "repos/PSModule/$r/contents/.github/pull_request_template.md" -H "Accept: application/vnd.github.raw" 2>$null
        if ($t -and ($t -join "`n") -notmatch 'Relevant issues') { $r }
    }

    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:

    • The blast radius is the whole organization, not this repository. Fixing .github/pull_request_template.md here 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.
    • The underlying gap is systemic. A normative structure changed in the standards repository with no step that updated the artifacts embodying it. Raised separately as MSXOrg/docs#143, since the fix there is a process change rather than a template edit.

    One detail worth carrying into the fix: the drift is not cosmetic. ## Technical Details renders 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.

  2. MariusStorhaug commented on Oct 31, 2026

    @MariusStorhaug
    MemberAuthor

    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.

  3. MariusStorhaug commented on Oct 31, 2026

    @MariusStorhaug
    MemberAuthor

    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.md outright, 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.

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