Process for API Promotion

[aruniverse]

Establish process for promoting apis from @beta to @public @preview, and @public preview to @public. Extend the docs for choosing-appropriate-release-tags to include this.

This is also a great opportunity for us to review our existing non-internal, non-public api surface area and start promoting them as well

[ColinKerr]

• Dev start -> @alpha
  • Code is merged into main after Peer Review by appropriate code owners
  • May still be incomplete, unstable and hacky
  • Design still in early stages
  • Only suitable for POCs in tight collaboration with developer of API.
• @alpha -> @beta
  • Code is complete within some initial scope
  • May still be incomplete and unstable compared with requirements for production use
  • Design and implementation has been tested with at least one POC and feedback incorporated
  • Community feedback is solicited for Code/Design
  • Code is documented with examples
  • Code is tested
• @beta -> @public @preview
  • At least one POC has transitioned to or is transitioning to released feature
  • Learning docs written
  • Feedback has been received and incorporated from at least one other community member.
    • Preferably more than one POC is in progress and has given feedback that has been incorporated.
• @public @preview -> @public
  • Multiple successful uses in production w/ feedback incorporated.
  • Code/API reviewed with learnings from existing uses and future request and it is determined that the current API is suitable for long term use without breaking changes

Special account needs to be taken for:

• Interfaces
  • Hard to make changes via deprecation and replacement.
• Anything persisted to an iModel or exposed as a persistence format in any other context
  • At what point do we make a promise to always be able to load the persisted data?
  • What does deprecation mean for a persistence format?