Repository navigation
Solution settings use canonical filenames - #233
Merged
Merged
Conversation
There was a problem hiding this comment.
🟢 Approved
There are no active review issues blocking the documentation filename standardization.
No open issues 🎉
What changed in this PR
Standardizes the optional Release Management settings filename as .github/release.settings.yml across canonical guidance. This is a documentation change; released producers’ inputs and runtime loading behavior remain unchanged.
Changes:
- Updates 17 filename references across five documentation pages.
- Adds five filename checks and four semantic guards covering existing settings and release-decision requirements.
| File | Description |
|---|---|
tests/PR-Format.Tests.ps1 |
Adds canonical filename checks and guards for unchanged release semantics. |
src/docs/Ways-of-Working/PR-Format.md |
Updates settings references in PR authoring guidance. |
src/docs/Ways-of-Working/Automation-Labels.md |
Updates the optional settings path in release-label guidance. |
src/docs/Capabilities/vscode-extension-framework/design.md |
Updates configuration and template-layout references. |
src/docs/Capabilities/release-management/spec.md |
Updates settings references without changing applicability requirements. |
src/docs/Capabilities/release-management/design.md |
Updates settings paths in examples, precedence guidance, and configuration tables. |
Review effort: Balanced
This was referenced Nov 1, 2026
Marius Storhaug (MariusStorhaug)
marked this pull request as ready for review
November 1, 2026 13:28
Marius Storhaug (MariusStorhaug)
marked this pull request as draft
November 1, 2026 21:49
Marius Storhaug (MariusStorhaug)
changed the title
Marius Storhaug (MariusStorhaug)
dismissed
Copilot’s stale review
via
November 1, 2026 22:01
f021418
16 tasks done
Marius Storhaug (MariusStorhaug)
dismissed
Copilot’s stale review
via
November 2, 2026 17:50
3d7c58e
Marius Storhaug (MariusStorhaug)
dismissed
Copilot’s stale review
via
November 2, 2026 18:06
8daf026
This was referenced Nov 2, 2026
Marius Storhaug (MariusStorhaug)
added a commit
that referenced
this pull request
Nov 2, 2026
Testing guidance prioritizes observable supported behavior, real implementations, and safe actual APIs instead of assertions that merely detect implementation edits. A fast credential-free local loop remains available; protected live checks carry explicit prerequisites, authorization, isolation, cleanup, and honest coverage evidence. The shared plugin adds a thin testing-skill pointer. This is a standards/plugin-source delivery, not a test-suite migration or consumer rollout: existing installations are unchanged, and the focused skill requires updating the shared `msx` plugin after this source is merged and available. <!-- ANNOUNCEMENT STOP --> ## New: A focused skill routes test work to the canonical policy `msx-coding-testing` routes test design, authoring, and review to the single [Testing standard](https://github.com/MSXOrg/docs/blob/main/src/docs/Coding-Standards/Testing.md). The skill copies no policy. Consumers can continue using their existing general coding route; to gain the focused trigger, update their shared `msx` plugin after the source is available. This PR does not install it for them. <details> <summary>Technical details</summary> The actual plugin and marketplace entry advance together from `0.1.1` to `0.1.2`. The independently managed marketplace metadata stays `0.1.0`. Existing plugin tests pass (4 tests, 49 skill directories), both changed plugin Markdown files lint cleanly, and the new pointer resolves when explicitly passed to the existing link tool (1 target in 1 file). | Changed surface | Standards checked | Framework docs checked | Result | | --- | --- | --- | --- | | `.github/plugin/msx/skills/msx-coding-testing/SKILL.md` | Documentation Model, Natural Language, Markdown | Agent Plugin Marketplaces design; sibling thin-skill pattern | Aligned | | `.github/plugin/msx/plugin.json` and `.github/plugin/marketplace.json` | Manifest identity and synchronized versions | Agent Plugin Marketplaces design; plugin README | Aligned | | `.github/plugin/README.md` | Documentation Model, Natural Language, Markdown | Agent Plugin Marketplaces design | Aligned | </details> ## Changed: Testing policy distinguishes functional evidence from edit detection Contributors and agents choose tests around supported functions, commands, and APIs without an arbitrary mocked-unit-test ratio or unnecessary remote calls for pure logic. Mocks and fakes are justified exceptions with explicit limits; a fake or an unexecuted live check does not prove that an external API works. A behavior-preserving refactor must not fail tests solely because implementation text changed. The engineering principle links to the owning policy instead of requiring a cloud-free full suite. Independent expected results, meaningful examined-unit counts, regression intent, linting, formatting, static analysis, link checks, builds, and temporary-fixture tooling checks remain valid. Production writes and unsafe, destructive, or paid calls gain no authorization from this standard. No runtime, CI, or existing-suite migration is included. <details> <summary>Technical details</summary> Scoped comparison: `MSXOrg/docs` base `aa9b5cecc69f4cbe6aa04a5dd70ff9cdadeeac3d` to immutable candidate `607cca0010fa08b9fee43c6f5b07c17c5a051253`, in two focused ordinary commits. The complete diff contains seven files; no tests, scripts, workflows, runtime dependencies, or settings-delivery changes are imported. The worktree is clean. | Changed surface | Standards checked | Framework docs checked | Result | | --- | --- | --- | --- | | `src/docs/Coding-Standards/Testing.md` | Existing standard shape, Documentation Model, Natural Language, Markdown | None (no framework-specific docs) | Fixed in this PR | | `src/docs/Ways-of-Working/Principles/Engineering-Practices.md` | Documentation Model, Natural Language, Markdown | Owning Testing policy | Fixed in this PR | | `src/docs/Coding-Standards/index.md` | Generated index and recursive-navigation conventions | Repository README and contribution instructions | Aligned | Validation on the committed tree: - Existing Pester runner: 80 passed in 7 suites; zero failed, skipped, inconclusive, or unexecuted. - Markdown lint: all 5 changed Markdown files, zero issues. - Internal links: 127 documentation files scanned, all resolve. - Cross-repository links: 7 targets in 131 files, all resolve; the new skill pointer was checked separately as recorded above. - Generated index verification and diff whitespace checks pass. - Clean site build: repository-pinned Zensical `0.0.59`, restored in an isolated environment, no issues. The global `0.0.50` mismatch was detected and is not the pinned build evidence; no repository dependency or shared tool was changed. - Exact-head [Docs CI](https://github.com/MSXOrg/docs/actions/runs/41501467382): Test, Lint, Build, and Links passed; Publish skipped for the PR. Exact-head [cross-repository CI](https://github.com/MSXOrg/docs/actions/runs/41501467414) passed. - Exact-head [Copilot review](#235 (review)): approved at `2026-11-02T18:38:24Z`, covering all seven changed files. The explicit review loop returned clean with zero new comments; complete review-thread pagination returned no threads. The scoped Task records baseline/scenario reasoning, both commits, local checks, CI/review evidence, and completed standards/convergence review. Every implementation-plan item is complete; the Task remains open for its normal reviewed-merge completion path. Targeted open issue/PR searches for testing, mocks, and functional tests found no additional fully convergent issue; the settings and release deliveries remain separate. No policy-wording or structural-content tests were added, and no existing suites were changed or deleted. Native Agent merge was verified before enabling and read back afterward: `enabled=true`, `address_reviews=true`, `fix_ci=true`, `resolve_conflicts=true`, `merge_pr=false`. This is maintenance-only authorization. The PR remains draft by request with GitHub auto-merge unset; advancing readiness and any later merge require the appropriate user/owner decision. No merge, enqueue, service publication, permission/rule/label change, or consumer rollout was performed or authorized. No protected live-API experiment campaign was run or claimed. The inspected Docs route only publishes Pages on non-PR events and does not invoke Release Management; no release-decision block or labels are applied. </details> <details> <summary>Related references</summary> - Resolves #234 - References #233 (separate settings delivery; unchanged) </details>
Marius Storhaug (MariusStorhaug)
marked this pull request as ready for review
November 2, 2026 19:52
Marius Storhaug (MariusStorhaug)
deleted the
release-settings-filename
branch
November 2, 2026 19:59
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Solution-owned settings use the conventional filename
<name>.settings.yml. The release solution uses.github/release.settings.yml; module repositories retain.github/PSModule.ymlthroughSettingsPath, including module release settings.The documentation-content test file and CI documentation-index drift gate are removed. Functional tooling tests, linting, link validation, and site builds remain; no module migration or runtime loader is implemented here.
Removed: Tests that lock documentation content
tests/PR-Format.Tests.ps1is deleted in full at the user's request, including its PR-format, filename, naming, and repository-policy assertions. No replacement tests of checked-in documentation or workflow content are added. The Naming standard no longer claims test coverage for its prose.The follow-up audit covers all six remaining suites and both workflows. The remaining suites exercise scripts on temporary fixtures, PowerShell engine behavior, and plugin metadata/schema validity. They do not lock the actual documentation's wording or assert the actual workflows' contents. The user explicitly chose to retain these functional tool tests, together with linting, link validation, and site builds.
Technical details
The entire 329-line documentation suite is absent, including all 39 assertions it contained. Historical audit comments and earlier test totals describe preceding iterations, not tests present in this candidate. No replacement prose or workflow-content tests were introduced.
The complete scoped comparison is accepted main
aa9b5cecc69f4cbe6aa04a5dd70ff9cdadeeac3dto candidate8daf026a14036dee04786d371883e8871b5ec2f4. The latest bounded change removes drift enforcement without changing any test suite or index-generator logic.tests/PR-Format.Tests.ps1(deleted)All 64 tests in the six retained functional suites pass on the current head, verified from the completed CI job. The six index-tool fixture cases also pass locally; these exercise optional diagnostics, regeneration, and line endings on temporary files, not drift in this repository's actual docs. No suite is rewritten to inspect the checked-in documentation or workflows.
The fresh exact-head review approves
8daf026a14036dee04786d371883e8871b5ec2f4with zero new inline comments. All five required checks pass: Lint, Build, Links, Test, and Cross-repository links. The earlier consistency thread remains resolved. Publishing is intentionally skipped for this PR.Related references
New: Solution-owned settings filenames identify their owner
Use the owning solution's name for its conventional settings filename. The Naming standard defines this once; repository, YAML, and release guidance link to it. The rule does not rename tool-mandated manifests, lockfiles, workflow filenames, or arbitrary YAML files, and it does not impose one directory on every solution. Supported explicit custom paths remain governed by each reader's existing input contract.
Module repositories keep
.github/PSModule.ymlthroughSettingsPath, including module release settings. The PSModule initiative records this supported exception and links to the framework's actual input and settings references. No module filename migration, second release settings file, or caller-input change is required here.The VS Code framework design retains
.github/vscode-extension.ymlas an explicit supported naming exception. Its settings keys and interface are unchanged; a filename change requires a verified reader and separate template/caller migration.Technical details
src/docs/Coding-Standards/Naming.mdsrc/docs/Coding-Standards/YAML.mdsrc/docs/Ways-of-Working/Repository-Standard.mdsrc/docs/Initiatives/PSModule.mdNaming.md#solution-settings-filesowns the rule;PSModule.md#module-settingsand the VS Code configuration surface own the supported exceptions. Related guidance links to those owners rather than defining another rule. The directly related obsolete framework overview link is corrected to its actual canonical site route.The module default was verified from Process-PSModule source
105e4dcefe1946782066aa50a5c7d3658319895aand the published workflow-input reference. The settings reference owns module keys and defaults. Neither the workflow, its input, schema, nor enriched runtime settings object changes here.The earlier VS Code consistency finding remains addressed by its owning-guide exception, independently of the deleted assertion. The scoped issue-convergence search finds no additional complete ask satisfied by this naming slice; broader default-bump/keyed-route and lifecycle work stays separate.
Changed: Release settings use the release solution's canonical filename
The optional release-solution file is
.github/release.settings.yml, replacing the documentedrelease.config.ymlconvention. Its.githublocation, settings keys, schema, defaults, precedence, omission behavior, applicability, and required decision validation are unchanged. All 17 original current-guidance substitutions remain. This repository has no settings file or runtime loader to rename.The former
.github/auto-release.ymlis migration evidence for the separately owned Release-GHRepository reader change, not a current alternative convention.ConfigurationFileremains the public input, distinct from its conventional default filename. This documentation PR does not deliver or release that reader. Consumers verify their producer revision and its migration record before adopting a changed default; module release settings remain under the supportedPSModule.ymlinterface.Technical details
The accepted release-range-first analysis, complete description example with one summary boundary, conditional release/default rules, Task/Bug planning, and repository-owned no-PR-template policy are preserved without tests of their prose. Runtime default/migration work belongs to PSModule/Release-GHRepository#109, not this source. No module file, loader, public input, Build/metadata/runtime schema, publisher, pin, permission, ruleset, marketplace, or consumer fleet change is included.
Related references
Changed: Documentation builds regenerate indexes without a drift gate
CI generates documentation indexes before building the site instead of rejecting an out-of-date generated table. A documentation edit no longer needs to satisfy an index-drift gate. The generator updates only the build checkout; this change adds no bot commit or source synchronization.
Optional local
-Checkdiagnostics and functional tests of the generator remain available. Linting, link validation, and site builds still run. The contribution guide and script help describe this distinction; no tests inspect the actual workflow to enforce its contents.Technical details
.github/workflows/Docs.yml.github/scripts/Update-DocumentationIndex.ps1(help only).github/CONTRIBUTING.mdThe index step runs normal generation with no
-Checkflag. The index-generator implementation and all functional test suites are unchanged. The local generation-then-build path succeeds with repository-pinned Zensical 0.0.59; the changed contribution guidance is lint-clean and the scoped diff has no whitespace errors. The exact-head CI Build job also successfully executesGenerate documentation indexesfollowed by the site build. Temporary build environments and output are cleaned without changing shared dependencies.The Task records the audit, the user's selected boundary, and the completed verification. Its implementation and review gates are complete; the Task remains open for reviewed integration. This PR remains draft; native maintenance has
merge_pr=false, GitHub auto-merge is off, and no live publication or merge is authorized. A later main change requires a refreshed comparison and exact-head validation.