Skip to content

Commit d6ff746

Browse files
jmacdotorgjmacdotorg
committed
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-orience how-to guides, one about controlling code reviews, and one about generating improvements. Add a new overview page for the code review process.
1 parent 7042a8a commit d6ff746

7 files changed

+378
-60
lines changed

‎docs/guides/code-review-best-practices.md

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
---
2+
title: Code review best practices
3+
description: Best practices for managing CodeRabbit code reviews.
4+
sidebar_label: Best practices
5+
---
6+
7+
This page lists best practices for performing code reviews with CodeRabbit.
8+
9+
For more information about working with
10+
CodeRabbit through chat, see [Control and manage code reviews](/guides/commands).
11+
12+
For a CodeRabbit command reference, see [Code review command reference](/reference/review-commands).
13+
14+
## Recommended code-review workflow
15+
16+
- Start with `@coderabbitai review` for checking new changes.
17+
- Use `@coderabbitai full review` when major changes require a fresh perspective.
18+
- Generate summaries after significant updates using `@coderabbitai summary`.
19+
20+
## Managing large changes
21+
22+
- Use `@coderabbitai pause` before making multiple commits.
23+
- Resume reviews with `@coderabbitai resume` when ready.
24+
- Consider `@coderabbitai full review` after substantial changes.
25+
26+
## Documentation flow
27+
28+
- Run `@coderabbitai generate docstrings` after finalizing function implementations.
29+
- Learn more about [docstring generation](/finishing-touches/docstrings).
30+
31+
## Overall tips
32+
33+
- Commands are case-insensitive (`@coderabbitai REVIEW` works the same as `@coderabbitai review`).
34+
- Commands can be issued by anyone with write access to the repository.
35+
- Multiple commands can be used in sequence as needed.
36+
- Use `@coderabbitai configuration` to export your settings before making changes.
37+
38+
## Command response time
39+
40+
- Most commands (pause, resume, ignore) take effect immediately.
41+
- Review commands typically complete within a few minutes, depending on PR size.
42+
- Docstring generation time varies based on the number of functions.

