Describe experimental COM interfaces

Fixes #5212

docs/design/README.md

@@ -20,4 +20,6 @@ The [Existential Types](existential-types.md) document goes into some detail abo
 
 The [Capabilities](capabilities.md) document explains the proposed model for how Slang will support general notions of profile- or capability-based overloading/dispatch.
 
-The [Casting](casting.md) document explains how casting works in the slang C++ compiler code base.
+The [Casting](casting.md) document explains how casting works in the slang C++ compiler code base.
+
+The [Experimental API Interfaces](experimental.md) document explains how experimental Slang API changes are to be deployed.

docs/design/experimental.md

@@ -0,0 +1,68 @@
+Deploying Experimental API Additions
+====================================
+
+This page intends to provide guidance to Slang developers when extending the Slang API, particularly when working on experimental features.
+It applies to the "COM-lite" Slang API, rather than the deprecated C Slang API (sp* functions).
+
+The goal is to maintain binary compatibility as much as possible between Slang releases, and to aid applications in dealing with changes to Slang.
+
+Slang is distributed as a dynamic library, and there is an expectation from Slang API users that upgrading by installing an updated slang.dll or slang.so will not break their application unnecessarily.
+
+ABI compatibility within the Slang API can be preserved between releases if some rules are followed by developers.
+
+Slang API uses a "COM-lite" structure wherein functionality is exposed through interfaces on objects. If the interfaces never change, ABI compatibility is preserved, but changes happen. When adding or changing interfaces, please observe the following:
+
+* It is preferred to create *new* COM interfaces when adding new functionality.
+** This completely maintains ABI compatibility.
+** Applications must acquire access to the new functionality using QueryInterface(), which will gracefully fail if the slang.dll/slang.so does not have the implemented functionality.
+
+* Changes to existing virtual methods in interfaces should be avoided, as that is an ABI breakage.
+** If a change is required though, change the interface's UUID.
+
+* New virtual methods _may_ be added (only) to the end of existing COM interface structs.
+** This does not disturb the ABI compatibility of the associated vtable. Old apps can remain unaware of the new methods.
+** A UUID change is not necessary.
+** Note that in the event that a Slang application which uses the added feature is run with an old slang.dll/slang.so, the experience for the user is not as clean as if the added method belongs to a new interface.
+
+Adding Experimental Interfaces
+==============================
+
+When the above recommendations cannot be followed, as with features that are expected to be iterated on or are regarded as temporary, there are additional recommendations.
+
+Interfaces that are expected to change must be marked "_Experimental" in their class name and in their UUID name.
+
+Note: Use uuidgen to generate IIDs new interfaces.
+
+For example,
+
+/* Experimental interface for doing something cool. This interface is susceptible to ABI breakage. */
+struct ICoolNewFeature_Experimental : public ISlangUnknown
+{
+    SLANG_COM_INTERFACE(0x8e12e8e3, 0x5fcd, 0x433e, { 0xaf, 0xcb, 0x13, 0xa0, 0x88, 0xbc, 0x5e, 0xe5 })        
+
+    virtual SLANG_NO_THROW SlangResult SLANG_MCALL coolMethod() = 0;
+};
+
+#define SLANG_UUID_ICoolNewFeature_Experimental ICoolNewFeature_Experimental::getTypeGuid()
+
+Removing Experimental Interfaces
+================================
+
+By the nature of being marked "Experimental", users have been warned that the interfaces are not offically supported and may be removed. You may simply delete the class and UUID, e.g. "ICoolNewFeature_Experimental" struct may be deleted from slang.h along with the definition of SLANG_UUID_ICoolNewFeature_Experimental.
+
+This will show up in applications as QueryInterface failures.
+
+Changing Experimental Interfaces
+================================
+
+Backwards incompatible changes to Slang COM interfaces should be accompanied with a UUID change.
+
+In the event that an old application runs with a new slang library, applications are more capable of gracefully handling an unavailable interface than a changed one. The former may be still be functional, or include a helpful error message, whereas the latter is most likely a crash of some sort.
+
+Promoting Experimental Interfaces
+=================================
+
+The class name and the UUID name should be changed in slang.h and in the slang source code, e.g. Rename "ICoolNewFeature_Experimental" to just "ICoolFeature".
+
+The SLANG_UUID for the interface should be renamed to omit "EXPERIMENTAL" but its value should remain the same. If there are no backwards incompatible changes that accompany the promotion from experimental to permananent, applications written against the experimental version can continue working against Slang libraries where the interface was promoted to permanent.
+

docs/user-guide/08-compiling.md

@@ -314,6 +314,9 @@ Application code is expected to correctly maintain the reference counts of `ISla
 Many Slang API calls return `SlangResult` values; this type is equivalent to (and binary-compatible with) the standard COM `HRESULT` type.
 As a matter of convention, Slang API calls return a zero value (`SLANG_OK`) on success, and a negative value on errors.
 
+> #### Note ####
+> Slang API interfaces may be named with the suffix "_Experimental", indicating that the interface is not complete, may have known bugs, and may change or be removed between Slang API releases.
+
 ### Creating a Global Session
 
 A Slang _global session_ uses the interface `slang::IGlobalSession` and it represents a connection from an application to a particular implementation of the Slang API.