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.

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: Add Design process description & basic style guide #1229

Merged
merged 3 commits into from
Dec 5, 2018
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
24 changes: 24 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,30 @@ and let us know if it's not up-to-date (even better, submit a PR with your corr
7. Once approved and tested, a maintainer will squash-merge to master and will use your PR title/description as the
commit message.

## Design Process

In order to enable efficient collaboration over design documents, the following process should be followed:

1. Open an issue describing the requirements and constraints the design must satisfy
+ Provide a clear list of use-cases that the design intends to address
2. Open a pull request with a Markdown document describing the proposed design. The document should be placed in the
`design` directory at the root of the repository.
+ Design discussions are tracked using the comment stream of the pull request
+ The design document will be merged in and retained as if it were code

## Style Guide

### Markdown

* Adhere to the [GitHub Flavored Markdown](https://github.github.com/gfm/) syntax
* `120` character lines
* ATX style headings (e.g: `## H2 heading`)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What does ATX refer to here?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The GitHub Flavored Markdown specification expressly mentions support for two types of headings:

  1. ATX headings
  2. Setext headings

Apparently, ATX & Setext are tools that offer similar features to Markdown and existed previously, that some people are familiar with. I really just re-used the spec's language here.


### Typescript and Javascript

* `2` space indentation
* `120` character lines

## Tools

The CDK is a big project, and, at the moment, all of the CDK modules are mastered in a single monolithic repository
Expand Down
Empty file added design/.gitkeep
Empty file.