[Proposal]: <preliminary> documentation element
- Dominant language
- C#
- Stars
- 12.7k
- Forks
- 1.1k
- Avg merge
- 11h 1m
- Merged PRs (30d)
- 3
Description
* Discussion: https://github.com/dotnet/csharplang/discussions/8970
## Summary
[summary]: #summary
I propose updating the C# language specification to define `` 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 `` 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 ``
* 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
:link: [preliminary (Sandcastle XML Comments Guide)](http://ewsoftware.github.io/XMLCommentsGuide/html/c16bece7-694e-48ca-802d-cf3ae9205c55.htm)
:link: [Breaking Changes Policy (Threading API Reference)](http://tunnelvisionlabs.github.io/dotnet-threading/docs-latest/html/e02b9881-f06b-4420-aace-71b176d635db.htm) (See the **Preliminary Features** section at the bottom)
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.