‎docs/guides/code-review-overview.md

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
---
2+
title: Review pull requests
3+
description: An overview of CodeRabbit's core code review features.
4+
sidebar_label: Overview
5+
---
6+
7+
One of the core features of CodeRabbit is its ability to proactively review
8+
new pull requests on your code repository.
9+
10+
CodeRabbit reviews take the form of pull request comments that
11+
include summaries, analyses, and initial critiques of the proposed changes.
12+
This information, usually added to pull requests within minutes, can help your team perform more rapid, better-informed code reviews.
13+
14+
The following sections present an overview of this feature. For a hands-on example that lets you experience a CodeRabbit code review using
15+
a real repository, see [Quickstart](/getting-started/quickstart).
16+
17+
## Automatically review pull requests {#review}
18+
19+
After you [integrate CodeRabbit with your repository](/platforms), CodeRabbit proceeds
20+
to automatically review every subsequent pull request, as soon as each one is created.
21+
22+
A CodeRabbit code review consists of a single, multi-part comment attached to the pull request.
23+
The comment contains a detailed summary and analysis of the changes,
24+
as well as a listing of problems or areas for potential improvement that it found.
25+
26+
CodeRabbit
27+
uses a variety of open-source linters and security tools to provide this analysis. CodeRabbit
28+
also consults a number of large language models (LLMs) to further analyze and critique the proposed changes,
29+
using all of the content of your repository as context. The code-review comment that CodeRabbit attaches
30+
to your pull request synthesizes and summarizes all of the information collected from these different sources.
31+
32+
For more information
33+
on the open-source tools that CodeRabbit applies and how you can configure its use of them,
34+
see [Configure third-party tool use](/tools).
35+
36+
For more information about the graph analysis that CodeRabbit includes with its reviews
37+
when available, see [CodeRabbit Code Graph Analysis](/integrations/code-graph-analysis).
38+
39+
### Events that trigger automated reviews {#events}
40+
41+
By default, the following activity in your repository triggers CodeRabbit to
42+
perform a code review:
43+
44+
- If CodeRabbit sees a new pull request, then it immediately performs a full review
45+
of the proposed code changes.
46+
- If an open pull request that CodeRabbit has already reviewed gets modified with another
47+
commit, then CodeRabbit performs an incremental review that focuses on the new commit.
48+
49+
### Example code reviews {#examples}
50+
51+
The following real pull requests, hosted on GitHub, demonstrate some example CodeRabbit
52+
review comments.
53+
54+
- [A modest refactoring of Markdown-based documentation source](https://github.com/coderabbitai/coderabbit-docs/pull/325), demonstrating a CodeRabbit graph analysis.
55+
- [A large change that added many files](https://github.com/tyaga001/devtoolsacademy/pull/44), demonstrating incremental automated reviews of subsequent commits.
56+
57+
## Interact with CodeRabbit reviews {#interact}
58+
59+
After CodeRabbit attaches its initial code-review comment to a pull request, you can
60+
directly interact with CodeRabbit by mentioning its username, `@coderabbitai`, in comments
61+
that you post to the pull request.
62+
63+
These interactions can serve several purposes:
64+
65+
- Free-form discussion about the pull request and the ongoing code review.
66+
- Commands to have CodeRabbit perform specific actions regarding the code review.
67+
- Prompts to have CodeRabbit generate its own improvements to the branch under review.
68+
69+
### Chat with CodeRabbit {#chat}
70+
71+
You can have open-ended, natural-language discussion with CodeRabbit during a code review, treating it
72+
as an LLM-powered chat bot that has your entire code repository available for context. For more information, see [CodeRabbit Chat](/guides/agent_chat).
73+
74+
### Manage CodeRabbit review behavior {#manage}
75+
76+
CodeRabbit recognizes a variety of keyword-based commands that let you control its
77+
behavior during a code review, including the following:
78+
79+
- Pause or resume automated reviews of the pull request.
80+
- Manually request a review, when automated reviews are paused.
81+
- Resolve all open comments authored by CodeRabbit.
82+
83+
For more information, see [Control and manage code reviews](/guides/commands).
84+
85+
### Generate improvements {#generate}
86+
87+
You can command CodeRabbit to generate improvements to the branch under review.
88+
CodeRabbit accomplishes this by publishing a new branch based on the branch under review,
89+
and cerating a new pull request for your own review.
90+
91+
Available code-generation commands let you request the following from CodeRabbit:
92+
93+
- Implement the suggestions for improvements that CodeRabbit has made in its earlier code review comments.
94+
- Generate inline documentation for any undocumented functions that this pull request proposes to add.
95+
96+
For more information, see [Generate improvements](/guides/generate-improvements).
97+
98+
## What's next {#whats-next}
99+
100+
- [Control and manage code reviews](/guides/commands)
101+
- [Generate code improvements](/guides/generate-improvements)

‎docs/guides/code-review-troubleshooting.md

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
title: Code review troubleshooting
3+
description: Troubleshooting CodeRabbit code reviews.
4+
sidebar_label: Troubleshooting
5+
---
6+
7+
This page is about troubleshooting interactive code review sessions with CodeRabbit. For more information about working with
8+
CodeRabbit through chat, see [Control and manage code reviews](/guides/commands).
9+
10+
If a CodeRabbit command doesn't seem to work:
11+
12+
1. Check that you have the necessary repository permissions.
13+
2. Verify the command syntax.
14+
3. Look for any response from CodeRabbit in the PR comments.
15+
4. Use `@coderabbitai help` for command guidance.
16+
17+
Need help? Join our community on [Discord](https://discord.gg/coderabbit) or [contact our support team](/getting-started/support).

‎docs/guides/commands.md

Lines changed: 96 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -3,92 +3,128 @@ title: Control and manage code reviews
33
description: Learn how to control CodeRabbit using commands in pull request comments
44
---
55

6-
# CodeRabbit Commands
6+
This page is about issuing direct commands to CodeRabbit during code reviews.
7+
For a general overview of performing code reviews with CodeRabbit, see [Review pull requests](/guides/code-review-overview).
78

8-
> 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.
9+
You can control CodeRabbit's behavior with a specific pull request by mentioning the
10+
username of its bot, `@coderabbitai`, alongside keywords in comments or the pull
11+
request description, as specified by the next sections of this page.
912

10-
## Review Control Commands
13+
For a complete CodeRabbit command reference, see [Code review command reference](/reference/review-commands).
1114

12-
### Managing Reviews
15+
## Control the flow of code reviews {#flow}
1316

14-
| Command | Description | Use Case |
15-
| --------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------- |
16-
| `@coderabbitai review` | Triggers an incremental review of new changes | When automatic reviews are disabled or you want to manually trigger a review |
17-
| `@coderabbitai full review` | Performs a complete review of all files from scratch | When you want to get fresh insights on the entire PR |
18-
| `@coderabbitai summary` | Regenerates the PR summary | When you want an updated overview after making changes |
17+
By default, CodeRabbit automatically reviews every new pull request created in
18+
your repository. It updates its review with with comments whenever the pull request has new commits
19+
pushed to it.
1920

20-
### Review Flow Control
21+
The following sections show you how to tell CodeRabbit to modify this behavior with
22+
a specific pull request, such as pausing reviews, or resolving open comments.
2123

22-
| Command | Description | Use Case |
23-
| ---------------------- | ---------------------------------------- | --------------------------------------------------- |
24-
| `@coderabbitai pause` | Temporarily stops reviews on the PR | When you're making multiple rapid changes |
25-
| `@coderabbitai resume` | Restarts reviews after a pause | When you're ready for CodeRabbit to review again |
26-
| `@coderabbitai ignore` | Permanently disables reviews for this PR | When you want to handle the review process manually |
24+
For more information about permanently configuring the behavior of CodeRabbit on
25+
your repository, see [Add a configuration file](/getting-started/configure-coderabbit).
2726

28-
### Comment Management
27+
### Have CodeRabbit ignore a pull request {#ignore}
2928

30-
| Command | Description | Use Case |
31-
| ----------------------- | --------------------------------------- | ------------------------------------------------------- |
32-
| `@coderabbitai resolve` | Resolves all CodeRabbit review comments | When you've addressed all feedback and want to clean up |
29+
If you want CodeRabbit to completely disregard a pull request, then add
30+
the following text, on a line by itself, to the pull request description:
3331

34-
### Documentation Commands
32+
```
33+
@coderabbitai ignore
34+
```
3535

36-
| Command | Description | Use Case |
37-
| ----------------------------------- | -------------------------------------------- | --------------------------------------------------- |
38-
| `@coderabbitai generate docstrings` | Generates docstrings for functions in the PR | When you need automatic documentation for your code |
39-
| `@coderabbitai configuration` | Shows current CodeRabbit settings | When you need to check or export your configuration |
36+
You can include this line while creating the pull request, or you can add it
37+
to the description after you create it.
4038

41-
### Agentic Chat Commands
39+
So long as the `@coderabbitai ignore` line remains in the pull request description, CodeRabbit
40+
doesn't perform any processing at all on this pull request. This also causes
41+
CodeRabbit to ignore any attempts to issue to commands using comments that mention `@coderabbitai`.
4242

43-
| Command | Description | Use Case |
44-
| -------------------- | ---------------------------------------------------------- | ---------------------------------------------------- |
45-
| `@coderabbitai plan` | Get the agentic chat to plan an edit for previous comments | When you want CodeRabbit to change your code for you |
43+
To have CodeRabbit stop ignoring a pull request, edit the description to
44+
remove the `@coderabbitai ignore` line.
4645

47-
### Help & Support
46+
### Pause and resume code reviews {#pause-resume}
4847

49-
| Command | Description | Use Case |
50-
| -------------------- | ------------------------------------------ | ------------------------------------------ |
51-
| `@coderabbitai help` | Displays available commands and usage info | When you need guidance on using CodeRabbit |
48+
You can tell CodeRabbit to pause its automatic reviews of a pull request. If
49+
you do, then you can still manually request CodeRabbit to review changes using
50+
the commands listed on [Code review command reference](/reference/review-commands).
5251

53-
## Best Practices
52+
To pause automated reviews of a pull request, post the following comment to the
53+
pull request:
5454

55-
### Review Workflow
55+
```
56+
@coderabbitai pause
57+
```
5658

57-
- Start with `@coderabbitai review` for checking new changes
58-
- Use `@coderabbitai full review` when major changes require a fresh perspective
59-
- Generate summaries after significant updates using `@coderabbitai summary`
59+
To resume automated reviews after pausing them, post the following comment to the
60+
pull request:
6061

61-
### Managing Large Changes
62+
```
63+
@coderabbitai resume
64+
```
6265

63-
- Use `@coderabbitai pause` before making multiple commits
64-
- Resume reviews with `@coderabbitai resume` when ready
65-
- Consider `@coderabbitai full review` after substantial changes
66+
## Manually request code reviews {#request}
6667

67-
### Documentation Flow
68+
You can ask CodeRabbit to perform a code review at any time. This can be useful
69+
when you have paused automated code reviews. Manually requested reviews have
70+
two types:
6871

69-
- Run `@coderabbitai generate docstrings` after finalizing function implementations
70-
- Learn more about [docstring generation](/finishing-touches/docstrings)
72+
- A _full review_ disregards any comments that CodeRabbit has already made
73+
on this pull request, and generates a complete review of the entire pull request.
7174

72-
## Tips
75+
- An _incremental review_ takes all comments that CodeRabbit has made since
76+
its most recent full review into consideration, and
7377

74-
- Commands are case-insensitive (`@coderabbitai REVIEW` works the same as `@coderabbitai review`)
75-
- Commands can be issued by anyone with write access to the repository
76-
- Multiple commands can be used in sequence as needed
77-
- Use `@coderabbitai configuration` to export your settings before making changes
78+
To manually request a full review, post the following comment to the
79+
pull request:
7880

79-
## Command Response Time
81+
```
82+
@coderabbitai full review
83+
```
8084

81-
- Most commands (pause, resume, ignore) take effect immediately
82-
- Review commands typically complete within a few minutes, depending on PR size
83-
- Docstring generation time varies based on the number of functions
85+
To manually request an incremental review, post the following comment to the
86+
pull request:
8487

85-
## Troubleshooting
88+
```
89+
@coderabbitai review
90+
```
8691

87-
If a command doesn't seem to work:
92+
## Resolve comments {#resolve}
8893

89-
1. Check that you have the necessary repository permissions
90-
2. Verify the command syntax
91-
3. Look for any response from CodeRabbit in the PR comments
92-
4. Use `@coderabbitai help` for command guidance
94+
To have CodeRabbit mark all of its previous comments as resolved, post the following comment to the
95+
pull request:
9396

94-
Need help? Join our community on [Discord](https://discord.gg/coderabbit) or contact our support team.
97+
```
98+
@coderabbitai resolve
99+
```
100+
101+
## Get information about CodeRabbit {#info}
102+
103+
The commands in this section request CodeRabbit to display its own configuration
104+
or documentation.
105+
106+
### Display current configutation {#config}
107+
108+
To have CodeRabbit post a comment listing out its current configuration
109+
with your repository, post the following comment to the
110+
pull request:
111+
112+
```
113+
@coderabbitai configuration
114+
```
115+
116+
### Display a quick-reference guide {#help}
117+
118+
To have CodeRabbit post a comment to the pull review with a quick-reference
119+
guide to its own commands and other features, post the following comment to the
120+
pull request:
121+
122+
```
123+
@coderabbitai help
124+
```
125+
126+
## What's next {#whats-next}
127+
128+
- [Generate code improvements](/guides/generate-improvements)
129+
- [Best practices](/guides/code-review-best-practices)
130+
- [Tips and troubleshooting](/guides/code-review-tips-and-troubleshooting)

0 commit comments

Comments
 (0)