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

docs(contributing): add introduction to contributing and update flowchart to include major and minor contributions #32619

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs(contributing): add introduction to contributing and update flowchart to include major and minor contributions #32619

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
113 changes: 63 additions & 50 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,18 +1,20 @@
# Contributing to the AWS Cloud Development Kit

Thanks for your interest in contributing to the AWS CDK! ❤️
The AWS Cloud Development Kit (AWS CDK) is an open-source software development
framework that you can contribute to. We highly value community contributions,
which significantly impact the development of the AWS CDK. This document will
guide you through learning about contributions, getting started with creating
contributions, and understanding what is required to ensure that your
efforts are impactful and your contribution process goes smoothly.

We highly value contributions, with roughly half of all commits to the CDK
coming from the community. We want to recognize all your hard work
by getting your code merged as quickly as we can, so please read the guidance
here carefully to make sure the review process goes smoothly.
Thank you for your interest in contributing to the AWS CDK! We look forward to
working with you to improve the AWS CDK for everyone. ❤️

The CDK is released under the [Apache license](http://aws.amazon.com/apache2.0/).
Any code you submit will be released under that license.

This document describes how to set up a development environment and submit your changes. Please
let us know if it's not up-to-date (even better, submit a PR with your corrections ;-)).
The AWS CDK is released under the [Apache license](http://aws.amazon.com/apache2.0/).
Any code that you submit will be released under that license.

- [What are contributions?](#what-are-contributions)
- [How contributions work](#how-contributions-work)
- [Where To Contribute](#where-to-contribute)
- [Demonstrating Value](#demonstrating-value)
- [Publishing Your Own Package](#publishing-your-own-package)
Expand Down Expand Up @@ -52,47 +54,58 @@ let us know if it's not up-to-date (even better, submit a PR with your correctio
- [Badges (Pilot Program)](#badges-pilot-program)
- [Related Repositories](#related-repositories)

## Contribution Workflow Diagram
## What are contributions?

A *contribution* refers to any improvement or addition to the AWS CDK from the
community. You make contributions to the AWS CDK through the `aws-cdk`
repository. They can include the following:

- **New features** - New functionality for existing L2 constructs or new L2
constructs for new or existing AWS services.
- **Bug fixes** - Address and fix issues in the code to improve functionality
or correct errors.
- **Documentation** - Improve documentation, such as adding examples, enhancing
readability, or updating existing content.
- **Tests** - Add or improve tests to increase code coverage and ensure
stability.
- **Refactoring** - Improve the code structure or performance without altering
its behavior.

Contributions can be *major* or *minor* in scope and size:

- **Major contributions** - Includes major new additions, such as new L2
constructs, updates that change how the AWS CDK works, or enhancements to
existing AWS CDK features and functionality that introduce breaking changes.
- **Minor contributions** - Includes bug fixes, improvements to existing L2
constructs, and other updates that don't alter how the AWS CDK works, such
as the addition of tests and changes to documentation.

## How contributions work

The following diagram illustrates how contributions work, from creation to completion:

```mermaid
flowchart TD
A(Identify Desired Functionality) --> B(Search For Existing Artifacts)
B --> C[External Packages]
B --> D[Relevant Issues And PRs]
C --> E{"Does A High Quality
Solution Exist?"}
D --> F{"Is There A PR In Progress"}
E --> |Yes| G(("Ask How You
Can Help"))
F --> |Yes| G
E --> |No| H(Evaluate Where To Contribute)
F --> |No| H
H --> I{"Is There Clear Evidence
For Inclusion In AWS-CDK"}
I --> |Yes| subEvidence
I --> |No| J{"Do You Want To Pursue Eventual
Inclusion In AWS-CDK"}
J --> |No| L(("Create Private
Implementation"))
J --> |Yes| K((Publish A Package))
subEvidence --> M(Make Pull Request)
M --> N{"Passes CI Checks, Linters,
And Follows Design Guidelines"}
N --> O(Review)
O --> |Accepted| R(Hooray!)
O --> P(Changes Requested)
P --> Q(Make Changes)
Q --> O
O --> |Refused| K

subgraph subEvidence[Gather Evidence]
direction LR
engagement[Engagement from Multiple users]
core[Intersects With Core Framework Concerns]
quality["Clear, Well Defined, Solution With
Limited Scope And Clear Boundaries"]
external[External Packages]
issues[Relevant Issues And PRs]
end
A(Identify desired functionality) --> B(Consider a contribution)
B --> C[External packages]
B --> D[Relevant Issues and PRs]
C --> E{Is a contribution the right solution?}
D --> E
E --> |Yes|F{Is your contribution major or minor?}
E --> |No|G((Pursue alternative solutions))
F --> |Major|H(Submit an RFC to discuss)
F --> |Minor|I(Code your changes)
H --> Q{Is a contribution the right solution?}
I --> J(Submit your PR)
J --> K[PR passes checks, linters, and follows design guidelines]
K --> L[PR is reviewed]
L --> M{Should PR be approved?}
M --> |Yes|N((PR is approved and merged))
M --> |No|O{Should PR be modified or closed?}
O --> |Modified|I
O --> |Closed|P((PR is closed))
Q --> |Yes|I
Q --> |No|S((RFC is closed))
```

## Where to Contribute
Expand Down Expand Up @@ -123,7 +136,7 @@ All of this information will help make it clear to reviewers why your contributi

This is by far the strongest signal you can give to the CDK team that a feature should be included within the core aws-cdk packages. A package published on npm, PyPI, Maven Central, NuGet, and GitHub (for Go) that has good documentation, a clear purpose, and an active group of users is a good indication that the functionality it provides is useful and should be examined for inclusion in the core aws-cdk packages. This may not be the goal of any given package, and some constructs and features do not provide functionality that should ever be vended as part of the core framework. However, if a package you own does include functionality that you and other users believe should be vended as part of the core CDK, we encourage making a pull request, or RFC if appropriate, proposing its inclusion.

#### Trust and Third Party Packages
#### Trust and Third Party Packages

An argument we commonly hear why contributors don't want to publish their contributions in their own packages, is that organizations have restrictions on what packages they allow to be used and these restrictions commonly include limiting usage of packages to those owned and distributed only from trusted sources. We recognize trust is an important part of the software dependency chain, and we take that into consideration when evaluating contributions in aws-cdk. However, not everything can be owned by the aws-cdk team. Strictly from a technical limitation perspective, `aws-cdk-lib` is big. Continuing a system that makes it, potentially, many multiple times bigger, has a cost on usability. Additionally, as the surface area widens, the aws-cdk team becomes stretched ever thinner and isn't able to properly maintain what we own.

Expand Down
Loading