chore: document new --unstable protocol for CLI features (#31612)

New protocol for `--unstable` is documented here and being used in #31611 

----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

CONTRIBUTING.md

@@ -954,6 +954,24 @@ grantAwesomePowerBeta1()
 When we decide it's time to graduate the API, the latest preview version will
 be deprecated and the final version - `grantAwesomePower` will be added.
 
+### Adding new experimental CLI features
+
+In order to move fast when developing new CLI features, we may decide to release 
+functionality as "experimental" or "incremental." In this scenario we can utilize
+explicit opt-in via an `--unstable` flag.
+
+Explicit opt-ins would look something like this:
+
+```bash
+cdk new-command --unstable='new-command'
+
+cdk bootstrap --unstable='new-funky-bootstrap'
+```
+
+And can be simply added as an additional flag on the CLI command that is being worked on.
+When the time comes to stabilize the command, we remove the requirement that such a flag
+is set.
+
 ## Documentation
 
 Every module's README is rendered as the landing page of the official documentation. For example, this is

packages/aws-cdk/README.md

@@ -33,6 +33,8 @@ The AWS CDK Toolkit provides the `cdk` command-line interface that can be used t
 - [SSO Support](#sso-support)
 - [Configuration](#configuration)
   - [Running in CI](#running-in-ci)
+- [Stability](#stability)
+- [Changing the default TypeScript transpiler](#Changing-the-default-TypeScript-transpiler)
 
 
 This module is part of the [AWS Cloud Development Kit](https://github.com/aws/aws-cdk) project.
@@ -1067,6 +1069,20 @@ The CLI will attempt to detect whether it is being run in CI by looking for the
 environment variable `CI=true`. This can be forced by passing the `--ci` flag. By default the CLI
 sends most of its logs to `stderr`, but when `ci=true` it will send the logs to `stdout` instead.
 
+### Stability
+
+Sometimes the CDK team will release experimental or incremental features. In these scenarios we will
+require explicit opt-in from users via the `--unstable` flag. For example, if we are working on a new
+bootstrap feature and decide to release it incrementally, we will "hide" its functionality.
+Opting in would look something like this:
+
+```bash
+cdk bootstrap --unstable='new-funky-bootstrap'
+```
+
+When the feature is stabilized, explicit opt-in is no longer necessary but the feature will continue
+to work with the `--unstable` flag set.
+
 ### Changing the default TypeScript transpiler
 
 The ts-node package used to synthesize and deploy CDK apps supports an alternate transpiler that might improve transpile times. The SWC transpiler is written in Rust and has no type checking. The SWC transpiler should be enabled by experienced TypeScript developers.