Add SDK header patch system for shift-left metadata annotations#2248
Open
jevansaks wants to merge 3 commits into
Open
Add SDK header patch system for shift-left metadata annotations#2248jevansaks wants to merge 3 commits into
jevansaks wants to merge 3 commits into
Conversation
Introduces a patch system that modifies SDK headers during ingestion (UpdateSDK.ps1 / RecompileIdlFilesForScraping.ps1) to add metadata annotations until the official SDK ships these changes. Patches are unified diffs in generation/WinSDK/patches/, organized by phase: - pre-midl/ : Applied before MIDL recompilation (IDL files, etc.) - post-midl/ : Applied after MIDL and header restores (.h files) Includes two proof-of-concept patches: - Uxtheme.h (post-midl): Adds conditional SET_THEME_APP_PROPERTIES_FLAGS enum under #ifdef _WIN32METADATA_ with typed function signatures - amstream.idl (pre-midl): Adds cpp_quote metadata marker that flows through MIDL into the generated amstream.h Both patches validated via full SDK update (10.0.26100.7705). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
jevansaks
force-pushed
the
user/jevansa/sdk-header-patches
branch
from
f0d152f to
a942a45
Compare
Supports multiple independent patches per header file, each for a single logical change. Patches are applied in sorted filename order. Example: Uxtheme.h.set-theme-app-properties-enum.patch Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The patch system (ApplySDKPatches.ps1, hooks in RecompileIdlFilesForScraping.ps1, docs/sdk_patches.md) is ready for use. POC patches removed to avoid winmd baseline changes — real patches will be added as shift-left work proceeds. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
| # the correct baseline. Edit the file, re-run `git diff`, and overwrite the patch file. | ||
| # | ||
| # Usage: | ||
| # . .\ApplySDKPatches.ps1 -Phase pre-midl # Apply pre-MIDL patches (IDL files, etc.) |
Contributor
There was a problem hiding this comment.
Nit:
Suggested change
| # . .\ApplySDKPatches.ps1 -Phase pre-midl # Apply pre-MIDL patches (IDL files, etc.) | |
| # & .\ApplySDKPatches.ps1 -Phase pre-midl # Apply pre-MIDL patches (IDL files, etc.) |
vineeththomasalex
approved these changes
May 27, 2026
There was a problem hiding this comment.
Pull request overview
Introduces a phase-based “SDK header patch” mechanism in the ingestion pipeline so the repo can apply unified-diff patches to copied Windows SDK headers/IDL during UpdateSDK.ps1 / RecompileIdlFilesForScraping.ps1, enabling shift-left metadata annotations while waiting for upstream SDK changes.
Changes:
- Add
scripts/ApplySDKPatches.ps1to apply*.patchfiles fromgeneration/WinSDK/patches/<phase>/usinggit apply. - Hook patch application into
scripts/RecompileIdlFilesForScraping.ps1in two phases:pre-midl(before MIDL recompilation) andpost-midl(after restores). - Add documentation for authoring/updating/removing patches (
docs/sdk_patches.md) and create patch phase directories.
Reviewed changes
Copilot reviewed 3 out of 5 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| scripts/RecompileIdlFilesForScraping.ps1 | Invokes patch application before MIDL (pre-midl) and after header restores (post-midl). |
| scripts/ApplySDKPatches.ps1 | New helper script that discovers and applies patch files per phase using git apply. |
| generation/WinSDK/patches/pre-midl/.gitkeep | Ensures the pre-midl patch directory exists in the repo. |
| generation/WinSDK/patches/post-midl/.gitkeep | Ensures the post-midl patch directory exists in the repo. |
| docs/sdk_patches.md | Documents the patch phases and recommended workflow for generating and maintaining patch files. |
Comment on lines
+39
to
+41
| . "$PSScriptRoot\CommonUtils.ps1" | ||
|
|
||
| $patchDir = Join-Path $windowsWin32ProjectRoot "patches\$Phase" |
Comment on lines
+70
to
+74
| ## Examples | ||
|
|
||
| **Header patch** (`post-midl/Uxtheme.h.set-theme-app-properties-enum.patch`): Would add a conditional `SET_THEME_APP_PROPERTIES_FLAGS` enum under `#ifdef _WIN32METADATA_` and update function signatures. | ||
|
|
||
| **IDL patch** (`pre-midl/myfile.idl.my-reason.patch`): Would add a `cpp_quote` block to an IDL file. MIDL compiles it and the change appears in the generated `.h`. |
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.
SDK Header Patch System
Adds a mechanism to patch SDK headers during ingestion (
UpdateSDK.ps1) so we can add metadata annotations (conditional enums, SAL attributes, etc.) while waiting for the official SDK to ship these changes.How it works
Patches are unified diffs in
generation/WinSDK/patches/, organized by phase:pre-midl/— Applied after SDK copy, before MIDL recompilation. IDL changes flow through MIDL into generated.hfiles.post-midl/— Applied after MIDL and header restores. For direct.hpatches.If a patch fails to apply during SDK update, the script errors out — signaling the SDK changed and the patch needs regeneration.
Proof-of-concept patches
Uxtheme.h(post-midl): Adds conditionalSET_THEME_APP_PROPERTIES_FLAGSenum under#ifdef _WIN32METADATA_with typed function signatures. Complements Proposal: Replace enums.json with conditional C++ enum declarations #2247.amstream.idl(pre-midl): Addscpp_quotemetadata marker that flows through MIDL compilation into the generatedamstream.h.Both validated via full SDK update with version 10.0.26100.7705.
Files changed
scripts/ApplySDKPatches.ps1scripts/RecompileIdlFilesForScraping.ps1generation/WinSDK/patches/post-midl/Uxtheme.h.patchgeneration/WinSDK/patches/pre-midl/amstream.idl.patchdocs/sdk_patches.mdSee
docs/sdk_patches.mdfor patch authoring workflow.