Attributes for denoting API stability levels

Conceptual overview

This proposal introduces two new attributes for marking the stability level of public Q# APIs, allowing for warnings to be generated when calling into unstable functions and operations.

This in turn will allow for new library features to be developed and prototyped in an unstable state without blocking on a complete API review, and for us to get more feedback on how unstable APIs work in practice before committing to final versions.

Current status

No distinction is made between different stability levels; all public Q# functions, operations, and UDTs are considered to be fully stable from their first release.

User feedback

n/a

Related issues

https://github.com/microsoft/qsharp-compiler/issues/998

Proposal

New and modified functions, operations, and UDTs

namespace Microsoft.Quantum.Documentation {
    /// # Summary
    /// Denotes that a function, operation, or user-defined type is unstable,
    /// and may change or be removed without warning in future versions.
    /// A URL must be provided that links to a public GitHub issue tracking
    /// the discussion regarding this issue.
    @Attribute()
    newtype Unstable = (
        IssueUrl: String
    );

    /// # Summary
    /// Denotes that a function, operation, or user-defined type is stable,
    /// and what version of the containing library the item first became stable in.
    ///
    /// # Named Items
    /// ## Version
    /// The first version of the package containing this item in which the item
    /// was stabilized.
    ///
    /// # Example
    /// The following denotes that a function `Sinc` first became stable as
    /// of version `"0.20.1"` of the package containing `Sinc`.
    /// ```qsharp
    /// @Stable("0.20.1")
    /// function Sinc(x : Double) : Double { ... }
    /// ```
    @Attribute()
    newtype Stable = (
        Version: String
    );
}

Modifications to style guide

If this proposal is adopted, API stability rules should be relaxed only for those functions, operations, and user-defined types denoted with @Unstable. Authors should be encouraged to place either @Unstable("...") or @Stable("..."), with stability being implied in the absence of any stability attribute.

Impact of breaking changes

n/a

Examples

Current status

n/a

Using proposed changes

See documentation comments on proposal above.

Relationship to Q# language feature proposals

Alternatives considered

Open design questions and considerations

Is Microsoft.Quantum.Documentation the right namespace?
Should @Stable() be dropped in favor of only marking as unstable?
Should @Stable() require version numbers (similar to Rust's #[stable("...")] attribute)?

microsoft / QuantumLibraries