From 6a8acec86c254cfb847359a746b05cb4059e0931 Mon Sep 17 00:00:00 2001 From: Kaizen Conroy Date: Tue, 1 Oct 2024 16:36:30 -0400 Subject: [PATCH] chore: document new `--unstable` protocol for CLI features --- CONTRIBUTING.md | 18 ++++++++++++++++++ packages/aws-cdk/README.md | 16 ++++++++++++++++ 2 files changed, 34 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6bd1959a5e67b..16a61e896c39f 100644 --- a/CONTRIBUTING.md +++ b/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 diff --git a/packages/aws-cdk/README.md b/packages/aws-cdk/README.md index 57081731a7c4c..ca79343503706 100644 --- a/packages/aws-cdk/README.md +++ b/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.