-
Notifications
You must be signed in to change notification settings - Fork 1.1k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
adding docs/proposals/ folder and sample template
Signed-off-by: Chris Hein <me@chrishein.com>
- Loading branch information
1 parent
19e72eb
commit 59d237f
Showing
3 changed files
with
58 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,36 @@ | ||
Designs | ||
======= | ||
|
||
These are design documents for changes to Controller Runtime They exist | ||
to help document the design processes that go into writing Controller | ||
Runtime, but may not be up-to-date (more below). | ||
|
||
Not all changes to Controller Runtime need a design document -- only major | ||
ones. use your best judgement. | ||
|
||
When submitting a design document, we encourage having written | ||
a proof-of-concept, and it's perfectly acceptable to submit the | ||
proof-of-concept PR simultaneously with the design document, as the | ||
proof-of-concept process can help iron out wrinkles and can help with the | ||
`Example` section of the template. | ||
|
||
## Out-of-Date Designs | ||
|
||
**Controller Runtime documentation | ||
[GoDoc](https://godoc.org/sigs.k8s.io/controller-runtime) should be | ||
considered the canonical, update-to-date reference and architectural | ||
documentation** for Controller Runtime. | ||
|
||
However, if you see an out-of-date design document, feel free to submit | ||
a PR marking it as such, and add an addendum linking to issues documenting | ||
why things changed. For example: | ||
|
||
```markdown | ||
|
||
# Out of Date | ||
|
||
This change is out of date. It turns out curly braces a frustrating to | ||
type, so we had to abandon functions entirely, and have users specify | ||
custom functionality using strings of Common LISP instead. See #000 for | ||
more information. | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,21 @@ | ||
Title of the Design | ||
=================== | ||
|
||
<!-- Describe your change here. This is purposefully freeform: we want | ||
enough information to evaluate the design, but not so much that you're | ||
annoyed by the overall design process and decide to bake cookies instead. | ||
--> | ||
|
||
## Example | ||
|
||
<!-- Specify an example of how the user would use this. It helps other | ||
contributors get a feel for how this will look in real code, and provides | ||
a good opportunity to evaluate the end-user feel of the code for yourself. | ||
If you find yourself groaning at verbosity, copy-and-pasting a lot, or | ||
writing a bunch of tiny helper functions, it's a good indication that you | ||
might need to re-evaluate the user experience of your design. | ||
This is also a good opportunity to stop and write a proof-of-concept, if | ||
you haven't already, which should help catch practical nits with the | ||
design. --> |