[Marius Storhaug (MariusStorhaug)]

Contributors now have one audience-first pull request format across the MSX documentation set. Titles state one reader-facing result, descriptions use ordered change sections and scoped evidence, and release decisions appear only on routes that invoke Release Management. The complete copy-ready template now authors release notes that are sufficient upgrade communication and history.

Consumers read the applicable release records after their actual baseline through a chosen target and compose the required actions. Resource docs describe supported target-state behavior and usage. Authors adopt the updated canonical template; this documentation-only change requires no runtime or consumer-configuration migration.

Changed: Pull request authoring guidance

PR authors identify readers, inspect the complete change, keep claims evidence-based, select relevant news, and group related results before writing. The format uses the approved announcement boundary, ordered change classifiers, and section-scoped technical details and references.

The complete template includes every classifier in the required order, one scoped technical-details and references pair for each result, standards and framework alignment fields, applicable release evidence, and the conditional release-decision block. Its instructions cover reader-facing, internal-only, release-managed, and unmanaged pull requests without leaving empty sections.

Workflow, readiness, repository, dependency, fleet, and release-management pages defer title and description structure to PR Format while retaining their own implementation rules. The repository contribution guide explains the inherited organization template, points to the canonical MSX standard, and links directly to the complete description template.

Technical details

The canonical src/docs/Ways-of-Working/PR-Format.md path, Zensical navigation entry, and thin plugin pointer remain unchanged. This repository has no Release Management workflow invocation, so this pull request carries no release-decision block or release:* label.

Changed surface	Standards checked	Framework docs checked	Result
PR format and complete description template	PR Format, Markdown, and Documentation Model	None (no framework-specific docs)	Aligned
Contribution guide and inherited-template link	Contribution Workflow and PR Format	None (no framework-specific docs)	Aligned
Contribution, review, readiness, branching, fleet, and repository workflow pages	Ways of Working	None (no framework-specific docs)	Aligned
Dependency, automation, and natural-language dependants	Owning capability and coding standards	None (no framework-specific docs)	Aligned

Current local validation passes: generated documentation indexes; 127-file local-link and anchor scan; 7 cross-repository links across 131 files; all 64 Pester tests in 6 suites; clean Zensical build with the pinned requirements.txt toolchain on Python 3.13; and git diff --check.

The template-contract check passes: exactly one announcement marker, five ordered classifiers, identical action/example instructions across all five, scoped technical-details and reference blocks, conditional release fields, and publisher-resolved release coordinates. Managed, unmanaged, and internal-only authoring routes retain their existing conditional structure.

Related references

• References MSXOrg/.github#8

Changed: Release notes own consumer upgrade instructions

Release notes explain what changed, why, affected supported uses, compatibility, and exact adoption actions with applicable prerequisites, ordering, and verification, or an explicit no-action result with its compatibility basis. Authors cover the complete delivered source range since the identified baseline, including earlier merged or skipped changes and every bundled consumer delta. Necessary old-to-new examples and comparisons stay in the note's prose and examples; scoped technical details support the instructions.

Reading every applicable record in release order is sufficient to compose the actions through the target. An intermediate installation or run is required only when a note explicitly requires it. Later instructions explain superseded actions while retaining required intermediate operations. Missing required instructions are evidence gaps to resolve in the notes; PRs and diffs provide optional depth.

Resource READMEs, specs, designs, implementation docs, guides, and references remain user-focused descriptions of supported target-state behavior and usage. Release-specific transitions and history stay in release records. ADRs and research retain their historical purposes. This change defines the documentation and authoring contract without implementing a replay engine, adding a history store, or backfilling published releases. Publication still resolves actual version, tag, source, and artifact coordinates.

Technical details

Changed surface	Standards checked	Framework docs checked	Result
PR-Format.md analysis, examples, all five template groups, and readiness	PR Format, Markdown, and Documentation Model	Release Management release-evidence requirements	Aligned
Release Management specification and design	Specification/design separation and Markdown	Release Management release evidence and source binding	Aligned
Documentation-Model.md ownership and evergreen guidance	Documentation Model and Markdown	Release Management release-note ownership	Aligned

Targeted Markdown lint passes for all four edited contract pages with zero issues. Link/anchor checks and the clean site build include their new cross-references. Commit 40346e7 adds this focused alignment while preserving the earlier PR work.

Illustrative replay review: These are hypothetical already-published records used to review the authoring contract, not proposed release versions for this PR. The consumer starts at R0 with output-dir: ./out and targets R3.

Record and identified baseline	Instructions contained in that release note
R1, after R0	Output configuration is standardized by renaming output-dir to output-path. Workflows using the old key must rename it and retain its value; the old key is rejected from R1. After selecting the desired release reference, verify a workflow run writes artifacts to the configured path. No intermediate installation or run is required for a later target.
R2, after R1	A logging fix preserves the supported input contract and artifact location. No workflow, configuration, or data action is required beyond selecting the desired release reference; the existing output check remains applicable. No intermediate operation is required.
R3, after R2	Artifact settings are named consistently by replacing output-path with artifact-path; both earlier keys are rejected. Rename whichever earlier key is present to artifact-path, retaining ./out. For an R3 target this supersedes the R1 key edit. Select R3, run the workflow, and verify artifacts under ./out. Installing or running R1/R2 is unnecessary.

Reading R1, R2, and R3 lets the R0 consumer make one final edit to artifact-path: ./out, select R3, and verify its workflow output. R2 contributes an explicit, justified no-action outcome. Evergreen R3 usage docs show only the supported artifact-path input; the transition is fully available in the notes.

Required-intermediate variant: If R2 explicitly says that a schema-1 cache requires backing up ./cache, installing R2, running example-tool convert-cache ./cache --to-schema 2, and confirming example-tool inspect-cache ./cache reports schema 2 before installing R3, that sequence remains required. Superseding the input-key edit does not remove the required conversion.

Gap and bundled-range review: Omitting a required key mapping, compatibility condition, or conversion instruction fails this contract; it is neither implicit no-action nor a direction to reconstruct instructions from PRs or diffs. A bundled record must retain every applicable instruction from its complete source range, including earlier merged or skipped work, rather than describe only the latest commit.

The walkthrough reviews documentation behavior; it does not execute consumer upgrades or validate an implementation of a release publisher. The overlapping consumer-upgrade and release-lifecycle drafts remain separate and unchanged.

Related references

• References MSXOrg/docs#205 for overlapping consumer-upgrade documentation.
• References MSXOrg/docs#208 for overlapping release-lifecycle documentation.