Design and RFC Process
Relevant source files
The following files were used as context for generating this wiki page:The AWS Cloud Development Kit (AWS CDK) project utilizes a structured design and Request for Comments (RFC) process to manage its evolution. This process ensures transparency, allows for community feedback on new features and significant changes, and maintains the stability of the framework. Key components of this process include a public roadmap, formal RFC documents for major changes, and specific contribution guidelines that encourage design documentation.
This system allows developers and contributors to understand upcoming features, participate in design decisions, and align their contributions with the project's direction. The process is managed across several repositories, including the main aws-cdk repository and the dedicated aws-cdk-rfcs repository.
Sources: README.md:23-25, ROADMAP.md:3-8
Feature Roadmap and Lifecycle
The project's direction and priorities are publicly tracked on the AWS CDK Roadmap project board. This board provides a high-level view of features in various stages of development, allowing contributors to plan their work and avoid conflicts with in-progress efforts.
Sources: ROADMAP.md:3-8, README.md:104-106
Roadmap Stages
Features on the roadmap progress through a series of stages, each represented as a column on the project board.
| Stage | Description |
|---|---|
| Researching | The team is gathering use cases and feedback on a potential feature. There is no firm commitment to deliver items in this stage. |
| We’re working on it | The feature has a design specification and an assigned developer. It is in active development. |
| Developer preview | The feature is available as a release candidate for user acceptance testing. APIs in this stage may still have breaking changes. |
| Shipped | The feature is generally available, fully supported, and its API is considered stable and safe for production use. |
Sources: ROADMAP.md:27-44
The following diagram illustrates the lifecycle of a feature as it moves through the roadmap stages.
This diagram shows the progression of a feature from the initial research phase to its final, shipped state.
Sources: ROADMAP.md:27-44
Design Documents and RFCs
For larger features, contributions are more likely to be accepted if they are accompanied by a design document. These documents are a crucial part of the development process, outlining the motivation, requirements, and proposed implementation for a new feature.
The aws-cdk-rfcs repository is the central place for formal Request for Comments (RFC) documents. This process allows the community to engage in design conversations and provide feedback before implementation begins.
Sources: packages/@aws-cdk/aws-ecs/CONTRIBUTING.md:41-45, ROADMAP.md:6-7
Example RFC: Publishing the Construct Tree
A concrete example of this process is the RFC for publishing the CDK construct tree. The goal of this RFC was to expose the construct tree as an artifact within the Cloud Assembly (cdk.out), enriching the developer experience for debugging and understanding CDK applications.
Sources: design/construct-tree.md:5-8
Motivation
The primary motivation was to provide developers with better insight into their applications. When using high-level constructs, it can be challenging to understand the underlying AWS resources and their properties without inspecting the generated CloudFormation templates. Exposing the construct tree helps answer questions like:
- What resources does a specific construct contain?
- What properties were resources initialized with?
- How are constructs related to each other?
Sources: design/construct-tree.md:23-53
Proposed Solution: tree.json
The RFC proposed generating a tree.json file during cdk synth. This file would contain a structured representation of the application's construct tree.
The proposed data model includes two main parts: construct properties and metadata properties.
Construct Properties
| Property | Type | Required | Source | Description |
|---|---|---|---|---|
path | string | Required | construct.node.path | Full, absolute path of the construct within the tree. |
children | Array | Not Required | construct.node.children | An array of absolute paths to the direct children of this construct. |
attributes | Array | Not Required | construct.node.attributes | Attributes describing the resources and properties encapsulated by the construct. |
Sources: design/construct-tree.md:100-104
Metadata Properties
Constructs can provide arbitrary metadata, which is stored in an attributes bag. To avoid conflicts, attribute keys are namespaced by convention.
| Property | Type | Required | Description |
|---|---|---|---|
attributes | Array | Not Required | A key-value map for arbitrary metadata like configuration, type, and properties. |
For example, CloudFormation resources use keys like aws:cdk:cloudformation:type and aws:cdk:cloudformation:properties.
Sources: design/construct-tree.md:108-115
The following diagram illustrates the structure of the proposed tree.json file.
This diagram shows the nested structure of the tree.json object, from the root to individual resource attributes.
Sources: design/construct-tree.md:118-151
Design in Practice: Declarative CDK (deCDK)
The deCDK module is another example of a feature with a well-defined public design. It allows defining CDK applications declaratively using a CloudFormation-like JSON/YAML format. The design process, referred to as "deconstruction," involves reflecting on the AWS Construct Library's type system to create a declarative interface.
Sources: packages/decdk/README.md:1-5, packages/decdk/README.md:28-30
Deconstruction Process
The deconstruction process maps object-oriented CDK concepts to declarative JSON structures.
This flowchart shows how deCDK translates a TypeScript CDK construct instantiation into its equivalent declarative JSON representation.
Sources: packages/decdk/README.md:71-90
Key mappings include:
- Constructs: Mapped to resources in the
Resourcessection with aTypecorresponding to the fully-qualified class name. - Props Interfaces: Mapped to JSON objects under
Properties. - Enum-like Classes: Static properties of classes (e.g.,
lambda.Runtime.NODEJS_12_X) are mapped to simple string values (e.g.,"NodeJS12X"). - References: References to other constructs are handled using the
Refintrinsic, similar to CloudFormation.
Sources: packages/decdk/README.md:32-69
Breaking Changes and Stability
A critical aspect of the design process is managing stability and breaking changes. The project enforces rules to prevent breaking changes in stable modules.
The PR linting process includes checks to validate how breaking changes are documented and whether they affect stable modules.
- A breaking change must be noted in the PR body with a line starting exactly with
BREAKING CHANGE:. - The PR title must specify the module affected by the breaking change.
- Breaking changes are disallowed in modules marked as
stable.
Sources: tools/prlint/lint.ts:91-111
This process ensures that the stability promises made to users are upheld, and any unavoidable breaking changes are clearly communicated.
This sequence diagram illustrates how the PR linter validates that breaking changes are not introduced into stable modules.
Sources: tools/prlint/lint.ts:105-111, packages/@aws-cdk/aws-docdb/package.json:101
Conclusion
The AWS CDK project's design and RFC process is a comprehensive framework that balances rapid feature development with the need for stability and community involvement. Through public roadmaps, formal design documents, and automated validation, the project maintains a high standard of quality and transparency. This structured approach empowers both the core team and the wider community to contribute effectively to the evolution of the AWS CDK.
Sources: ROADMAP.md:10-18, README.md:108-110