chore: Add Design process description & basic style guide #1229
Conversation
Fixes awslabs/cdk-ops#177
|
|
||
| * Adhere to the [GitHub Flavored Markdown](https://github.github.com/gfm/) syntax | ||
| * `120` character lines | ||
| * ATX style headings (e.g: `## H2 heading`) |
There was a problem hiding this comment.
What does ATX refer to here?
There was a problem hiding this comment.
The GitHub Flavored Markdown specification expressly mentions support for two types of 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.
CONTRIBUTING.md
Outdated
|
|
||
| 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 |
There was a problem hiding this comment.
Where does the file live?
Does it get deleted after the discussion or committed?
There was a problem hiding this comment.
Nah I guess the point of the PR is to keep the traces checked in. As to where the file lives, I can attempt to specify this if that's useful... It felt maybe a little overreaching (especially s we don't have a place juts yet, in fact).
There was a problem hiding this comment.
No, but you know what? I think I'd like for the file to be committed along with the change.
Why not be the first project where we actually keep a set of design documents in our repo, as use to future historians (and team members)?
There was a problem hiding this comment.
I would create a directory /design and recommend that people put the files there.
There was a problem hiding this comment.
@rix0rrr I VERY definitely meant for the documents to live with the project, I just meant we don't have the folder yet... But yeah I can recommend a file name and path.
CONTRIBUTING.md
Outdated
| @@ -41,6 +41,28 @@ 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 must be followed: | |||
There was a problem hiding this comment.
"must" is too strong a word. I would say "recommended"
CONTRIBUTING.md
Outdated
|
|
||
| 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 |
There was a problem hiding this comment.
I would create a directory /design and recommend that people put the files there.
RomainMuller
force-pushed
the
rmuller/contributing-md
branch
from
1d76610
to
0481a21
Compare
RomainMuller
force-pushed
the
rmuller/contributing-md
branch
from
722d755
to
e4fc2e2
Compare
Fixes awslabs/cdk-ops#177
Pull Request Checklist
Please check all boxes (including N/A items)
Testing
tests
manually executed (paste output to the PR description)
(currently maintained in a private repo).
Documentation
Title and description
fix(module): <title>bug fix (patch)feat(module): <title>feature/capability (minor)chore(module): <title>won't appear in changelogbuild(module): <title>won't appear in changelogBREAKING CHANGE: <describe exactly what changed and how to achieve similar behavior + link to documentation/gist/issue if more details are required>Fixes #xxxorCloses #xxxBy submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license.