-
Notifications
You must be signed in to change notification settings - Fork 1.4k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
This adds a design folder and template that we can use for documenting major design decisions.
- Loading branch information
1 parent
c2276b8
commit 3ab437e
Showing
3 changed files
with
59 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,37 @@ | ||
Designs | ||
======= | ||
|
||
These are design documents for changes to KubeBuilder (and | ||
cross-repository changes for related projects, like controller-runtime and | ||
controller-tools). They exist to help document the design processes that | ||
go into writing KubeBuilder, but may not be up-to-date (more below). | ||
|
||
Not all changes to KubeBuilder 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 simulatenously 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 | ||
|
||
**KubeBuilder documentation (the [book](https://book.kubebuilder.io) and | ||
the [GoDoc](https://godoc.org/sigs.k8s.io/controller-runtime)) should be | ||
considered the canonical, update-to-date reference and architectural | ||
documentation** for KubeBuilder. | ||
|
||
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 oportunity 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 oportunity to stop and write a proof-of-concept, if | ||
you haven't already, which should help catch practical nits with the | ||
design. --> |