Skip to content

Latest commit

 

History

History
162 lines (111 loc) · 11 KB

CONTRIBUTING.md

File metadata and controls

162 lines (111 loc) · 11 KB
Raw

Contributing Guidelines

Thank you for your interest in contributing to our project. Whether it's a bug report, new feature, correction, or additional documentation, we greatly value feedback and contributions from our community.

Please read through this document before submitting any issues or pull requests to ensure we have all the necessary information to effectively respond to your bug report or contribution.

Table of Contents

  1. Reporting Bugs/Feature Requests
  2. Contributing via Pull Requests
  3. Adding an Example
  4. Linking External Example
  5. Style and Formatting
  6. Finding Contributions to Work On
  7. Adding Learning Resources
  8. Code of Conduct
  9. Security Issue Notifications
  10. Licensing

Reporting Bugs/Feature Requests

We welcome you to use the GitHub issue tracker to report bugs or suggest features.

When filing an issue, please check existing open, or recently closed, issues to make sure somebody else hasn't already reported the issue. Please try to include as much information as you can. Details like these are incredibly useful:

  • A reproducible test case or series of steps
  • The version of our code being used
  • Any modifications you've made relevant to the bug
  • Anything unusual about your environment or deployment

Contributing via Pull Requests

Contributions via pull requests are much appreciated. Before sending us a pull request, please ensure that:

  1. You are working against the latest source on the master branch.
  2. You check existing open, and recently merged, pull requests to make sure someone else hasn't addressed the problem already.
  3. You open an issue to discuss any significant work - we would hate for your time to be wasted.

To send us a pull request, please:

  1. Fork the repository.
  2. Modify the source; please focus on the specific change you are contributing. If you also reformat all the code, it will be hard for us to focus on your change.
  3. Ensure local tests pass automated tests (check the scripts directory)
  4. Commit to your fork using clear commit messages.
  5. Send us a pull request, answering any default questions in the pull request interface.
  6. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation.

GitHub provides additional document on forking a repository and creating a pull request.

Adding an Example

When adding a new example, there are several things important to consider as you implement (please create a feature-request issue to discuss these before writing your contribution):

Added Value

As an official learning resource, it is important that any new examples add value to our learning resources. This means that it should not duplicate an existing example, and cover one of the following topics:

  • Document a common infrastructure pattern - (static website, cron triggered lambda, etc.)
  • Outline usage of an L2 construct
  • Cover a less-obvious implementation of one or more constructs - (cross-stack resource sharing, escape hatches, using SSM values during synthesis, etc.)

When we are considering merging a new contribution we will review the above criteria as well as evaluating quality based on the criteria in the following sections.

Language Parity

While we have historically allowed adding examples in just one of our supported languages, moving forward we would like to maintain language parity. This does not necessarily mean that you must write the example in each language yourself, but a PR will not be merged until the example has been added for each language.

If you are looking for help to achieve language parity, you can request help in either the issue related to the new example, or directly through the PR.

Components

When adding a new example, there are several required components. The majority of these will be added when running cdk init.

  1. General Structure

The best way to create the structure for the new example to be added is to run npx cdk init app --language [LANGUAGE] on an empty directory with the example name. This will generate all language-specific components needed for your new example. Please keep the suggested structure for the application (eg. typescript apps start in ./bin/example-name.ts, and store the stack/s in ./lib/example-name-stack.ts).

When submitting the PR, please ensure that the directory includes all relevant package manager and configuration files so that someone else viewing it only needs to run the build commands and cdk deploy to get the example running.

  1. README.md

Every example needs a comprehensive README at the root of its directory. This README can vary depending on the example, but has several required components:

  • Stability Banner: You can use the banner code below to indicate whether an example consists of modules that are "Stable", "Dev-Preview", or "Cfn-Only" (for more information on state, see the Module Lifecycle guide. Please reference the lowest common denominator (if all modules are stable except for one that is dev-preview, you must mark the example as dev-preview)

    • Stable
<!--BEGIN STABILITY BANNER-->
---

![Stability: Stable](https://img.shields.io/badge/stability-Stable-success.svg?style=for-the-badge)

> **This is a stable example. It should successfully build out of the box**
>
> This example is built on Construct Libraries marked "Stable" and does not have any infrastructure prerequisites to build.
---
<!--END STABILITY BANNER-->
  • Dev Preview
<!--BEGIN STABILITY BANNER-->
---

![Stability: Developer Preview](https://img.shields.io/badge/stability-Developer--Preview-important.svg?style=for-the-badge)

> **This is an experimental example. It may not build out of the box**
>
> This example is built on Construct Libraries marked "Developer Preview" and may not be updated for latest breaking changes.
>
> It may additionally requires infrastructure prerequisites that must be created before successful build.
>
> If build is unsuccessful, please create an [issue](https://github.com/aws-samples/aws-cdk-examples/issues/new) so that we may debug the problem 
---
<!--END STABILITY BANNER-->
  • Overview: This should be a description of the example including, but not limited to, an overview of resources being created in the example, a description of any standard/common patterns being used, as well as the overall function of the example.
  • Structure: If the example is more complex than a single stack, or the stack contains more than a couple resources, please describe the structure of application being deployed. This can be as simple as a bulleted list of resources, or as intricate as a complete infrastructure diagram.
  • Build/Deploy: Finally, the README must include the basic build/deploy instructions required for that example in said language.

Linking External Examples

If you have an example project that is out of scope or too large for this repo based on the criteria listed above, but you still think it would be a good learning resource for CDK users, you may contribute it to this repo as an external link.

Simply create a Pull Request to the README of this repo, adding the link to your repo in the "Additional Examples" section. The pull request can be used to discuss the function and content of the linked repo with the CDK team and other contributors. If the repo is not a learning resource, but rather a tool or library based-on, or for use with the CDK consider requesting it be added to the Awesome CDK repo.

Style and Formatting

We strive to keep examples consistent in style and formatting. This hopefully makes navigating examples easier for users. Since the examples span different languages, we try to keep example code as idiomatic as possible.

New guidelines for various languages will be added as we define them.

Typescript

  1. You can use eslint with the standard configuration to check code syntax and style.

Java

  1. Use builders wherever possible. Some classes are unable to have builders generated in JSII but for those that do, prefer them over constructing by hand.
  2. Format your code with google-java-format. If you're using visual studio code, see this comment to get a formatter task setup.

Finding Contributions to Work On

Looking at the existing issues is a great way to find something to contribute on. As our projects, by default, use the default GitHub issue labels (enhancement/bug/duplicate/help wanted/invalid/question/wontfix), looking at any 'help wanted' issues is a great place to start.

Adding Learning Resources

On the main README of this repo, we maintain a shortlist of additional learning resources related to the CDK. The "Officially Supported" section will be maintained by CDK project maintainers, however if you have a resource (workshop, example-set, etc.) you think should be added to the list, create a PR with your reasoning for adding in the description and a CDK maintainer will discuss with you in PR reviews.

When adding a resource (or external example), please make the same considerations you would for adding a new example.

Code of Conduct

This project has adopted the Amazon Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opensource-codeofconduct@amazon.com with any additional questions or comments.

Security Issue Notifications

If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our vulnerability reporting page. Please do not create a public github issue.

Licensing

See the LICENSE file for our project's licensing. We will ask you to confirm the licensing of your contribution.

We may ask you to sign a Contributor License Agreement (CLA) for larger changes.