diff --git a/docs/guides/code-review-best-practices.md b/docs/guides/code-review-best-practices.md new file mode 100644 index 00000000..83bd8abb --- /dev/null +++ b/docs/guides/code-review-best-practices.md @@ -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. +- 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). + +## 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. + +## 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. diff --git a/docs/guides/code-review-overview.md b/docs/guides/code-review-overview.md new file mode 100644 index 00000000..9c4548a4 --- /dev/null +++ b/docs/guides/code-review-overview.md @@ -0,0 +1,96 @@ +--- +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. + +A CodeRabbit code review consists of a single, multi-part comment attached to the pull request. +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](/tools) to provide this analysis. CodeRabbit +also consults an ensemble of 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. + +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. + +### Example code reviews {#examples} + +The following real pull requests, hosted on GitHub, demonstrate some example CodeRabbit +review comments. + +- [A modest refactoring of Markdown-based documentation source](https://github.com/coderabbitai/coderabbit-docs/pull/325), demonstrating a CodeRabbit graph analysis. +- [A large change that added many files](https://github.com/tyaga001/devtoolsacademy/pull/44), demonstrating incremental automated reviews of subsequent commits. + +## 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 chat bot 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) diff --git a/docs/guides/code-review-troubleshooting.md b/docs/guides/code-review-troubleshooting.md new file mode 100644 index 00000000..72539453 --- /dev/null +++ b/docs/guides/code-review-troubleshooting.md @@ -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). diff --git a/docs/guides/commands.md b/docs/guides/commands.md index f7cbe002..98946bd2 100644 --- a/docs/guides/commands.md +++ b/docs/guides/commands.md @@ -3,92 +3,140 @@ title: Control and manage code reviews description: Learn how to control CodeRabbit using commands in pull request comments --- -# CodeRabbit Commands +This page is about issuing direct commands to CodeRabbit during code reviews. +For a general overview of performing code reviews with CodeRabbit, see [Review pull requests](/guides/code-review-overview). -> Control your code reviews directly from pull request comments using CodeRabbit's command system. Each command starts with `@coderabbitai` followed by the specific action you want to take. +You can control CodeRabbit's behavior with a specific pull request by mentioning the +username of its bot, `@coderabbitai`, alongside keywords in comments or the pull +request description, as specified by the next sections of this page. -## Review Control Commands +For a complete CodeRabbit command reference, see [Code review command reference](/reference/review-commands). -### Managing Reviews +## Control automatic code reviews {#flow} -| 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 | +By default, CodeRabbit automatically reviews every new pull request created in +your repository. It updates its review with comments whenever the pull request has new commits +pushed to it. -### Review Flow Control +The following sections show you how to tell CodeRabbit to modify this behavior with +a specific pull request, such as pausing reviews, or resolving open comments. -| 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 | +For more information about permanently configuring the behavior of CodeRabbit on +your repository, see [Add a configuration file](/getting-started/configure-coderabbit). -### Comment Management +### Pause and resume automatic code reviews {#pause-resume} -| Command | Description | Use Case | -| ----------------------- | --------------------------------------- | ------------------------------------------------------- | -| `@coderabbitai resolve` | Resolves all CodeRabbit review comments | When you've addressed all feedback and want to clean up | +You can tell CodeRabbit to pause its automatic reviews of a pull request. If +you do, then you can still manually request CodeRabbit to review changes using +the commands listed on [Code review command reference](/reference/review-commands). -### Documentation Commands +To pause automated reviews of a pull request, post the following comment to the +pull request: -| 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 | +```text +@coderabbitai pause +``` -### Agentic Chat Commands +To resume automated reviews after pausing them, post the following comment to the +pull request: -| 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 | +```text +@coderabbitai resume +``` -### Help & Support +### Disable automatic code reviews {#ignore} -| Command | Description | Use Case | -| -------------------- | ------------------------------------------ | ------------------------------------------ | -| `@coderabbitai help` | Displays available commands and usage info | When you need guidance on using CodeRabbit | +To disable automatic code reviews for a pull request, add the following line +anywhere in the pull request description: -## Best Practices +```text +@coderabbitai ignore +``` -### Review Workflow +As long as that text remains in the description, CodeRabbit will not +automatically review any commits associated with that pull request. +You can still [chat with CodeRabbit](/guides/agent_chat) and issue other commands in the pull +request comments. -- Start with `@coderabbitai review` for checking new changes -- Use `@coderabbitai full review` when major changes require a fresh perspective -- Generate summaries after significant updates using `@coderabbitai summary` +To enable automatic reviews on that pull request, delete "`@coderabbitai ignore`" +from the pull request description. CodeRabbit commences automatic reviews starting with +the next commit made to the branch under review. -### Managing Large Changes +## Manually request code reviews {#request} -- Use `@coderabbitai pause` before making multiple commits -- Resume reviews with `@coderabbitai resume` when ready -- Consider `@coderabbitai full review` after substantial changes +You can ask CodeRabbit to perform a code review at any time. This can be useful +when you have paused automated code reviews. Manually requested reviews have +two types: -### Documentation Flow +- A _full review_ disregards any comments that CodeRabbit has already made + on this pull request, and generates a complete review of the entire pull request. -- Run `@coderabbitai generate docstrings` after finalizing function implementations -- Learn more about [docstring generation](/finishing-touches/docstrings) +- An _incremental review_ takes all comments that CodeRabbit has made since its most recent full review into consideration, and generates a review of only the new changes. -## Tips +To manually request a full review, post the following comment to the +pull request: -- 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 +```text +@coderabbitai full review +``` -## Command Response Time +To manually request an incremental review, post the following comment to the +pull request: -- 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 +```text +@coderabbitai review +``` -## Troubleshooting +## Resolve comments {#resolve} -If a command doesn't seem to work: +To have CodeRabbit mark all of its previous comments as resolved, post the following comment to the +pull request: -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 +```text +@coderabbitai resolve +``` -Need help? Join our community on [Discord](https://discord.gg/coderabbit) or contact our support team. +## Generate summary text {#summary} + +To have CodeRabbit add or update a generated summary of the branch’s proposed changes +to the pull request’s description, post the following comment: +pull request: + +```text +@coderabbitai summary +``` + +CodeRabbit appends the summary text to the description under the heading +"Summary by CodeRabbit". If CodeRabbit has previously added a summary under that +heading, then it replaces it with the new summary. + +## Get information about CodeRabbit {#info} + +The commands in this section request CodeRabbit to display its own configuration +or documentation. + +### Display current configuration {#config} + +To have CodeRabbit post a comment listing out its current configuration +with your repository, post the following comment to the +pull request: + +```text +@coderabbitai configuration +``` + +### Display a quick-reference guide {#help} + +To have CodeRabbit post a comment to the pull request with a quick-reference +guide to its own commands and other features, post the following comment to the +pull request: + +```text +@coderabbitai help +``` + +## What's next {#whats-next} + +- [Generate code improvements](/guides/generate-improvements) +- [Best practices](/guides/code-review-best-practices) +- [Troubleshooting](/guides/code-review-troubleshooting) diff --git a/docs/guides/generate-improvements.md b/docs/guides/generate-improvements.md new file mode 100644 index 00000000..a348b9e9 --- /dev/null +++ b/docs/guides/generate-improvements.md @@ -0,0 +1,77 @@ +--- +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'; + + +``` + +During a code review, you can command CodeRabbit to address its own review comments +by generating its own code improvements, which it publishes on separate branches. + +For a general overview of performing code reviews with CodeRabbit, see [Review pull requests](/guides/code-review-overview). + +## Overview of CodeRabbit code generation {#overview} + +You can command CodeRabbit to generate any code changes necessary to address its own code review suggestions, +or you can command it specifically to address inline documentation gaps. + +After you give it a code-generation command, CodeRabbit delivers its suggested improvements by taking these steps: + +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} + +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} + +:::note +This feature is available only on GitHub. +::: + +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 +@coderabbitai plan +``` + +## What's next {#whats-next} + +- [Control and manage code reviews](/guides/commands) +- [Best practices](/guides/code-review-best-practices) +- [Troubleshooting](/guides/code-review-troubleshooting) diff --git a/docs/reference/review-commands.md b/docs/reference/review-commands.md new file mode 100644 index 00000000..011bf9d5 --- /dev/null +++ b/docs/reference/review-commands.md @@ -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 | diff --git a/sidebars.ts b/sidebars.ts index 2668b5c1..210e385d 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -84,7 +84,11 @@ const sidebars: SidebarsConfig = { collapsed: true, label: "Review pull requests", items: [ + "guides/code-review-overview", "guides/commands", + "guides/generate-improvements", + "guides/code-review-best-practices", + "guides/code-review-troubleshooting", "guides/agent_chat", { type: "category", @@ -140,6 +144,7 @@ const sidebars: SidebarsConfig = { label: "CodeRabbit API", href: "https://api.coderabbit.ai/api/swagger/", }, + "reference/review-commands", { type: "category", label: "Supported tools",