-
Notifications
You must be signed in to change notification settings - Fork 32
Expand and refactor the code-review docs #355
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
+422
−60
Merged
Changes from all commits
Commits
Show all changes
13 commits
Select commit
Hold shift + click to select a range
d6ff746
Split the current chat commands page into three pages: a reference page,
jmacdotorg c20141c
Small fixes
jmacdotorg 5599b53
Add the `summary` command. Clarify what `ignore` does.
jmacdotorg 4e55b6a
Add the pro-plan banner to the generation page.
jmacdotorg b649449
Specifcy code block style
jmacdotorg 40d6c7d
Merge branch 'main' into split-commands
jmacdotorg 4b5263e
A few rewords, on Aravind's suggestion.
jmacdotorg e30d68e
Merge branch 'split-commands' of https://github.com/coderabbitai/code…
jmacdotorg 686274a
Merge branch 'main' into split-commands
jmacdotorg ce799ab
Make changes suggested by Howon, includiing some significant clarific…
jmacdotorg 180c7ba
Merge branch 'split-commands' of https://github.com/coderabbitai/code…
jmacdotorg 6203b7b
Typo fix
jmacdotorg 7dd02e9
tweaks
jmacdotorg File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or 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,42 @@ | ||
| --- | ||
| title: Code review best practices | ||
| description: Best practices for managing CodeRabbit code reviews. | ||
| sidebar_label: Best practices | ||
| --- | ||
|
|
||
| This page lists best practices for performing code reviews with CodeRabbit. | ||
|
|
||
| For more information about working with | ||
| CodeRabbit through chat, see [Control and manage code reviews](/guides/commands). | ||
|
|
||
| For a CodeRabbit command reference, see [Code review command reference](/reference/review-commands). | ||
|
|
||
| ## Recommended code-review workflow | ||
|
|
||
| - Start with `@coderabbitai review` for checking new changes. | ||
jmacdotorg marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| - Use `@coderabbitai full review` when major changes require a fresh perspective. | ||
| - Generate summaries after significant updates using `@coderabbitai summary`. | ||
|
|
||
| ## Managing large changes | ||
|
|
||
| - Use `@coderabbitai pause` before making multiple commits. | ||
| - Resume reviews with `@coderabbitai resume` when ready. | ||
| - Consider `@coderabbitai full review` after substantial changes. | ||
|
|
||
| ## Documentation flow | ||
|
|
||
| - Run `@coderabbitai generate docstrings` after finalizing function implementations. | ||
| - Learn more about [docstring generation](/finishing-touches/docstrings). | ||
|
|
||
jmacdotorg marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| ## Overall tips | ||
|
|
||
| - Commands are case-insensitive (`@coderabbitai REVIEW` works the same as `@coderabbitai review`). | ||
| - Commands can be issued by anyone with write access to the repository. | ||
| - Multiple commands can be used in sequence as needed. | ||
| - Use `@coderabbitai configuration` to export your settings before making changes. | ||
|
|
||
jmacdotorg marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| ## Command response time | ||
|
|
||
| - Most commands (pause, resume, ignore) take effect immediately. | ||
| - Review commands typically complete within a few minutes, depending on PR size. | ||
| - Docstring generation time varies based on the number of functions. | ||
This file contains hidden or 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,89 @@ | ||
| --- | ||
| title: Review pull requests | ||
| description: An overview of CodeRabbit's core code review features. | ||
| sidebar_label: Overview | ||
| --- | ||
|
|
||
| The central feature of CodeRabbit is its ability to proactively review | ||
| new pull requests on your code repository. | ||
|
|
||
| CodeRabbit reviews take the form of pull request comments that | ||
| include summaries, analyses, and initial critiques of the proposed changes. | ||
| This information, usually added to pull requests within minutes, can help your team perform more rapid, better-informed code reviews. | ||
|
|
||
| The following sections present an overview of this feature. For a hands-on example that lets you experience a CodeRabbit code review using | ||
| a real repository, see [Quickstart](/getting-started/quickstart). | ||
|
|
||
| ## Automatically review pull requests {#review} | ||
|
|
||
| After you [integrate CodeRabbit with your repository](/platforms), CodeRabbit proceeds | ||
| to automatically review every subsequent pull request, as soon as each one is created. | ||
|
|
||
| CodeRabbit performs code reviews by attaching comments to the pull request. | ||
| These comments contain detailed summaries and analyses of the changes, | ||
| as well as listing out problems or areas for potential improvement that it found. | ||
|
|
||
| CodeRabbit uses [a variety of open-source linters and security tools](/tools) and a custom | ||
| code verification agent to provide this analysis. CodeRabbit | ||
| also consults several models to further analyze and critique the proposed changes, | ||
| using all of the content of your repository as context. The code-review comment that CodeRabbit attaches | ||
| to your pull request synthesizes and summarizes all of the information collected from these different sources. | ||
|
|
||
jmacdotorg marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| For more information about the graph analysis that CodeRabbit includes with its reviews | ||
| when available, see [CodeRabbit Code Graph Analysis](/integrations/code-graph-analysis). | ||
|
|
||
| ### Events that trigger automated reviews {#events} | ||
|
|
||
| By default, the following activity in your repository triggers CodeRabbit to | ||
| perform a code review: | ||
|
|
||
| - If CodeRabbit sees a new pull request, then it immediately performs a full review | ||
| of the proposed code changes. | ||
| - If an open pull request that CodeRabbit has already reviewed gets modified with another | ||
| commit, then CodeRabbit performs an incremental review that focuses on the new commit. | ||
|
|
||
| ## Interact with CodeRabbit reviews {#interact} | ||
|
|
||
| After CodeRabbit attaches its initial code-review comment to a pull request, you can | ||
| directly interact with CodeRabbit by mentioning its username, `@coderabbitai`, in comments | ||
| that you post to the pull request. | ||
|
|
||
| These interactions can serve several purposes: | ||
|
|
||
| - Free-form discussion about the pull request and the ongoing code review. | ||
| - Commands to have CodeRabbit perform specific actions regarding the code review. | ||
| - Prompts to have CodeRabbit generate its own improvements to the branch under review. | ||
|
|
||
| ### Chat with CodeRabbit {#chat} | ||
|
|
||
| You can have open-ended, natural-language discussion with CodeRabbit during a code review, treating it | ||
| as an LLM-powered chatbot that has your entire code repository available for context. For more information, see [CodeRabbit Chat](/guides/agent_chat). | ||
|
|
||
| ### Manage CodeRabbit review behavior {#manage} | ||
|
|
||
| CodeRabbit recognizes a variety of keyword-based commands that let you control its | ||
| behavior during a code review, including the following: | ||
|
|
||
| - Pause or resume automated reviews of the pull request. | ||
| - Manually request a review, when automated reviews are paused. | ||
| - Resolve all open comments authored by CodeRabbit. | ||
|
|
||
| For more information, see [Control and manage code reviews](/guides/commands). | ||
|
|
||
| ### Generate improvements {#generate} | ||
|
|
||
| You can command CodeRabbit to generate improvements to the branch under review. | ||
| CodeRabbit accomplishes this by publishing a new branch based on the branch under review, | ||
| and creating a new pull request for your own review. | ||
|
|
||
| Available code-generation commands let you request the following from CodeRabbit: | ||
|
|
||
| - Implement the suggestions for improvements that CodeRabbit has made in its earlier code review comments. | ||
| - Generate inline documentation for any undocumented functions that this pull request proposes to add. | ||
|
|
||
| For more information, see [Generate improvements](/guides/generate-improvements). | ||
|
|
||
| ## What's next {#whats-next} | ||
|
|
||
| - [Control and manage code reviews](/guides/commands) | ||
| - [Generate code improvements](/guides/generate-improvements) | ||
This file contains hidden or 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,17 @@ | ||
| --- | ||
| title: Code review troubleshooting | ||
| description: Troubleshooting CodeRabbit code reviews. | ||
| sidebar_label: Troubleshooting | ||
| --- | ||
|
|
||
| This page is about troubleshooting interactive code review sessions with CodeRabbit. For more information about working with | ||
| CodeRabbit through chat, see [Control and manage code reviews](/guides/commands). | ||
|
|
||
| If a CodeRabbit command doesn't seem to work: | ||
|
|
||
| 1. Check that you have the necessary repository permissions. | ||
| 2. Verify the command syntax. | ||
| 3. Look for any response from CodeRabbit in the PR comments. | ||
| 4. Use `@coderabbitai help` for command guidance. | ||
|
|
||
| Need help? Join our community on [Discord](https://discord.gg/coderabbit) or [contact our support team](/getting-started/support). |
This file contains hidden or 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 hidden or 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,102 @@ | ||
| --- | ||
| title: Generate improvements | ||
| description: Request coderabbit to generate its own code improvements during code reviews | ||
| --- | ||
|
|
||
| ```mdx-code-block | ||
| import ProPlanNotice from '@site/src/components/ProPlanNotice.mdx'; | ||
| <ProPlanNotice /> | ||
| ``` | ||
|
|
||
| This page is about using CodeRabbit to generate improvements to code under review. | ||
|
|
||
| For a general overview of performing code reviews with CodeRabbit, see [Review pull requests](/guides/code-review-overview). | ||
|
|
||
| ## Overview of CodeRabbit code generation {#overview} | ||
|
|
||
| :::note | ||
| This feature is available only on GitHub. | ||
| ::: | ||
|
|
||
| You can request CodeRabbit to generate improvements to a branch that it is currently reviewing. | ||
|
|
||
| To do this, write out your request prompt in a comment addressed to `@coderabbitai`, | ||
| such as with the following examples: | ||
|
|
||
| - `@coderabbitai Please implement the changes you suggested in your code review.` | ||
| - `@coderabbitai Add input validation with proper error messages to these new functions.` | ||
| - `@coderabbitai Break this large function into smaller, more focused methods.` | ||
|
|
||
| In addition to this kind of free-form request, you can also give CodeRabbit keyword-based | ||
| commands for common code-generation requests, as described in [Code generation commands](#commands). | ||
| This includes the `plan` keyword, which acts as shorthand for the first prompt on the | ||
| previous list. | ||
|
|
||
| After you give it a code-generation prompt or command, CodeRabbit delivers its suggested improvements by taking these steps: | ||
|
|
||
| 1. CodeRabbit posts a comment or two to the pull request, detailing its improvement plans. | ||
| 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. | ||
|
|
||
| CodeRabbit doesn't make any further changes to the new branch or to the new pull request | ||
| after it creates them. From that point on, it's fully up to you what to do with the new, suggested-change branch. | ||
|
|
||
| The best practice is to effectively take ownership of the new branch for yourself, | ||
| deciding whether it's worth merging into the original pull request branch, and making | ||
| any further updates you'd like to make first. You can use comments in the new branch | ||
| to ask CodeRabbit to explain its changes, if needed, or to otherwise converse with | ||
| CodeRabbit about the suggested improvements. | ||
|
|
||
| Because it's just an ordinary Git branch, the presence of the suggested-change branch | ||
| doesn't block the ongoing code review in the original pull request branch. You are | ||
| free to merge, defer, or close the suggested-change pull request that CodeRabbit made, using any method or timing that fits | ||
| your workflow. | ||
|
|
||
| ## Code generation commands {#commands} | ||
|
|
||
| This section lists short commands that you can give CodeRabbit to have it accomplish | ||
| common code-generation tasks. For more complex tasks, you can instead write out full | ||
| prompts, as described in the previous section. | ||
|
|
||
| For a complete CodeRabbit command reference, see [Code review command reference](/reference/review-commands). | ||
|
|
||
| ### Generate inline documentation {#docstrings} | ||
|
|
||
| To have CodeRabbit generate missing documentation for function code added by | ||
| the pull request, post the following comment to the | ||
| pull request: | ||
|
|
||
| ```text | ||
| @coderabbitai generate docstrings | ||
| ``` | ||
|
|
||
| For more information about how CodeRabbit can generate inline documentation, including | ||
| the Git platforms and programming languages that this feature supports, see | ||
| [Docstrings](/finishing-touches/docstrings). | ||
|
|
||
| ### Generate solutions to open review comments {#plan} | ||
|
|
||
| To have CodeRabbit generate and add a new repository branch with code improvements | ||
| that try to address its own code review comments, post the following comment to the | ||
| pull request: | ||
|
|
||
| ```text | ||
jmacdotorg marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| @coderabbitai plan | ||
| ``` | ||
|
|
||
| Using this keyword is essentially shorthand for writing out a prompt like the following: | ||
|
|
||
| ```text | ||
| @coderabbitai Implement the changes that you suggested and apply them to this pull request. | ||
| ``` | ||
|
|
||
| If you want to give CodeRabbit more specific implement instructions other than a general | ||
| request to implement its own suggestions, then you can write out those instructions | ||
| as a full prompt, instead of using the one-word `plan` command. | ||
|
|
||
| ## What's next {#whats-next} | ||
|
|
||
| - [Control and manage code reviews](/guides/commands) | ||
| - [Best practices](/guides/code-review-best-practices) | ||
| - [Troubleshooting](/guides/code-review-troubleshooting) | ||
This file contains hidden or 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,47 @@ | ||
| --- | ||
| title: Code review commands | ||
| description: A list of commands that you can issue to CodeRabbit during code reviews. | ||
| --- | ||
|
|
||
| This page lists the various commands that you can issue to CodeRabbit through | ||
| its chat interface during code reviews. For more information about working with | ||
| CodeRabbit through chat, see [Interact with CodeRabbit reviews](/guides/code-review-overview#interact). | ||
|
|
||
| | Command | Description | Use Case | | ||
| | --------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------- | | ||
| | `@coderabbitai review` | Triggers an incremental review of new changes | When automatic reviews are disabled or you want to manually trigger a review | | ||
| | `@coderabbitai full review` | Performs a complete review of all files from scratch | When you want to get fresh insights on the entire PR | | ||
| | `@coderabbitai summary` | Regenerates the PR summary | When you want an updated overview after making changes | | ||
|
|
||
| ## Code review flow control | ||
|
|
||
| | Command | Description | Use Case | | ||
| | ---------------------- | ---------------------------------------- | --------------------------------------------------- | | ||
| | `@coderabbitai pause` | Temporarily stops reviews on the PR | When you're making multiple rapid changes | | ||
| | `@coderabbitai resume` | Restarts reviews after a pause | When you're ready for CodeRabbit to review again | | ||
| | `@coderabbitai ignore` | Permanently disables reviews for this PR | When you want to handle the review process manually | | ||
|
|
||
| ## Comment management | ||
|
|
||
| | Command | Description | Use Case | | ||
| | ----------------------- | --------------------------------------- | ------------------------------------------------------- | | ||
| | `@coderabbitai resolve` | Resolves all CodeRabbit review comments | When you've addressed all feedback and want to clean up | | ||
|
|
||
| ## Documentation commands | ||
|
|
||
| | Command | Description | Use Case | | ||
| | ----------------------------------- | -------------------------------------------- | --------------------------------------------------- | | ||
| | `@coderabbitai generate docstrings` | Generates docstrings for functions in the PR | When you need automatic documentation for your code | | ||
| | `@coderabbitai configuration` | Shows current CodeRabbit settings | When you need to check or export your configuration | | ||
|
|
||
| ## Agentic chat commands | ||
|
|
||
| | Command | Description | Use Case | | ||
| | -------------------- | ---------------------------------------------------------- | ---------------------------------------------------- | | ||
| | `@coderabbitai plan` | Get the agentic chat to plan an edit for previous comments | When you want CodeRabbit to change your code for you | | ||
|
|
||
| ## Help and support | ||
|
|
||
| | Command | Description | Use Case | | ||
| | -------------------- | ------------------------------------------ | ------------------------------------------ | | ||
| | `@coderabbitai help` | Displays available commands and usage info | When you need guidance on using CodeRabbit | |
This file contains hidden or 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
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.