Proposal: <preliminary> documentation element

[sharwell]

I propose updating the C# language specification to define <preliminary> as a section-level documentation element. This element is valuable in versioning strategies where APIs may be included in published binaries prior to being declared stable. One recent example is the IOperation APIs used by Roslyn. Defining the <preliminary> element provides several benefits to library authors and users:

• Library authors can validate the defined public API surface for both stable and preliminary APIs by updating PublicApiAnalyzer to account for <preliminary>
• Library users can avoid using preliminary APIs by installing an analyzer capable of identifying preliminary APIs in a uniform manner
• In cases where library users wish to use a preliminary API, analyzers can help users contain the usage scope to avoid possible negative impact on other parts of an application

🔗 preliminary (Sandcastle XML Comments Guide)
🔗 Breaking Changes Policy (Threading API Reference) (See the Preliminary Features section at the bottom)

[sharwell]

/cc @EWSoftware