Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 1 commit into from
Oct 1, 2024
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
16 changes: 16 additions & 0 deletions packages/aws-cdk/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down
Loading