Conversation
Additionally, create folder for v0.6.0 design docs Signed-off-by: Anik Bhattacharjee <anbhatta@redhat.com>
WalkthroughA new Markdown design document template is introduced at Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~5 minutes 🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
design-docs/design-template.md (1)
12-22: Consider using blockquotes instead of unlabeled code blocks for instructional text.The template uses fenced code blocks without language specifications for instructional text. While this works, blockquotes (
>prefix) would be more semantic for guidance text and would satisfy markdown linting rules.📚 Example refactor for Problem Statement section
## Problem Statement -``` -Clearly and succinctly write the problem statement. What problem is this design proposing to -solve and who is the intended audience / recipient of the benefit of the solution. +> Clearly and succinctly write the problem statement. What problem is this design proposing to +> solve and who is the intended audience / recipient of the benefit of the solution. +> +> Describe WHY we need this. Briefly describe the need for this proposed feature to be +> built and work be done for it. +> +> This section focuses on the importance of an idea rather than on whether it is interesting. An +> interesting idea is good, but not good enough. This method operates in terms of whether the +> idea to be developed is sufficiently important. -Describe WHY we need this. Briefly describe the need for this proposed feature to be -built and work be done for it. - -This section focuses on the importance of an idea rather than on whether it is interesting. An -interesting idea is good, but not good enough. This method operates in terms of whether the -idea to be developed is sufficiently important. -```Apply the same pattern to the other instructional blocks throughout the template.
Also applies to: 27-34, 43-48, 55-64, 70-75, 81-85, 91-93, 99-102
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@design-docs/design-template.md` around lines 12 - 22, Replace instructional fenced code blocks in design-template.md with markdown blockquotes: locate the "Problem Statement" section and every other instructional block (the ranges noted: lines roughly 27-34, 43-48, 55-64, 70-75, 81-85, 91-93, 99-102) and convert the triple-backtick blocks into lines prefixed with "> " so guidance becomes semantic blockquotes; ensure each paragraph of instructions is prefixed with "> ", remove the surrounding code fences, and keep the original instruction text intact and line breaks preserved so linting and readability improve across the template.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@design-docs/design-template.md`:
- Line 92: Replace the misspelled word "explicity" with the correct spelling
"explicitly" in the guidance string "What are you not attempting to do? What is
this proposal not about? What is explicity out-of-scope?" so the sentence reads
"...What is explicitly out-of-scope?"; locate that exact text in
design-template.md and update the token.
- Around line 34-35: Add a blank line between the closing code fence (the ```
line) and the table header "| Stakeholder | How are they impacted |" in
design-template.md so the Markdown table is rendered correctly; locate the
closing ``` immediately above that table and insert a single empty line before
the table row.
---
Nitpick comments:
In `@design-docs/design-template.md`:
- Around line 12-22: Replace instructional fenced code blocks in
design-template.md with markdown blockquotes: locate the "Problem Statement"
section and every other instructional block (the ranges noted: lines roughly
27-34, 43-48, 55-64, 70-75, 81-85, 91-93, 99-102) and convert the
triple-backtick blocks into lines prefixed with "> " so guidance becomes
semantic blockquotes; ensure each paragraph of instructions is prefixed with ">
", remove the surrounding code fences, and keep the original instruction text
intact and line breaks preserved so linting and readability improve across the
template.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 0d3d339e-2638-46d1-bb58-4c4cf419d4e9
📒 Files selected for processing (1)
design-docs/design-template.md
| ``` | ||
| | Stakeholder | How are they impacted | |
There was a problem hiding this comment.
Add blank line before the table.
The table should be surrounded by blank lines for proper Markdown rendering. Add a blank line between the closing code fence and the table.
📝 Proposed fix
| Stakeholder | How are they impacted |
</details>
<!-- suggestion_start -->
<details>
<summary>📝 Committable suggestion</summary>
> ‼️ **IMPORTANT**
> Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
```suggestion
🧰 Tools
🪛 markdownlint-cli2 (0.21.0)
[warning] 35-35: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@design-docs/design-template.md` around lines 34 - 35, Add a blank line
between the closing code fence (the ``` line) and the table header "|
Stakeholder | How are they impacted |" in design-template.md so the Markdown
table is rendered correctly; locate the closing ``` immediately above that table
and insert a single empty line before the table row.
| ## Non-goals | ||
|
|
||
| ``` | ||
| What are you not attempting to do? What is this proposal not about? What is explicity out-of-scope? |
There was a problem hiding this comment.
Fix typo: "explicity" → "explicitly".
There's a spelling error in the guidance text.
✏️ Proposed fix
-What are you not attempting to do? What is this proposal not about? What is explicity out-of-scope?
+What are you not attempting to do? What is this proposal not about? What is explicitly out-of-scope? 📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| What are you not attempting to do? What is this proposal not about? What is explicity out-of-scope? | |
| What are you not attempting to do? What is this proposal not about? What is explicitly out-of-scope? |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@design-docs/design-template.md` at line 92, Replace the misspelled word
"explicity" with the correct spelling "explicitly" in the guidance string "What
are you not attempting to do? What is this proposal not about? What is explicity
out-of-scope?" so the sentence reads "...What is explicitly out-of-scope?";
locate that exact text in design-template.md and update the token.
tisnik
left a comment
tisnik
left a comment
There was a problem hiding this comment.
It seems to be very different from the document template we got from Ansible (ALIA). Why we won't use their template? @max-svistunov ?
I am fine using whatever template the team wants. I am not really married to one template over the other. I just don't see any other template being put out for the team, so this is an effort to bring us all to the table and agree on a template. This PR is for feedback. We can iterate through different sections if you have feedback on them. @max-svistunov feel free to open another PR with a different template if you have, and if that looks better than what I have here I'm happy to close this PR. |
|
Closing in favor of #1399 |
2 participants
Description
Add Design Doc template.
Additionally, create folder for v0.6.0 design docs
Type of change
Tools used to create PR
Identify any AI code assistants used in this PR (for transparency and review context)
Related Tickets & Documents
Checklist before requesting a review
Testing
Summary by CodeRabbit