Explicit public surface definition

[sobolk]

We should define and document our public contract. So that customers know how our public surface is evolved and for us to guide that evolution.

We should define and publish:

1. What API changes are allowed in what package.
2. How do we mark APIs as public, "public but for internal purpose", experimental etc.
3. Which stateful parts, like deployed resources are considered contract and which not. For example, CFN outputs.

In addition, we should implement automated checks to enforce that publicly facing elements are properly documented and annotated.

[redjonzaci]

can i help?