@samitouri / QOSAMI-WSL / commits / ff898462

Scope ABI-stability guidance to SDK-facing WSLCCompat.idl (#40906)

* Scope ABI-stability guidance to SDK-facing WSLCCompat.idl Only WSLCCompat.idl (the WSLC SDK-facing layer) and the public plugin API require a backward-compatible ABI. The other in-box COM interfaces (IWSLCSession in wslc.idl, wslservice.idl, etc.) ship in lockstep with their only clients and have their proxy/stubs regenerated each build, so appending methods is fine. Stops the review bot from flagging method additions to in-box interfaces. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Include method removal as an ABI break in stable-surface guidance Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Use 'internal, non-stable' terminology; document it in wslservice.idl Replace the confusing 'in-box' term with 'internal, non-stable' in the ABI guidance, and add a matching note to wslservice.idl (mirroring wslc.idl) so the stability boundary is documented at the source. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Ben Hillis <benhill@ntdev.microsoft.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Ben Hillis committed Jun 25, 2026 at 11:47 UTC ff898462eeec3c3a4cc8f6e5a4bd960a60f08c7d

3 files changed +6 -4

.github/copilot-instructions.md

+1 -1

@@ -140,7 +140,7 @@ When modifying service interfaces (`src/windows/service/inc/`):

140 - String params: `[in, unique] LPCWSTR` with `[string]` for marshaled strings

141 - Handle params: `[in, system_handle(sh_file)] HANDLE`

142 - User-facing errors: pass `[in, out] LXSS_ERROR_INFO* Error`

143 -- **Adding methods to an existing interface is an ABI break** — create a new versioned interface with a new IID

143 +- **ABI stability applies only to SDK-facing and public surfaces.** `WSLCCompat.idl` (the WSLC SDK-facing layer) and the public plugin API (`WslPluginApi.h`) must stay backward compatible: do not add, remove, or reorder methods on their existing interfaces, and do not change struct layouts. Introduce a new versioned interface with a new IID instead. Every other interface (`IWSLCSession` in `wslc.idl`, the interfaces in `wslservice.idl`, etc.) is internal and non-stable: rebuilt and shipped in lockstep with its only clients, so appending new methods to those is fine.

144 - Custom error codes: `WSL_E_xxx` via `MAKE_HRESULT(SEVERITY_ERROR, FACILITY_ITF, WSL_E_BASE + N)`

145

146 ### Config File (.wslconfig) Conventions

.github/copilot/review.md

+3 -3

@@ -3,9 +3,9 @@

3 When reviewing code, enforce the conventions in `.github/copilot-instructions.md`. Focus especially on these high-risk areas:

5 ### ABI Safety (Critical)

6 -- **Flag** new methods added to existing COM interfaces without a new versioned interface/IID

7 -- **Flag** changed struct layouts in IDL files

8 -- **Flag** changes to `WSLPluginHooksV1` or `WSLPluginAPIV1` structs (public API)

6 +Only the SDK-facing and public surfaces require a backward-compatible ABI. Every other COM interface (`wslc.idl`, `wslservice.idl`, etc.) is internal and non-stable: shipped in lockstep with its only clients, with the proxy/stub regenerated each build, so methods may be appended to those freely. Do **not** flag internal, non-stable interfaces.

7 +- **Flag** ABI-breaking changes (new, removed, or reordered methods, changed struct layouts) only in the stable surfaces: `WSLCCompat.idl` (the WSLC SDK-facing layer, which must stay backward compatible) and the public plugin API (`WSLPluginHooksV1` / `WSLPluginAPIV1` structs in `WslPluginApi.h`).

8 +- **Do not flag** new methods appended to internal, non-stable interfaces such as `IWSLCSession` in `wslc.idl`, or interfaces in `wslservice.idl`.

10 ### Resource Safety

11 - **Flag** raw `CloseHandle()`, `delete`, `free()`, or manual resource cleanup — require WIL smart pointers

src/windows/service/inc/wslservice.idl

@@ -10,6 +10,8 @@ Abstract:

11 This file contains the COM object definitions used to talk with the WSL

12 service "WslService"

13 + // N.B. These interfaces are internal and non-stable. ABI breaking changes in this

14 + // file are OK, since the client and service always ship together in the same package.

16 --*/