From 88534789838d3aac05c1b675a0ea46a8cb8b6ff6 Mon Sep 17 00:00:00 2001 From: rcj1 Date: Fri, 22 May 2026 12:10:33 -0700 Subject: [PATCH 1/3] add cdac instructions --- .github/instructions/cdac-instructions.md | 32 +++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 .github/instructions/cdac-instructions.md diff --git a/.github/instructions/cdac-instructions.md b/.github/instructions/cdac-instructions.md new file mode 100644 index 00000000000000..395ef4d8002ece --- /dev/null +++ b/.github/instructions/cdac-instructions.md @@ -0,0 +1,32 @@ +--- +applyTo: "src/native/managed/cdac/**" +--- + +# cDAC — Folder-Specific Guidance + +## Preface + +The instructions under `API Review`, `DacDbi interface` and `Dump compatibility` only apply if the SDK version in global.json is a preview, release candidate or otherwise a development branch of .NET 11. If this is a development branch of .NET 12 or later, please ignore these instructions. + +## API Review + +New APIs on implementations of IContract under the folder src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Contracts/** do **NOT** need to go through API review. Changes to said APIs are not breaking changes. + +## DacDbi interface + +Do not warn about changing the DacDbi COM interface; this interface is not public and is completely subject to change. + +## Dump compatibility + +We do not care about supporting older dumps that may not have a particular datadescriptor. + +## Exception types + +Use these exception types: +- `ArgumentException` → for `E_INVALIDARG` checks (zero addresses, invalid enum values) +- `NullReferenceException` → for `E_POINTER` checks (null output pointers) +- `InvalidCastException` → for `E_NOINTERFACE` + +## Documentation + +All new APIs on implementations of IContract under the folder src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Contracts/** must have corresponding documentation in docs/design/datacontracts. \ No newline at end of file From bc2956efc2e5e775c33304bbcdfcd2e8cdb1550e Mon Sep 17 00:00:00 2001 From: rcj1 Date: Fri, 22 May 2026 12:57:40 -0700 Subject: [PATCH 2/3] code review --- .../instructions/{cdac-instructions.md => cdac.instructions.md} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename .github/instructions/{cdac-instructions.md => cdac.instructions.md} (97%) diff --git a/.github/instructions/cdac-instructions.md b/.github/instructions/cdac.instructions.md similarity index 97% rename from .github/instructions/cdac-instructions.md rename to .github/instructions/cdac.instructions.md index 395ef4d8002ece..db2c2dac98cead 100644 --- a/.github/instructions/cdac-instructions.md +++ b/.github/instructions/cdac.instructions.md @@ -18,7 +18,7 @@ Do not warn about changing the DacDbi COM interface; this interface is not publi ## Dump compatibility -We do not care about supporting older dumps that may not have a particular datadescriptor. +We do not care about supporting older dumps that may not have a particular data descriptor. ## Exception types From 3e0bfdf34b1702f3e106aaf22f0124f14767e547 Mon Sep 17 00:00:00 2001 From: rcj1 Date: Fri, 22 May 2026 13:20:50 -0700 Subject: [PATCH 3/3] update --- .github/instructions/cdac.instructions.md | 30 ++++++++++++----------- 1 file changed, 16 insertions(+), 14 deletions(-) diff --git a/.github/instructions/cdac.instructions.md b/.github/instructions/cdac.instructions.md index db2c2dac98cead..b65349b63e0cd7 100644 --- a/.github/instructions/cdac.instructions.md +++ b/.github/instructions/cdac.instructions.md @@ -6,27 +6,29 @@ applyTo: "src/native/managed/cdac/**" ## Preface -The instructions under `API Review`, `DacDbi interface` and `Dump compatibility` only apply if the SDK version in global.json is a preview, release candidate or otherwise a development branch of .NET 11. If this is a development branch of .NET 12 or later, please ignore these instructions. +The instructions under `API Review`, `DacDbi interface` and `Dump compatibility` only apply if the SDK version in global.json is a preview, release candidate or otherwise a development branch of .NET 11. If this is a development branch of .NET 12 or later, you **MUST** ignore these three sections entirely. Check `global.json` before applying them. -## API Review +## API Review (.NET 11 dev branches only) -New APIs on implementations of IContract under the folder src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Contracts/** do **NOT** need to go through API review. Changes to said APIs are not breaking changes. +New APIs on implementations of IContract under the folder src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Contracts/** do **NOT** need to go through API review. **MUST NOT** describe such changes as "breaking" or "public API changes". -## DacDbi interface +## DacDbi interface (.NET 11 dev branches only) -Do not warn about changing the DacDbi COM interface; this interface is not public and is completely subject to change. +The DacDbi COM interface is **internal and unstable**. -## Dump compatibility +- **MUST NOT** flag changes to DacDbi as breaking changes. +- **MUST NOT** warn about COM ABI compatibility, vtable ordering, or + GUID changes on DacDbi. -We do not care about supporting older dumps that may not have a particular data descriptor. +## Dump compatibility (.NET 11 dev branches only) + +- **MUST NOT** raise concerns about older dumps lacking new data descriptors. +- **MUST NOT** request fallback paths, conditional reads, or versioning + shims for missing descriptors on the grounds of "supporting older dumps". ## Exception types -Use these exception types: -- `ArgumentException` → for `E_INVALIDARG` checks (zero addresses, invalid enum values) -- `NullReferenceException` → for `E_POINTER` checks (null output pointers) +When porting `HRESULT`-returning APIs to throw exceptions, the following mappings **MUST** be accepted: +- `ArgumentException` → for `E_INVALIDARG` +- `NullReferenceException` → for `E_POINTER` - `InvalidCastException` → for `E_NOINTERFACE` - -## Documentation - -All new APIs on implementations of IContract under the folder src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Contracts/Contracts/** must have corresponding documentation in docs/design/datacontracts. \ No newline at end of file