Graduate @aws-cdk/aws-kinesis to stable

[iliapolo]

We plan on graduating this module to stable.

What does it mean?

It means we will start providing semantic versioning guarantees on the existing API's.

Use this issue to provide feedback about the current API and any changes you think are warranted.

Following are the tasks needed to complete before flipping the switch:

• Validate no p0 bugs in the last 4 weeks.
• Validate L2 coverage.
• Clear awslint exclusions (chore(kinesis): remove linter exclusions #6758)
• Update README (docs(kinesis): refresh README and add updated snippets #7038)
• Retention period is not of Duration type (fix(kinesis): retention period does not use Duration type #7037)
• Streams permissions is missing ListShards permissions (feat(kinesis): grantRead now allows the ListShards action and grant is now public #6141)
• Enable Stream Encryption by default (supported in all regions except cn-north-1 and cn-northwest-1 (feat(kinesis): streams are encrypted by default #7102)
• Update grantxYz... methods (i.e. take out describeStream and add getShardIterator) - added as a part of (fix(kinesis): retention period does not use Duration type #7037)
• Conduct API review.

[richardhboyd]

I would recommend that we graduate specific Constructs to Stable. My biggest concern with Stable packages are two-fold:
(1) If someone wants to add a new Construct to a package, it has to go from 0 to Stable in one PR without the benefit of an experimental period to test-drive the API. We're already seeing this in API Gateway
(2) the L1 Constructs are the most stable resources that exist in CDK. They should be marked as stable as soon as the cfn spec is processed.

[iliapolo]

@richardhboyd Wrote:

I would recommend that we graduate specific Constructs to Stable. My biggest concern with Stable packages are two-fold:
(1) If someone wants to add a new Construct to a package, it has to go from 0 to Stable in one PR without the benefit of an experimental period to test-drive the API. We're already seeing this in API Gateway

You definitely make a good point.

However, this graduation process reflects libraries we want to mark as stable given the current methodology, which is package wide. As it stands now, we allow for experimental Constructs or API to exist inside stable packages, by using the @experimental annotation. This means that stability can be reached over a long period of time, with several PR's.

We are aware of the confusion this might create, and are already considering ways of resolving this. One way would be Construct level maturity, another is splitting experimental constructs to its own "*-experimental" package.

In fact, we already have a pending RFC that addresses this problem.
It would be great if you voice your concerns and provided feedback about this in the RFC.

@richardhboyd Wrote:

(2) the L1 Constructs are the most stable resources that exist in CDK. They should be marked as stable as soon as the cfn spec is processed.

This depends on the maturity methodology we choose. L1 constructs are always auto-generated, and are therefore stable by nature. Do you feel this needs better clarification? Are users reluctant to use L1 constructs inside experimental packages for fear of API breakage?