Add a new setup-and-configuration best practices guide. #385
Conversation
…tices pages into their own top-level ToC section.
WalkthroughA new documentation guide on setup and configuration best practices was added. The sidebar structure was updated to introduce a "Best practices" category containing both setup and code review best practices guides. Additionally, the sidebar label for the code review best practices document was updated for consistency. Changes
Assessment against linked issues
Poem
✨ 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 (6)
docs/guides/setup-best-practices.md (6)
3-3: Fix typo in front-matter description.“seting up CodeRabbit” → “setting up CodeRabbit”
-description: Best practices for seting up CodeRabbit. +description: Best practices for setting up CodeRabbit.
79-79: Add missing article for clarity.Change “loads the file along with rest of your repository” to include “the rest”.
- During code reviews, CodeRabbit loads the file along with rest of your repository. + During code reviews, CodeRabbit loads the file along with the rest of your repository.🧰 Tools
🪛 LanguageTool
[uncategorized] ~79-~79: Possible missing article found.
Context: ...s, CodeRabbit loads the file along with rest of your repository. This means that you...(AI_HYDRA_LEO_MISSING_THE)
80-80: Refine contributor phrasing.Simplify “makes the repository's CodeRabbit settings transparent to all of the repository's contributors” for readability.
- - The file makes the repository's CodeRabbit settings transparent to all of the repository's contributors. + - The file makes the repository's CodeRabbit settings transparent to all contributors.🧰 Tools
🪛 LanguageTool
[style] ~80-~80: Consider removing “of” to be more concise
Context: ...ry's CodeRabbit settings transparent to all of the repository's contributors. Repository-...(ALL_OF_THE)
83-83: Correct spelling error.“defned” → “defined”.
- Repository-level settings defined by a `coderabbit.yaml` take precedence over the same settings defned for that same repository in the Dashboard. + Repository-level settings defined by a `coderabbit.yaml` take precedence over the same settings defined for that repository in the Dashboard.
85-85: Ensure link consistency.Use a leading slash in the relative link to match other internal references.
- [Add a configuration file](getting-started/configure-coderabbit/) + [Add a configuration file](/getting-started/configure-coderabbit/)
93-93: Remove redundant “of” for conciseness.Simplify “use all of the open-source linters” → “use all the open-source linters”.
- By default, CodeRabbit is allowed to use all of the [open-source linters and analyzer tools](/tools)… + By default, CodeRabbit is allowed to use all the [open-source linters and analyzer tools](/tools)…🧰 Tools
🪛 LanguageTool
[style] ~93-~93: Consider removing “of” to be more concise
Context: ...y default, CodeRabbit is allowed to use all of the [open-source linters and analyzer too...(ALL_OF_THE)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
docs/guides/code-review-best-practices.md(1 hunks)docs/guides/setup-best-practices.md(1 hunks)sidebars.ts(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/guides/setup-best-practices.md
[uncategorized] ~79-~79: Possible missing article found.
Context: ...s, CodeRabbit loads the file along with rest of your repository. This means that you...
(AI_HYDRA_LEO_MISSING_THE)
[style] ~80-~80: Consider removing “of” to be more concise
Context: ...ry's CodeRabbit settings transparent to all of the repository's contributors. Repository-...
(ALL_OF_THE)
[style] ~93-~93: Consider removing “of” to be more concise
Context: ...y default, CodeRabbit is allowed to use all of the [open-source linters and analyzer too...
(ALL_OF_THE)
⏰ Context from checks skipped due to timeout of 90000ms (1)
- GitHub Check: test
🔇 Additional comments (2)
docs/guides/code-review-best-practices.md (1)
4-4: Label update is accurate.The sidebar_label change from “Best practices” to “Code reviews” correctly aligns with the new sidebar structure.
sidebars.ts (1)
137-145: Sidebar category placement looks good.The new “Best practices” category is correctly inserted and collapsed by default, containing both setup and code-review guides.
Deploying coderabbit-docs with
|
| Latest commit: |
c221bcc
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://aa8979d2.coderabbit-docs.pages.dev |
| Branch Preview URL: | https://best-practices.coderabbit-docs.pages.dev |
There was a problem hiding this comment.
Caution
Inline review comments failed to post. This is likely due to GitHub's limits when posting large numbers of comments. If you are seeing this consistently it is likely a permissions issue. Please check "Moderation" -> "Code review limits" under your organization settings.
Actionable comments posted: 1
🧹 Nitpick comments (5)
docs/guides/setup-best-practices.md (5)
1-5: Fix typo in frontmatter description and expand scope
Thedescriptionfield has a misspelling (“seting”) and could more accurately reflect both setup and configuration.
Apply this diff:--- a/docs/guides/setup-best-practices.md +++ b/docs/guides/setup-best-practices.md @@ line 3 -description: Best practices for seting up CodeRabbit. +description: Best practices for setting up and configuring CodeRabbit.
21-21: Ensure consistent branding for service account name
The bot account is referred to asCoderabbitAI, but the product name is “CodeRabbit”.--- a/docs/guides/setup-best-practices.md +++ b/docs/guides/setup-best-practices.md @@ line 21 -If you use GitHub, then CodeRabbit sets up a service account named `CoderabbitAI` for you … +If you use GitHub, then CodeRabbit sets up a service account named `CodeRabbitAI` for you …
80-80: Add missing article for clarity
The phrase “along with rest of your repository” needs the definite article “the.”--- a/docs/guides/setup-best-practices.md +++ b/docs/guides/setup-best-practices.md @@ line 80 -During code reviews, CodeRabbit loads the file along with rest of your repository. +During code reviews, CodeRabbit loads the file along with the rest of your repository.🧰 Tools
🪛 LanguageTool
[style] ~80-~80: Consider removing “of” to be more concise
Context: ...ry's CodeRabbit settings transparent to all of the repository's contributors. Repository-...(ALL_OF_THE)
82-82: Streamline phrasing by removing redundant “of”
The sentence can be tightened by dropping “of.”--- a/docs/guides/setup-best-practices.md +++ b/docs/guides/setup-best-practices.md @@ line 82 -The file makes the repository's CodeRabbit settings transparent to all of the repository's contributors. +The file makes the repository's CodeRabbit settings transparent to all the repository's contributors.
93-93: Simplify phrasing in tools description
Remove the extra “of” for conciseness.--- a/docs/guides/setup-best-practices.md +++ b/docs/guides/setup-best-practices.md @@ line 93 -**Tools**: By default, CodeRabbit is allowed to use all of the [open-source linters and analyzer tools](/tools) that are available to it during code reviews. +**Tools**: By default, CodeRabbit is allowed to use all the [open-source linters and analyzer tools](/tools) that are available to it during code reviews.🧰 Tools
🪛 LanguageTool
[style] ~93-~93: Consider removing “of” to be more concise
Context: ...y default, CodeRabbit is allowed to use all of the [open-source linters and analyzer too...(ALL_OF_THE)
🛑 Comments failed to post (1)
docs/guides/setup-best-practices.md (1)
83-83: 🛠️ Refactor suggestion
Correct spelling of ‘defined’ and refine phrasing
There’s a typo (“defned”) and a redundant “same” -> streamline the sentence.--- a/docs/guides/setup-best-practices.md +++ b/docs/guides/setup-best-practices.md @@ line 83 -Repository-level settings defined by a `coderabbit.yaml` take precedence over the same settings defned for that same repository in the Dashboard. +Repository-level settings defined by a `coderabbit.yaml` take precedence over the settings defined for that repository in the Dashboard.📝 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.Repository-level settings defined by a `coderabbit.yaml` take precedence over the settings defined for that repository in the Dashboard.🤖 Prompt for AI Agents
In docs/guides/setup-best-practices.md at line 83, correct the typo "defned" to "defined" and remove the redundant word "same" to improve clarity and streamline the sentence.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (7)
docs/guides/setup-best-practices.md (7)
3-3: Fix typo in frontmatter description
The word “seting” is missing a “t.”
Apply this diff:- description: Best practices for seting up CodeRabbit. + description: Best practices for setting up CodeRabbit.
79-79: Add missing article “the”
Improve clarity by including “the”:- During code reviews, CodeRabbit loads the file along with rest of your repository. + During code reviews, CodeRabbit loads the file along with the rest of your repository.🧰 Tools
🪛 LanguageTool
[uncategorized] ~79-~79: You might be missing the article “the” here.
Context: ...s, CodeRabbit loads the file along with rest of your repository. This means that you...(AI_EN_LECTOR_MISSING_DETERMINER_THE)
80-80: Reduce redundancy: remove “of”
The phrase “all of the repository’s contributors” can be more concise:- The file makes the repository's CodeRabbit settings transparent to all of the repository's contributors. + The file makes the repository's CodeRabbit settings transparent to all the repository's contributors.🧰 Tools
🪛 LanguageTool
[style] ~80-~80: Consider removing “of” to be more concise
Context: ...ry's CodeRabbit settings transparent to all of the repository's contributors. Repository-...(ALL_OF_THE)
83-83: Fix typo in “defined”
Correct the misspelled word “defned.”- settings defned for that same repository in the Dashboard. + settings defined for that same repository in the Dashboard.
92-92: Fix typo in “repository’s”
Correct the misspelled “reposistory’s.”- to disregard everything in your reposistory's top-level `dist` directory when + to disregard everything in your repository's top-level `dist` directory when
107-107: Clean up phrasing: remove “of”
The list item can be slightly more concise:- **Tools**: By default, CodeRabbit is allowed to use all of the [open-source linters and analyzer + **Tools**: By default, CodeRabbit is allowed to use all the [open-source linters and analyzer🧰 Tools
🪛 LanguageTool
[style] ~107-~107: Consider removing “of” to be more concise
Context: ...y default, CodeRabbit is allowed to use all of the [open-source linters and analyzer too...(ALL_OF_THE)
129-129: Remove unnecessary horizontal rule
The trailing---serves no sectioning purpose and can be dropped:- ---
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/guides/setup-best-practices.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/guides/setup-best-practices.md
[uncategorized] ~79-~79: You might be missing the article “the” here.
Context: ...s, CodeRabbit loads the file along with rest of your repository. This means that you...
(AI_EN_LECTOR_MISSING_DETERMINER_THE)
[style] ~80-~80: Consider removing “of” to be more concise
Context: ...ry's CodeRabbit settings transparent to all of the repository's contributors. Repository-...
(ALL_OF_THE)
[style] ~96-~96: Consider using a different verb to strengthen your wording.
Context: ...e when preparing a code review can help make its code reviews faster. You can define path filters using the...
(MAKE_XXX_FASTER)
[style] ~107-~107: Consider removing “of” to be more concise
Context: ...y default, CodeRabbit is allowed to use all of the [open-source linters and analyzer too...
(ALL_OF_THE)
⏰ Context from checks skipped due to timeout of 90000ms (2)
- GitHub Check: test
- GitHub Check: Cloudflare Pages
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (10)
docs/guides/setup-best-practices.md (10)
3-3: Fix typo in the frontmatter description
The word “seting” is missing a “t.” It should read “setting up CodeRabbit.”
4-4: Consider clarifying the sidebar label
Thesidebar_labelis “Setup and configuration,” but the title includes “best practices.” For consistency, you might rename it to “Setup and configuration best practices.”
21-21: Correct product and platform casing
“Gitlab” should be “GitLab,” and the service-account nameCoderabbitAIshould match your branding (e.g.CodeRabbitAI).
56-57: Normalize link trailing slash
Other internal guides use a trailing slash (e.g.,/platforms/). Consider updating[Generate reports](/guides/reports-overview)to[Generate reports](/guides/reports-overview/)for consistency.
79-79: Add missing article
In “loads the file along with rest of your repository,” insert “the” before “rest.”🧰 Tools
🪛 LanguageTool
[uncategorized] ~79-~79: You might be missing the article “the” here.
Context: ...s, CodeRabbit loads the file along with rest of your repository. This means that you...(AI_EN_LECTOR_MISSING_DETERMINER_THE)
80-80: Streamline phrasing
Remove “of” in “transparent to all of the repository’s contributors” – e.g., “transparent to all the repository’s contributors” or simply “transparent to the repository’s contributors.”🧰 Tools
🪛 LanguageTool
[style] ~80-~80: Consider removing “of” to be more concise
Context: ...ry's CodeRabbit settings transparent to all of the repository's contributors. Repository-...(ALL_OF_THE)
92-92: Fix typo in repository spelling
“reposistory’s” should be “repository’s.”
96-96: Strengthen wording for speed
Instead of “help make its code reviews faster,” consider “help accelerate code reviews” or “improve review performance.”🧰 Tools
🪛 LanguageTool
[style] ~96-~96: Consider using a different verb to strengthen your wording.
Context: ...e when preparing a code review can help make its code reviews faster. You can define path filters using the...(MAKE_XXX_FASTER)
106-107: Remove unnecessary “of”
In “allowed to use all of the open-source linters and analyzer tools,” drop “of”: “allowed to use all the open-source linters and analyzer tools.”🧰 Tools
🪛 LanguageTool
[style] ~107-~107: Consider removing “of” to be more concise
Context: ...y default, CodeRabbit is allowed to use all of the [open-source linters and analyzer too...(ALL_OF_THE)
128-128: Remove stray horizontal rule marker
The---at line 128 may be confused with frontmatter. If it’s not a section separator, please remove it.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/guides/setup-best-practices.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/guides/setup-best-practices.md
[uncategorized] ~79-~79: You might be missing the article “the” here.
Context: ...s, CodeRabbit loads the file along with rest of your repository. This means that you...
(AI_EN_LECTOR_MISSING_DETERMINER_THE)
[style] ~80-~80: Consider removing “of” to be more concise
Context: ...ry's CodeRabbit settings transparent to all of the repository's contributors. Repository-...
(ALL_OF_THE)
[style] ~96-~96: Consider using a different verb to strengthen your wording.
Context: ...e when preparing a code review can help make its code reviews faster. You can define path filters using the...
(MAKE_XXX_FASTER)
[style] ~107-~107: Consider removing “of” to be more concise
Context: ...y default, CodeRabbit is allowed to use all of the [open-source linters and analyzer too...
(ALL_OF_THE)
⏰ Context from checks skipped due to timeout of 90000ms (2)
- GitHub Check: test
- GitHub Check: Cloudflare Pages
🔇 Additional comments (1)
docs/guides/setup-best-practices.md (1)
125-126: Verify example PR link
The link points toff14-advanced-market-search/temp-fe. Please confirm this is the intended CodeRabbit example or update it to a representative CodeRabbit repo.
| The graphical UI of the Repositories page lets you set up your per-repository | ||
| preferences more rapidly, and can help you get familiar with CodeRabbit configuration options. | ||
|
|
||
| Once you are ready to fine-tune the ways that CodeRabbit works with your repositories, |
There was a problem hiding this comment.
I didn't follow this line. What is it trying to tell the user?
| we recommend adding a `coderabbit.yaml` file to each one. This file has several | ||
| advantages over using only the Dashboard: | ||
|
|
||
| - It applies version control to your repository's CodeRabbit settings. |
There was a problem hiding this comment.
Can we also specify what this means to the user? Something along the lines of "…VC to repo's CR settings enabling you to view and revert to previous settings"?
| - During code reviews, CodeRabbit loads the file along with rest of your repository. This means that you can include setting changes as part of a pull request, and CodeRabbit both analyzes and applies these settings during its review. | ||
| - The file makes the repository's CodeRabbit settings transparent to all of the repository's contributors. | ||
|
|
||
| Repository-level settings defined by a `coderabbit.yaml` take precedence over the |
There was a problem hiding this comment.
Also include how org-level settings come into play here
| when preparing a code review can help make its code reviews faster. | ||
|
|
||
| You can define path filters using the CodeRabbit | ||
| web interface, or with [a configuration file](/getting-started/configure-coderabbit/). |
There was a problem hiding this comment.
Be consistent between the use of graphical UI or CR web interface and also a config file or coderabbit.yaml file
|
@coderabbitai Can you address the unresolved comments from @SahanaVP attached to this pull request? |
|
Tip For best results, initiate chat on the files or code changes. 🧩 Analysis chain🏁 Script executed: Length of output: 1605 🏁 Script executed: Length of output: 22672 @jmacdotorg I found 5 unresolved comments from @SahanaVP on the Comment 1 (Line 71): SahanaVP asked about organization vs per-repository level setup. I see you already responded that organization-level configuration belongs in general configuration docs. Comment 2 (Line 74): SahanaVP found a line unclear: "Once you are ready to fine-tune the ways that CodeRabbit works with your repositories." This could be clearer by explaining what "fine-tune" means in this context. Comment 3 (Line 78): SahanaVP requested expanding on the version control benefits with something like "enabling you to view and revert to previous settings." Comment 4 (Line 82): SahanaVP asked to include how organization-level settings come into play with repository-level settings precedence. Comment 5 (Line 99): SahanaVP noted inconsistent terminology between "graphical UI"/"CodeRabbit web interface" and "config file"/"coderabbit.yaml file." Would you like me to provide specific text suggestions to address these comments, or would you prefer to handle these revisions yourself? 🏁 Script executed: Length of output: 6868 @jmacdotorg Now that I've read the full file, I can provide specific suggestions to address each of @SahanaVP's comments: Specific Text Suggestions:Comment 2 (Line 74) - Unclear "fine-tune" language: Suggested: "Once you are ready to customize specific aspects of how CodeRabbit reviews your code (such as review focus, language preferences, or custom instructions)," Comment 3 (Line 78) - Expand version control benefits: Suggested: "- It applies version control to your repository's CodeRabbit settings, enabling you to track changes, view setting history, and revert to previous configurations as needed." Comment 4 (Line 82) - Include organization-level settings precedence: Suggested: "Repository-level settings defined by a Comment 5 (Line 99) - Consistent terminology:
Also, there's a typo on line 91: "reposistory's" should be "repository's" Would you like me to create a follow-up issue to track these documentation improvements, or would you prefer to address them directly in this PR? |
|
@coderabbitai Could you create a new follow-up PR based on your own suggestions, instead? |
|
Tip For best results, initiate chat on the files or code changes. A summary of the edits CodeRabbit can apply:
A plan of each step that CodeRabbit will take in order to execute the edits for each file (with inline rough draft snippets): 📄 docs/guides/setup-best-practices.mdLocate line 74 and replace the sentence starting with "Once you are ready to fine-tune the ways that CodeRabbit works with your repositories," with: Locate the bullet on line 78 that reads: Locate line 82 that reads: Search the entire document for "graphical UI" and replace each occurrence with "CodeRabbit web interface". Search the entire document for the phrases "config file" and "configuration file" (case-insensitive) and replace each occurrence with " Search for the typo "reposistory's" and replace it with "repository's". Review the updated document to ensure all replacements are applied correctly, commit the changes to a new branch, and open a follow-up pull request titled "docs: address unresolved comments on setup-best-practices.md (Fixes #383)".
|
This also creates a new "Best practices" section of the docs, and moves the existing code review best practices page into it.
There is more best-practices work to do after this, based on a document by @smb06. This work covers all of the recommendations specific to CodeRabbit setup and configuration, and sets the stage for further best-practice documentation.
Staged: https://best-practices.coderabbit-docs.pages.dev/guides/setup-best-practices
Fixes #383