Expand and refactor the code-review docs #355
Conversation
a troubleshooting guide, and a best practices guide. Replace the chat commands page with two task-orience how-to guides, one about controlling code reviews, and one about generating improvements. Add a new overview page for the code review process.
WalkthroughSeveral new documentation guides were added and existing documentation was reorganized. New pages provide overviews, best practices, troubleshooting, and improvement-generation instructions for CodeRabbit code reviews. The chat commands documentation was split into a how-to guide and a reference page. Sidebar navigation was updated to reflect these additions. Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant CodeRabbit
participant Docs
User->>Docs: Reads code review overview and best practices
User->>CodeRabbit: Issues review/generate commands via PR comments
CodeRabbit-->>User: Responds with reviews, summaries, or improvements
User->>Docs: Consults troubleshooting guide if issues arise
User->>Docs: References command documentation and reference as needed
Assessment against linked issues
Poem
📜 Recent review detailsConfiguration used: CodeRabbit UI 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
⏰ Context from checks skipped due to timeout of 90000ms (1)
✨ Finishing Touches
🧪 Generate Unit Tests
🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (8)
docs/guides/code-review-troubleshooting.md (1)
17-17: Ensure consistent formatting and newline at end of file
Add a blank line before the call-to-action and ensure the file ends with a newline. This improves readability and avoids potential build warnings for missing trailing newlines.docs/guides/generate-improvements.md (1)
22-29: Improve list numbering and sentence variety
The two list items both start with1.and three consecutive sentences begin with "CodeRabbit." Renumber and rephrase to avoid repetition and improve clarity:- After you give it a code-generation command, CodeRabbit delivers its suggested improvements by taking these steps: - 1. CodeRabbit publishes a new branch... - 1. CodeRabbit opens a new pull request... - CodeRabbit doesn't make any further changes to the new branch... + After you give it a code-generation command, CodeRabbit delivers its suggested improvements by taking these steps: + 1. It publishes a new branch based on the pull request branch. + 2. It opens a linked pull request for the new branch. + 3. It does not modify the suggested-change branch or pull request after creation.🧰 Tools
🪛 LanguageTool
[style] ~26-~26: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ... to it from the original pull request. CodeRabbit doesn't make any further changes to the...(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~27-~27: Consider an alternative to strengthen your wording.
Context: ...l request. CodeRabbit doesn't make any further changes to the new branch or to the new pull re...(CHANGES_ADJUSTMENTS)
docs/guides/commands.md (1)
36-136: Add language identifiers to fenced code blocks
To enable proper syntax highlighting, specify a language (e.g.,bash) on each fenced code block. For example:- ``` + ```bashPlease apply this update to all code snippets on lines 36, 43, 52, 79, 86, 95, 105, 124, and 134.
🧰 Tools
🪛 LanguageTool
[misspelling] ~74-~74: Did you mean “sense”?
Context: ...s all comments that CodeRabbit has made since its most recent full review into consid...(MAKE_SINCE)
🪛 markdownlint-cli2 (0.17.2)
36-36: Fenced code blocks should have a language specified
null(MD040, fenced-code-language)
43-43: Fenced code blocks should have a language specified
null(MD040, fenced-code-language)
52-52: Fenced code blocks should have a language specified
null(MD040, fenced-code-language)
79-79: Fenced code blocks should have a language specified
null(MD040, fenced-code-language)
86-86: Fenced code blocks should have a language specified
null(MD040, fenced-code-language)
95-95: Fenced code blocks should have a language specified
null(MD040, fenced-code-language)
105-105: Fenced code blocks should have a language specified
null(MD040, fenced-code-language)
124-124: Fenced code blocks should have a language specified
null(MD040, fenced-code-language)
134-134: Fenced code blocks should have a language specified
null(MD040, fenced-code-language)
docs/guides/code-review-overview.md (5)
17-25: Refine terminology for clarity.
Consider using “multipart” as one word instead of “multi-part” to align with common usage:- CodeRabbit code review consists of a single, multi-part comment attached to the pull request. + CodeRabbit code review consists of a single, multipart comment attached to the pull request.🧰 Tools
🪛 LanguageTool
[misspelling] ~22-~22: This word is normally spelled as one.
Context: ...abbit code review consists of a single, multi-part comment attached to the pull request. T...(EN_COMPOUNDS_MULTI_PART)
26-29: Simplify phrasing for conciseness.
You can tighten the wording and remove extra occurrences of “of”:- CodeRabbit uses a variety of open-source linters and security tools to provide this analysis. + CodeRabbit uses various open-source linters and security tools to provide this analysis. ... - using all of the content of your repository as context. + using all the content of your repository as context.🧰 Tools
🪛 LanguageTool
[style] ~26-~26: Consider using a more concise synonym.
Context: ...ovement that it found. CodeRabbit uses a variety of open-source linters and security tools ...(A_VARIETY_OF)
[uncategorized] ~27-~27: Do not mix variants of the same word (‘analyze’ and ‘analyse’) within a single text.
Context: ...large language models (LLMs) to further analyze and critique the proposed changes, usin...(EN_WORD_COHERENCY)
[style] ~28-~28: Consider removing “of” to be more concise
Context: ...nd critique the proposed changes, using all of the content of your repository as context. ...(ALL_OF_THE)
[style] ~29-~29: Consider removing “of” to be more concise
Context: ...pull request synthesizes and summarizes all of the information collected from these differ...(ALL_OF_THE)
68-72: Standardize terminology.
Use “chatbot” as one word for consistency:- treating it as an LLM-powered chat bot that has your entire code repository available for context. + treating it as an LLM-powered chatbot that has your entire code repository available for context.🧰 Tools
🪛 LanguageTool
[misspelling] ~71-~71: This word is normally spelled as one.
Context: ...e review, treating it as an LLM-powered chat bot that has your entire code repository av...(EN_COMPOUNDS_CHAT_BOT)
75-80: Tighten phrasing and correct punctuation.
- Replace “a variety of” with “various” for brevity.
- Remove the comma before “when” in the manual-review bullet.
- CodeRabbit recognizes a variety of keyword-based commands that let you control its behavior... + CodeRabbit recognizes various keyword-based commands that let you control its behavior... - Manually request a review, when automated reviews are paused. + Manually request a review when automated reviews are paused.🧰 Tools
🪛 LanguageTool
[style] ~75-~75: Consider using a more concise synonym.
Context: ...havior {#manage} CodeRabbit recognizes a variety of keyword-based commands that let you con...(A_VARIETY_OF)
[typographical] ~79-~79: Usually, there’s no comma before “when”.
Context: ...ull request. - Manually request a review, when automated reviews are paused. - Resolve...(IF_NO_COMMA)
99-100: Unify link text for consistency.
Use the same phrasing “Generate improvements” used earlier:- [Generate code improvements](/guides/generate-improvements) + [Generate improvements](/guides/generate-improvements)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (7)
docs/guides/code-review-best-practices.md(1 hunks)docs/guides/code-review-overview.md(1 hunks)docs/guides/code-review-troubleshooting.md(1 hunks)docs/guides/commands.md(1 hunks)docs/guides/generate-improvements.md(1 hunks)docs/reference/review-commands.md(1 hunks)sidebars.ts(2 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/guides/generate-improvements.md
[style] ~26-~26: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ... to it from the original pull request. CodeRabbit doesn't make any further changes to the...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~27-~27: Consider an alternative to strengthen your wording.
Context: ...l request. CodeRabbit doesn't make any further changes to the new branch or to the new pull re...
(CHANGES_ADJUSTMENTS)
docs/guides/code-review-overview.md
[misspelling] ~22-~22: This word is normally spelled as one.
Context: ...abbit code review consists of a single, multi-part comment attached to the pull request. T...
(EN_COMPOUNDS_MULTI_PART)
[style] ~26-~26: Consider using a more concise synonym.
Context: ...ovement that it found. CodeRabbit uses a variety of open-source linters and security tools ...
(A_VARIETY_OF)
[uncategorized] ~27-~27: Do not mix variants of the same word (‘analyze’ and ‘analyse’) within a single text.
Context: ...large language models (LLMs) to further analyze and critique the proposed changes, usin...
(EN_WORD_COHERENCY)
[style] ~28-~28: Consider removing “of” to be more concise
Context: ...nd critique the proposed changes, using all of the content of your repository as context. ...
(ALL_OF_THE)
[style] ~29-~29: Consider removing “of” to be more concise
Context: ...pull request synthesizes and summarizes all of the information collected from these differ...
(ALL_OF_THE)
[misspelling] ~71-~71: This word is normally spelled as one.
Context: ...e review, treating it as an LLM-powered chat bot that has your entire code repository av...
(EN_COMPOUNDS_CHAT_BOT)
[style] ~75-~75: Consider using a more concise synonym.
Context: ...havior {#manage} CodeRabbit recognizes a variety of keyword-based commands that let you con...
(A_VARIETY_OF)
[typographical] ~79-~79: Usually, there’s no comma before “when”.
Context: ...ull request. - Manually request a review, when automated reviews are paused. - Resolve...
(IF_NO_COMMA)
docs/guides/commands.md
[misspelling] ~74-~74: Did you mean “sense”?
Context: ...s all comments that CodeRabbit has made since its most recent full review into consid...
(MAKE_SINCE)
docs/reference/review-commands.md
[uncategorized] ~12-~12: Use a comma before ‘or’ if it connects two independent clauses (unless they are closely connected and short).
Context: ... | When automatic reviews are disabled or you want to manually trigger a review |...
(COMMA_COMPOUND_SENTENCE)
[grammar] ~43-~43: The word ‘Help’ is a conjunction. In formal texts, use “to”.
Context: ... to change your code for you | ## Help and support | Command | Descr...
(HELP_AND_VB)
🪛 markdownlint-cli2 (0.17.2)
docs/guides/commands.md
36-36: Fenced code blocks should have a language specified
null
(MD040, fenced-code-language)
43-43: Fenced code blocks should have a language specified
null
(MD040, fenced-code-language)
52-52: Fenced code blocks should have a language specified
null
(MD040, fenced-code-language)
79-79: Fenced code blocks should have a language specified
null
(MD040, fenced-code-language)
86-86: Fenced code blocks should have a language specified
null
(MD040, fenced-code-language)
95-95: Fenced code blocks should have a language specified
null
(MD040, fenced-code-language)
105-105: Fenced code blocks should have a language specified
null
(MD040, fenced-code-language)
124-124: Fenced code blocks should have a language specified
null
(MD040, fenced-code-language)
134-134: Fenced code blocks should have a language specified
null
(MD040, fenced-code-language)
⏰ Context from checks skipped due to timeout of 90000ms (1)
- GitHub Check: Cloudflare Pages
🔇 Additional comments (18)
sidebars.ts (2)
87-91: Review pull requests category items added
The new guides—code-review-overview,generate-improvements,code-review-best-practices, andcode-review-troubleshooting—are correctly ordered under "Review pull requests," improving discoverability in the sidebar.
147-147: Reference section updated with review commands
Thereference/review-commandsentry has been added to the "Reference" category, aligning with the new documentation structure.docs/reference/review-commands.md (2)
1-4: Frontmatter and introduction are clear
The page title, description, and introductory context effectively convey the purpose of this command reference.
8-9:✅ Verification successful
Verify the cross-link anchor
Ensure that the[Interact with CodeRabbit reviews](/guides/code-review-overview#interact)link points to a valid anchor in the overview guide. Run the following to confirm:If no matches are returned, adjust the link or add the corresponding anchor in the overview page.
🏁 Script executed:
#!/bin/bash rg -R "#.*interact" docs/guides/code-review-overview.mdLength of output: 462
Let’s retry locating the “interact” anchor in the overview guide:
🏁 Script executed:
#!/bin/bash # Look for a heading that would generate the “#interact” anchor rg -n '^#{1,6}.*Interact with CodeRabbit reviews' docs/guides/code-review-overview.md # Also check for an explicit HTML anchor rg -n 'name="interact"' docs/guides/code-review-overview.mdLength of output: 200
Confirmed: “#interact” anchor exists
The heading in
docs/guides/code-review-overview.mdat line 56 already defines{#interact}, so the link/guides/code-review-overview#interactis valid.
- docs/guides/code-review-overview.md:56 →
## Interact with CodeRabbit reviews {#interact}No changes required.
docs/guides/commands.md (1)
73-75: Ignore false-positive spelling suggestion
The static analysis suggestion to replace “consideration” with “sense” is incorrect. The phrase “…into consideration” is appropriate here.🧰 Tools
🪛 LanguageTool
[misspelling] ~74-~74: Did you mean “sense”?
Context: ...s all comments that CodeRabbit has made since its most recent full review into consid...(MAKE_SINCE)
docs/guides/code-review-overview.md (6)
1-6: Frontmatter configuration is correct.
The YAML header properly definestitle,description, andsidebar_label.
7-15: Introduction is clear and concise.
This section effectively summarizes CodeRabbit’s proactive review capabilities and provides a Quickstart link for hands-on experience.
39-47: Events list formatting is clear.
The bullet points accurately capture the automatic review triggers.
48-55: Example links are descriptive and relevant.
The sample pull requests demonstrate both full and incremental automated review scenarios effectively.
56-63: Interaction instructions are well-presented.
Clear guidance on mentioning@coderabbitaifor free-form discussion and commands.
84-95: Generation commands are explained clearly.
The section on creating new branches and available generation commands is helpful and well-structured.docs/guides/code-review-best-practices.md (7)
1-5: Frontmatter configuration is correct.
The YAML header properly definestitle,description, andsidebar_label.
7-13: Overview links are relevant.
Clear pointers to managing reviews and the command reference enhance discoverability.
14-19: Recommended workflow is concise and actionable.
The listed commands (review,full review,summary) cover key review stages.
20-25: Large-change management guidance is clear.
Pause/resume and full-review recommendations are well-organized for handling substantial commits.
26-30: Documentation flow instructions are helpful.
Docstring generation steps and the link to deeper guidance are correctly referenced.
31-37: Overall tips provide valuable reminders.
Notes on case-insensitivity, permission requirements, and configuration export are spot-on.
38-42: Response time section is accurate.
Timings for pause/resume, review completion, and docstring generation are clearly stated.
Deploying coderabbit-docs with
|
| Latest commit: |
40d6c7d
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://daf2f3f8.coderabbit-docs.pages.dev |
| Branch Preview URL: | https://split-commands.coderabbit-docs.pages.dev |
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (3)
docs/guides/generate-improvements.md (2)
13-14: Simplify repetitive phrasing
The phrase “its own review comments” and “its own code improvements” can be streamlined for readability. Consider revising to:During a code review, you can ask CodeRabbit to address review comments by generating corresponding code improvements on separate branches.
23-28: Improve list item wording to reduce repetition
Lines 25–26 repeat “CodeRabbit” at the start of consecutive sentences. Consider varying the phrasing and numbering for clarity:- 1. CodeRabbit publishes a new branch, based on the open pull request's branch, to the remote repository. - 1. CodeRabbit opens a new pull request based on this new branch, and links to it from the original pull request. + 1. Publish a new branch on the remote repository, based on the open pull request's branch. + 2. Open a pull request for that branch and link it from the original pull request.🧰 Tools
🪛 LanguageTool
[style] ~26-~26: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ... to it from the original pull request. CodeRabbit doesn't make any further changes to the...(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~27-~27: Consider an alternative to strengthen your wording.
Context: ...l request. CodeRabbit doesn't make any further changes to the new branch or to the new pull re...(CHANGES_ADJUSTMENTS)
docs/guides/commands.md (1)
101-104: Remove stray label before code block
Line 103 includes an extraneous “pull request:” label. It should be removed to avoid confusion:- post the following comment: - pull request: + post the following comment:
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
docs/guides/commands.md(1 hunks)docs/guides/generate-improvements.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/guides/commands.md
[misspelling] ~74-~74: Did you mean “sense”?
Context: ...s all comments that CodeRabbit has made since its most recent full review into consid...
(MAKE_SINCE)
docs/guides/generate-improvements.md
[style] ~26-~26: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ... to it from the original pull request. CodeRabbit doesn't make any further changes to the...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~27-~27: Consider an alternative to strengthen your wording.
Context: ...l request. CodeRabbit doesn't make any further changes to the new branch or to the new pull re...
(CHANGES_ADJUSTMENTS)
⏰ Context from checks skipped due to timeout of 90000ms (2)
- GitHub Check: test
- GitHub Check: Cloudflare Pages
🔇 Additional comments (9)
docs/guides/generate-improvements.md (3)
1-4: Front matter is well-formed
The title, description, and front-matter delimiters are correct and self-explanatory.
7-10: MDX notice component usage is correct
TheProPlanNoticecomponent is imported and rendered properly within an MDX code block.
45-58: Linking and references are clear
The pointers to the command reference and Docstrings guide are accurate and contextually helpful.docs/guides/commands.md (6)
6-7: Introduction is concise
The page clearly states its purpose and links to an overview guide.
9-11: Sentence break formatting is acceptable
Breaking the sentence across lines in Markdown will reflow correctly; no changes needed.
27-38: Pause/resume command examples are clear
The code blocks for@coderabbitai pauseand@coderabbitai resumeare accurately presented with proper context.
47-63: Disable automatic reviews workflow is well-documented
The instructions to ignore and re-enable automatic reviews are complete and user-friendly.
71-74: LanguageTool false positive
The use of “since” in “comments that CodeRabbit has made since its most recent full review” is correct. This can be safely ignored.🧰 Tools
🪛 LanguageTool
[misspelling] ~74-~74: Did you mean “sense”?
Context: ...s all comments that CodeRabbit has made since its most recent full review into consid...(MAKE_SINCE)
139-142: What's next links are accurate
The next-step links correctly point to related guides, ensuring a smooth navigation flow.
| @@ -0,0 +1,42 @@ | |||
| --- | |||
There was a problem hiding this comment.
Sahil is gonna share another best practice guide soon.
| sidebar_label: Overview | ||
| --- | ||
|
|
||
| One of the core features of CodeRabbit is its ability to proactively review |
There was a problem hiding this comment.
I'd say - that is the core feature of the CodeRabbit. We are an AI Code Reviewer.
| The comment contains a detailed summary and analysis of the changes, | ||
| as well as a listing of problems or areas for potential improvement that it found. | ||
|
|
||
| CodeRabbit uses a variety of open-source linters and security tools to provide this analysis. CodeRabbit |
There was a problem hiding this comment.
CodeRabbit uses a variety of open-source linters and security tools to provide this analysis.
CodeRabbit uses a variety of open-source linters and security tools which we call as tools to provide this analysis.
| as well as a listing of problems or areas for potential improvement that it found. | ||
|
|
||
| CodeRabbit uses a variety of open-source linters and security tools to provide this analysis. CodeRabbit | ||
| also consults a number of large language models (LLMs) to further analyze and critique the proposed changes, |
There was a problem hiding this comment.
consults a number of large language models
uses a ensemble of models
Split the current chat commands page into three pages: a reference page,
a troubleshooting guide, and a best practices guide.
Replace the chat commands page with two task-oriented how-to guides:
one about controlling code reviews, and one about generating improvements.
Add a new overview page for the code review process.
Staged:
Fixes #302 Fixes #312