From 0aad50bc58e273cc7fa31736cfb3a1d3c3d6b268 Mon Sep 17 00:00:00 2001
From: Darren Hoehna <dhoehna@yahoo.com>
Date: Wed, 16 Mar 2022 14:21:38 -0700
Subject: [PATCH] User/dahoehna/api contracts (#2110)

* Adding WinRTAPIContracts

* Fixing broken link

* Converting tabs to spaces

* Addresing comments.  Moving to spec folder

* Adding changes

* Adding forbidden changes

* Adding structs

* Updating spec

* Fixing example typo

* Adding scope to EV tracking

* Revert "Adding scope to EV tracking"

This reverts commit 1981e80a3d080d9362d3146035f38a2ca895a9a9.

* Adressing comments

* Adding notes about contracts over versions

* FOrgot formatting

* Changing verbage for contract numbering

* Capatalizing contracts

Co-authored-by: Darren Hoehna <dahoehna@microsoft.com>
---
 specs/WinRT/WinRTAPIContracts.md | 88 ++++++++++++++++++++++++++++++++
 1 file changed, 88 insertions(+)
 create mode 100644 specs/WinRT/WinRTAPIContracts.md

diff --git a/specs/WinRT/WinRTAPIContracts.md b/specs/WinRT/WinRTAPIContracts.md
new file mode 100644
index 0000000000..218f2f2dcc
--- /dev/null
+++ b/specs/WinRT/WinRTAPIContracts.md
@@ -0,0 +1,88 @@
+# New Document
+# Windows App SDK API Contracts
+
+## Summary
+Customers trust that Microsoft products are sound. As Windows App SDK evolves and more developers
+use Windows App SDK in their own projects Windows App SDK needs a way, at build time and run time,
+to allow apps to light up API features and to gracefully degrade. This can be achieved by looking
+at the deltas between APIs.
+
+In order to allow apps to depend on API versions Windows App SDK will add contracts to all their
+WinRT APIs.
+
+## Architecture Decisions
+1. Contract boundaries
+   1. One contract per feature/component/sub-system.
+   2. Contracts will not span across a transport package/repo.
+2. Contract numbering  
+Contracts versions are a single number with no minor version, no "x.y".  The contract version is
+frozen on a stable release.  Any changes after a stable release requires the version to be incremented.
+3. Enforcement  
+The build system has gates that enforce contract versioning to verify that contract is present,
+ up to date, and there are no conflicts between APIs.
+4. Contract migration  
+This spec does not deal with contract migration. A separate spec will be available for contract
+migration if, and when, it is needed.
+5. Internal contracts  
+All WinRT internal APIs have a contract, and the version is 1. The version is never updated.
+6. Contract naming  
+Contract names need to end with the word `Contract`.
+
+## Adding a new contract
+Contract placement is part of an API review. When adding a new API, the API team will
+talk about what contract the API will go under.
+
+## Example
+```
+namespace Microsoft.Windows.System
+{
+    [contractversion(1)]
+    apicontract WindowsSystemContract {}
+    
+    [Contract(MicrosoftWindowsSystem, 1)]
+    runtimeclass EnvironmentManager
+    {
+        static EnvironmentManager GetForProcess();
+        static EnvironmentManager GetForUser();
+        static EnvironmentManager GetForMachine();
+
+        static Boolean IsSupported{ get; };
+
+        IMapView<String, String> GetEnvironmentVariables();
+        String GetEnvironmentVariable(String name);
+        void SetEnvironmentVariable(String name, String value);
+
+        // Path manipulation
+        void AppendToPath(String path);
+        void RemoveFromPath(String path);
+
+        // PathExt Manipulation
+        void AddExecutableFileExtension(String pathExt);
+        void RemoveExecutableFileExtension(String pathExt);
+    }
+}
+```
+## 1.1 ship blocker
+Any APIs that changed between 1.0 and 1.1 need to add a contract or 1.1 will not ship.
+
+## Telemetry
+API specific telemetry will not be collected because it does not provide any additional information
+compared to the Windows App SDK version.
+
+## Gate check-ins
+Because the contracts are used for API versions there will need to be work done in the build system
+to make sure
+1. All APIs have contracts
+2. Each contract is correct. This means version and name.
+3. All Contracts and dependencies work with each other.
+4. Contracts/Types in releases honor the source/binary/behavior compatibility rules e.g. 
+contracts/types in a stable release doesn't change in future releases of the same major version
+(e.g. contracts/types in 1.1 don't change in 1.2, 1.3, ...)
+
+The builds that check for contracts compatibility are:
+1. Nightly
+2. Release 
+3. PR
+
+## Open issues
+None.