Finish the cutover to source-generated schemas and publish missing version folders
维护者通常 1 天内回复
还没有人认领这个 Issue。
评估
- 难度
- 5/5
- 预计耗时
- 一周以上
- 新手友好度
- 35/100
- Issue 类型
- 功能
- 描述清晰度
- 基本清楚
- 活跃度
- 冷清
- 技术栈
- powershell, rust
- 领域
- build-system, ci-cd, devtools
调研方向
首先阅读 schemas/src 和 schemas/build.ps1,然后检查 lib/dsc-lib 下的 DscRepoSchema 实现并运行 cargo xtask schema export。将生成的输出与现有的 schemas/ 文件夹以及 dsc/tests 中提议的 Pester 覆盖范围进行比较。完成的标准是:生成的 schema 覆盖已声明的类型和已发布的版本,避免出现偏差,并验证仓库的示例 manifest。
由索引模型根据 Issue 内容生成。
描述
Summary of the new feature / enhancement
As a configuration author or resource developer using the published DSC schemas,
I want the schemas to publish for every released version and stay in sync with the engine automatically,
So that editor validation and IntelliSense help me instead of contradicting DSC.
Currently the published schemas under schemas/ are built from hand-maintained YAML sources (schemas/src via schemas/build.ps1) that were last generated for v3.1.0, while the engine has moved on to 3.4.
The most visible symptom is that recognized $schema URIs don't resolve. The engine accepts every version through v3.2.3 as a valid $schema value, but no schema folder was ever published after v3.1.0, so a document pinned to a URI like this validates in DSC and 404s in the editor:
$schema: https://aka.ms/dsc/schemas/v3.2/bundled/config/document.json
The YAML sources have also drifted from the engine — fields, enum values, and whole subsystems added since v3.1.0 aren't represented, and in several cases the published schemas reject manifests this repository ships. Those content gaps will be filed as individual issues; this issue tracks the underlying problem that makes them inevitable.
That underlying problem is that the repository has two schema systems mid-migration. The YAML pipeline is what publishes, but every release requires manually editing schemas.config.yaml, re-running build.ps1 per version folder, and hand-updating the $schema URI enums in the sources — steps nothing enforces, which is how seven releases shipped without schemas. Meanwhile the source-based generator from #538/#1406 (DscRepoSchema + cargo xtask schema export) derives schemas directly from the engine's types — making drift structurally impossible — but is nearly complete rather than complete: it has never published anything, and no CI exercises either system.
Proposed technical implementation details (optional)
Finish the cutover to generated schemas in phases, each independently reviewable:
- Exporter correctness (#1672): fix the two silent path collisions (
AdaptedDscResourceManifest,DeleteWhatIfResult), export every type that derivesDscRepoSchema, fail on duplicate output paths, add--schema-version/--releasetargeting, and routedsc schemathrough the same machinery so the CLI and exporter agree. - Bundling and namespace parity: expand
should_bundleto match the 24 bundled schemas the YAML pipeline publishes today, and decide the disposition of each YAML-only schema (resource/stdout/*,resource/properties/*,metadata/Microsoft.DSC/*), with$refalias stubs in the floating version folders for moved paths. - Authoring parity: port the
title/description/VS Code keywords from the YAML sources onto the Rust types using the existingschema_i18n!pattern, with a comparison report gating the cutover so generated schemas don't regress the editor experience. - CI: commit
schemas/vNext, regenerate it in CI and fail on drift, and validate the repository's own example configurations and manifests against the generated schemas. - Backfill: publish the missing
v3.1.1–v3.2.3folders from each release tag's own sources so every recognized URI resolves. - Cutover: the next stable release publishes its folders via
cargo xtask schema export --release, after whichschemas/srcandschemas/build.ps1can be retired.
The CI checks (phase 4) fit naturally as a Pester test in dsc/tests, so they run in the existing ./build.ps1 -Test -PesterTestGroup dsc job as well as in a dedicated schemas workflow that invokes cargo xtask schema export first. Something like:
BeforeDiscovery {
# Every (folder_path, base_name) pair declared with #[dsc_repo_schema(...)]
$declarations = Get-ChildItem lib/dsc-lib/src -Recurse -Filter '*.rs' | ForEach-Object {
[regex]::Matches(
(Get-Content $_.FullName -Raw),
'(?s)base_name\s*=\s*"(?<base>[^"]+)"\s*,\s*folder_path\s*=\s*"(?<folder>[^"]+)"'
) | ForEach-Object {
@{ folder = $_.Groups['folder'].Value; base = $_.Groups['base'].Value }
}
}
}
Describe 'exported schemas' {
It 'exports <folder>/<base>.json' -TestCases $declarations {
Join-Path 'schemas/vNext' $folder "$base.json" | Should -Exist
}
It 'has no uncommitted drift' {
git diff --exit-code -- schemas/vNext
$LASTEXITCODE | Should -Be 0 -Because 'run `cargo xtask schema export` and commit the result'
}
}
Describe 'instance validation' {
It 'validates <name> against the generated manifest schema' -TestCases $manifests {
Test-Json -Path $path -SchemaFile 'schemas/vNext/bundled/resource/manifest.json' | Should -BeTrue
}
}
The first block also catches the "derives DscRepoSchema but was never exported" class of bug statically, and the instance validation is the regression proof for the drift issues: manifests in this repository that fail against the published v3.1.0 schemas today must pass against the generated ones.
- 主要语言
- Rust
- 星标
- 536
- 派生
- 76
- 平均合并
- 1 天 11 小时
- 30 天内合并 PR
- 15
环境准备
在浏览器里用你自己的 GitHub 账号启动这个项目的开发容器。
- 没有 Dockerfile 或 Docker Compose 文件
- 没有 Pull Request 模板
- 阅读贡献指南
从这里开始
- 先读完整个 Issue,再读项目的贡献指南。
- 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
- Fork 仓库,在一个分支上完成修改。
- 提交 Pull Request,并在描述里引用这个 Issue 编号。
PowerShell/DSC 的其他 Issue
-
Issue-Enhancement Needs Triage
难度 4/5 3-5 天 新手友好度 30/100
PowerShell/DSC#1750 · 3 条评论 ·
维护者通常 1 天内回复
-
Issue-Bug Need-Review
难度 3/5 1-2 天 新手友好度 45/100
PowerShell/DSC#1749 ·
维护者通常 1 天内回复
-
Issue-Bug Need-Review
难度 3/5 1-2 天 新手友好度 40/100
PowerShell/DSC#1748 · 2 条评论 ·
维护者通常 1 天内回复
-
"apt install dsc" will install the preview release instead of stable可能已有人在做 @SteveL-MSFT 于 1 天前认领。 未关闭Issue-Bug Need-Review
PowerShell/DSC#1746 · 1 条评论 · 已指派 1 人 ·
维护者通常 1 天内回复
-
Issue-Enhancement
难度 5/5 一周以上 新手友好度 35/100
PowerShell/DSC#1737 · 1 条评论 ·
维护者通常 1 天内回复
相似的 Issue
-
bug user-priority/P2
难度 2/5 1-3 小时 新手友好度 62/100
维护者通常 1 天内回复
-
难度 2/5 1-3 小时 新手友好度 65/100
rescript-lang/rescript#8765 ·
维护者通常 1 天内回复
-
难度 2/5 1-3 小时 新手友好度 72/100
nautechsystems/nautilus_trader#5287 ·
维护者通常 1 天内回复
-
bug
难度 2/5 1-3 小时 新手友好度 62/100
farion1231/cc-switch#8072 ·
维护者通常 1 天内回复
-
Python 3.15 support可能已有人在做 @amnesiaof 今天认领。 未关闭L: python L: python:uv
难度 2/5 1-3 小时 新手友好度 72/100
dependabot/dependabot-core#16524 · 1 条评论 ·
维护者通常 1 天内回复