Design docs v2 #2
Conversation
Signed-off-by: Samuel Hawker <[email protected]>
Signed-off-by: Samuel Hawker <[email protected]>
Signed-off-by: Samuel Hawker <[email protected]>
Signed-off-by: Samuel Hawker <[email protected]>
Signed-off-by: Samuel Hawker <[email protected]>
Signed-off-by: Samuel Hawker <[email protected]>
Also simplification Signed-off-by: Samuel Hawker <[email protected]>
Signed-off-by: Samuel Hawker <[email protected]>
|
|
||
| This document is intended to progress discussion about how to write and maintain [design documentation](https://en.wikipedia.org/wiki/Software_design_description) for Strimzi. | ||
|
|
||
| The main goal of design documents for Strimzi is to make contributors more effective by encouraging all involved to think through the design and gather feedback from others. People often think the point of a design doc is to to teach others about some system or serve as documentation later on. While those can be beneficial side effects, they are not the goal in and of themselves. |
There was a problem hiding this comment.
Is this still the main goal? It still seems at odds to the benefits listed
There was a problem hiding this comment.
How so? What would you say is the main goal?
There was a problem hiding this comment.
The main goal of having design documents for Strimzi is so that behaviours of Strimzi as a whole and each of the components are well defined and are agreed upon.
Is what I am changing this to
| (Continued) | ||
| ``` | ||
|
|
||
| The above is just an example but I think it demonstrates the value of a deeper context for how the Strimzi project is written but without general specifics. Moreover this should be fairly simple to maintain as the overall architecture and flow doesn't change often and should need little more than a single sentence change when they do. |
There was a problem hiding this comment.
"general specifics" change to "without describing implementation details"
|
|
||
| ### Where to write a design document | ||
|
|
||
| A design document should be a markdown file located in the `design` directory of the repository they are located in, for instance all design documents relating to the strimzi operator(s) should be located in the `strimzi-kafka-operator` repository under the `design` folder. |
There was a problem hiding this comment.
"they are located in" - should this be "the component code is located in"
| A design document should be a markdown file located in the `design` directory of the repository they are located in, for instance all design documents relating to the strimzi operator(s) should be located in the `strimzi-kafka-operator` repository under the `design` folder. | ||
|
|
||
| #### Strimzi Design Document Organization | ||
| Design documents should be splt into logical areas, for repositories that aren't `strimiz-kafka-operator` I suspect this would start as a single or just a few succinct documents. |
There was a problem hiding this comment.
"splt" -> "split"
"strimiz-kafka-operator" -> "strimzi-kafka-operator"
|
|
||
| ### How to write a design document | ||
|
|
||
| The design documents would live in the related repository in the Strimzi Organization and would match the current code state. Naturally it is hard to allign the design documents and the code behaviour, but it would be the respinsibility of a reviewer to identify if any of the changes are impactful enough to potentially effect the design docs. Due to the below described simplicity of the design docs, if they are found to be out of date, it should be fairly simply to raise a pull request with the behavioural changes documented. |
There was a problem hiding this comment.
"allign" -> "align"
"respinsibility" -> "responsibility
"effect" -> "affect" or "have an effect on"
| A design document is considered complete when the reviewers and maintainers believe the document to accurately reflect the implementation of the components behaviour. | ||
| Once approved the document is merged and is understood to be correct, any mistakes or changes to behaviour should be corrected in the form of a pull request alongside the code that changes the behavior. | ||
|
|
||
| A lot of implementation issues, problems and compromises are only clear during or after development of a feature or change, so a design doc is recommended to be written alongside the code development, this helps in avoiding the writing of invalid design documents and help hilight potentially problematic elements of implementation or important holes in the testing strategy. |
There was a problem hiding this comment.
"hilight" -> "highlight"
I think given that the scope of these design docs are quite high level it could be argued that it would be valuable to write them up front when creating a new component. I could imagine the document being created as a PR initially and then only merged once the component is complete. It's up to you whether you take on this suggestion, but just thought I'd share my thoughts.
|
|
||
| ## Summary of changes | ||
|
|
||
| In an effort to improve where we are, the above guidelines are suggestions for future contributors but no enforced or mandated. This means that we will not place the entire burden on the first person to come along who wants to make a change in a given area. |
There was a problem hiding this comment.
"no enforced" -> "not enforced"
It might be clearer to simplify this, it seems like if it isn't enforced then design docs will never be written. Maybe just saying "In an effort to improve where we are, the above guidelines are suggested for future contributions that are either new components or significant changes to the design or behaviour of existing components. This could result in some components only being partially documented but over time design documents for existing components can be contributed."
Then I would be tempted to get rid of the rest of this section as you are sort of repeating yourself.
* Move Service Binding proposal to Strimzi Proposals repository Signed-off-by: Jakub Scholz <[email protected]> * feat: Update Service Binding integration proposal Signed-off-by: Katherine Stanley <[email protected]> * feat: Update proposal based on feedback * Clarify steps left up to application developer in approach #1. * Add example secret for approach #2. * Add extension to approach #3 to add spec.binding.listener to KafkaUser. * Fix status.binding reference in approach #4. * Add sasl.jaas.config entry to KafkaUser example secret for completeness. Signed-off-by: Katherine Stanley <[email protected]> * feat: Update sasl.jaas.config example in secret Signed-off-by: Katherine Stanley <[email protected]> * feat: Edit example of sasl.jaas.config in secret Signed-off-by: Katherine Stanley <[email protected]> * feat: Add example KafkaConnection and secret Signed-off-by: Katherine Stanley <[email protected]> * feat: Update secret examples and rephrase considerations Signed-off-by: Katherine Stanley <[email protected]> * feat: Update proposal to highlight approach agreed Signed-off-by: Katherine Stanley <[email protected]> * feat: Add type and provider to Secret Signed-off-by: Katherine Stanley <[email protected]> * feat: Condense the connecting to Strimzi section Signed-off-by: Katherine Stanley <[email protected]> * feat: Add implementation steps Signed-off-by: Katherine Stanley <[email protected]> * feat: Update proposal based on feedback Signed-off-by: Katherine Stanley <[email protected]> * feat: Update secret keys to match Kafka client config names Signed-off-by: Katherine Stanley <[email protected]> * feat: Update listener selection to include external and not be random Signed-off-by: Katherine Stanley <[email protected]> * feat: Updates based on community call feedback * Rename CR to KafkaAccess * New operator will be standalone * Remove section around connecting to Strimzi as no longer needed for reference * Clarify that the user Kind is required to allow extension where user is specified using a secret and not the KafkaUser Kind Signed-off-by: Katherine Stanley <[email protected]> * feat: Update filename and add it to the readme Signed-off-by: Katherine Stanley <[email protected]> Co-authored-by: Jakub Scholz <[email protected]>
No description provided.