Provide ability to annotate endpoints and objects unstable/incubating

[chrismale]

Motivation

When developing a new API there maybe a short period before the API reaches a level of stability that it will be long term supported or generally available. In that preliminary development stage an API may change rapidly and the changes may not warrant a major version bump, particularly if there are a known set of consumers who are comfortable with the short term churn. However it is important to convey to consumers that the relevant APIs are in this unstable/incubating phase so they can consciously opt in.

One approach for marking an API as unstable right now has been to prefix the endpoints and objects with incubating. This pattern is sufficient however it creates significant churn when an API moves from being incubating to being long term supported. Even if the wire-api itself remains unchanged, all consumers will need to update their APIs and fix compilation breaks.

Proposal

In addition to the deprecated metadata that can be added to endpoints, adding an unstable marker in the conjure definitions would then allow code-generation to add the appropriate annotation/comment so consumers can see at the code-level whether the API is unstable. It would additionally allow consumers to identify unstable APIs by just looking at the conjure definitions rather than needing to dive into the generated code.

[lycarter]

cc @carterkozak @iamdanfox

[carterkozak]

Could you put something on the calendar to chat through what precisely this would entail and how it would impact codegen and wire calls? + @ferozco @uschi2000 @iamdanfox