Merge branch 'main' into fix/oxlint

Author: alexcoderabbitai

docs/changelog.md

@@ -5,6 +5,26 @@ description: The latest updates and changes to CodeRabbit.
 sidebar_position: 13
 ---
 
+## April 19, 2025
+
+### Docstring Path Instructions
+
+You can now provide path-based instructions for the generation of docstring in `.coderabbit.yaml`.
+
+Example:
+
+```yaml
+code_generation:
+  docstrings:
+    path_instructions:
+      - path: "**/*.ts"
+        instructions: |
+          End all docstrings with a notice that says "Auto-generated by CodeRabbit.".
+          Do not omit the closing tags; the docstring must be valid.
+```
+
+See the [docstrings documentation](/finishing-touches/docstrings#path-instructions) for more details.
+
 ## April 14, 2025
 
 ### Shopify CLI Integration & Bitbucket Cloud Reporting

docs/finishing-touches/docstrings.md

@@ -33,6 +33,20 @@ CodeRabbit cannot perform further modifications to opened pull requests. From th
 
 This feature has been rigorously tested and is now available for all Pro plan users. Additionally, you can provide feedback about this feature on [Discord](https://discord.com/channels/1134356397673414807/1317286905557287022).
 
+## Path Instructions
+
+You can customize the generated docstrings by providing instructions based on file paths in your `.coderabbit.yaml`. The `path` is a [minimatch](https://github.com/isaacs/minimatch) pattern.
+
+```yaml
+code_generation:
+  docstrings:
+    path_instructions:
+      - path: "**/*.ts"
+        instructions: |
+          End all docstrings with a notice that says "Auto-generated by CodeRabbit.".
+          Do not omit the closing tags; the docstring must be valid.
+```
+
 ## Supported software forges
 
 These software forges are supported:

docs/getting-started/quickstart.md

@@ -1,55 +1,135 @@
 ---
-title: Playing with CodeRabbit
+title: Quickstart
 sidebar_label: Quickstart
-description: Get started with CodeRabbit in less than 2 minutes
+description: See CodeRabbit in action, using a live GitHub repository.
 sidebar_position: 1
 ---
 
-# Quickstart Guide
+# Quickstart
+
+This tutorial gives you a hands-on demonstration of CodeRabbit, using a real, GitHub-based repository. It guides you through the following tasks:
+
+1. Integrate CodeRabbit into a GitHub-based repository that you own.
+1. Observe CodeRabbit perform a code review of a pull request that you initiate.
+1. Converse with CodeRabbit about the code review.
+1. Prompt CodeRabbit to generate its own improvements to the pull request.
+
+When you complete this tutorial, you'll have seen CodeRabbit's code-review feature in action, and glimpsed a few of its other AI-driven abilities as well.
+
+For a more general overview of CodeRabbit, see [Introduction](/).
 
 :::note
-Get started with CodeRabbit in three simple steps. No complex configuration needed.
+While this tutorial focuses on GitHub, CodeRabbit also works with GitLab, Azure DevOps, and Bitbucket. For more information, see [Supported Git Platforms](/platforms/).
 :::
 
-## Steps to Enable CodeRabbit
+## Before you begin
 
-### Sign In with GitHub
+Create a new, private repository on GitHub. Name the new repository `coderabbit-test`, and let it have otherwise default GitHub settings.
 
-- Visit [coderabbit.ai](https://coderabbit.ai)
-- Click "Sign in with GitHub"
-- Authorize CodeRabbit
+## Integrate CodeRabbit with your GitHub account
 
-![CodeRabbit Login](/img/integrations/login-self-hosted-github.png)
+To integrate CodeRabbit with your GitHub account, follow these steps:
 
-### Add Your Repository
+1. Visit [the CodeRabbit login page](https://app.coderabbit.ai/login).
+1. Click **Login with GitHub**.
+1. Click **Authorize coderabbitai**.
 
-- Go to your [Dashboard](https://app.coderabbit.ai/dashboard)
-- Click "Add Repositories"
-- Select the repositories you want to enable
+CodeRabbit takes a moment to set up the integration. After it finishes, the CodeRabbit dashboard appears.
 
-![CodeRabbit Dashboard](/img/getting-started/dashboard-coderabbit.png)
+## Add CodeRabbit to your repository
 
-### You're Done 🎉
+To add CodeRabbit to your test repository, follow these steps:
 
-- CodeRabbit will automatically start reviewing your Pull Requests
-- Default configuration works out of the box
-- No additional setup needed
+1. On the CodeRabbit dashboard, click **Add Repositories**. A GitHub repository-access dialog appears.
+1. Select the **Only select repositories** radio button.
+1. From the **Select repositories** menu, select the `coderabbit-test` repository that you created earlier in this Quickstart.
+1. Click **Install & Authorize**.
+1. If a CodeRabbit **Complete your signup** dialog appears, then fill it out with the requested information before continuing.
 
-## What's Next?
+CodeRabbit is now ready to use with your test repository. The next steps demonstrate its core code-review features.
 
-- Watch CodeRabbit
-- Here's an example of CodeRabbit in action:
-  ![CodeRabbit PR Review Example](/img/getting-started/pr-examples.png)
-- [View live example PR](https://github.com/tyaga001/devtoolsacademy/pull/39)
-- [Configure CodeRabbit](/getting-started/configure-coderabbit) (optional)
-- [Add custom review instructions](/guides/review-instructions) (optional)
+## Let CodeRabbit perform a code review
 
-## Need Help?
+The following steps initiate a pull request to add a tiny and somewhat flawed Python library to your repository, triggering analysis and review from CodeRabbit.
 
-- Join our [Discord community](https://discord.gg/coderabbit) for support
-- Check out our [FAQ](/faq)
-- Contact [support@coderabbit.ai](mailto:support@coderabbit.ai)
+Use your usual Git workflow to perform the following steps in the `coderabbit-test` repository:
 
-:::tip
-CodeRabbit starts working immediately. You can customize its behavior later when needed.
-:::
+1. Create a branch named `add-utils`.
+
+1. In that new `add-utils` branch, create a new file called `simple_utils.py`, with the following content:
+
+   ```python
+   # simple_utils.py - A tiny utility library
+
+   def reverse_string(text):
+       """Reverses the characters in a string."""
+       return text[::-1]
+
+   def count_words(sentence):
+       return len(sentence.split())
+
+   def celsius_to_fahrenheit(celsius):
+       return (celsius * 9/5) + 32
+   ```
+
+1. Commit the added file to the `add-utils` branch. Use any text you want for the commit message.
+
+1. Create a pull request that proposes to merge the `add-utils` branch into the `main` branch. Use any text you want for the pull request message.
+
+After a few moments, CodeRabbit responds to the pull request using the `@coderabbitai` GitHub account. It performs the following actions, all of which are visible on the pull request's page on GitHub:
+
+- If you didn't write a pull request summary, then CodeRabbit adds a new summary to the pull request.
+- CodeRabbit posts a comment titled **Walkthrough** containing analysis and commentary about the content of the pull request.
+- CodeRabbit attaches a detailed code review to the pull request as another comment.
+
+Part of the review resembles the following screenshot:
+
+![An example code review comment](/img/getting-started/quickstart-comment.png)
+
+This shows that CodeRabbit has noticed some flaws with this Python library, including a lack of docstrings and input validation. The review comment identifies these flaws, and suggests how you might improve them.
+
+## Ask CodeRabbit for more information
+
+After CodeRabbit reviews a pull request, you can converse with it about its review. You can also give CodeRabbit special commands to request it to perform specific functions, such as generating appropriate code changes for you.
+
+1. Post the following as a new GitHub comment attached to the pull request:
+
+   ```text
+   @coderabbitai Why do all of these functions need docstrings? Isn't it obvious enough what they do?
+   ```
+
+   After a few moments, CodeRabbit posts its reply, explaining its motivations for its recommendation. The reply might resemble the following:
+
+   > You're right that these functions are quite self-explanatory from their names alone. Docstrings aren't strictly necessary for every function, especially in smaller projects with clear function names.
+   >
+   > While docstrings do provide benefits (IDE tooltips, documentation generation, help for future developers), they can sometimes feel redundant for very straightforward functions. It's ultimately a matter of coding style and project requirements.
+   >
+   > If you prefer to skip docstrings for obvious utility functions in this project, that's perfectly reasonable. Would you like me to adjust my review approach regarding documentation for this repository?
+
+   In this case, CodeRabbit is offering to adjust its future behavior when reviewing changes to this repository. Instead, follow the next step to ask CodeRabbit to implement part of its suggestions.
+
+1. Post the following as another new comment:
+
+   ```text
+   @coderabbitai generate docstrings
+   ```
+
+   After a few moments, CodeRabbit does the following:
+
+   - CodeRabbit creates a new branch, based on `add-utils`.
+   - CodeRabbit commits changes to the branch that adds suggested docstrings to `add-utils`.
+   - CodeRabbit opens a new pull request between the new branch and `add-utils`.
+
+## Clean up
+
+Continue experimenting with CodeRabbit in your test repository for as long as you like. When you're finished, you can delete the repository.
+
+You are now ready to add CodeRabbit to other repositories that you own, and let it review some real pull requests.
+
+## What's next
+
+- [Integrate CodeRabbit](/platforms/) with your repositories on GitHub, GitLab, Azure DevOps, or Bitbucket.
+- [Configure CodeRabbit](/getting-started/configure-coderabbit) beyond its default settings.
+- [Add custom review instructions](/guides/review-instructions).
+- [Get support for CodeRabbit](/getting-started/support).
+- [Learn more about how CodeRabbit works](/overview/why-coderabbit).

docs/guides/agent_chat.md

@@ -37,11 +37,11 @@ CodeRabbit Chat integrates real-time web search capabilities, enabling it to fet
 
 Set `enabled` to false within `web_search` within `knowledge_base` within the config in order to turn this off.
 
-### Code Definition Integration
+### Code Graph Analysis Integration
 
-CodeRabbit Chat is capable of taking definitions of code symbols from the symbol graph that CodeRabbit generates from your codebase. The CodeRabbit Chat response will indicate in its responses if it has found relevant symbols and snippets surrounding symbols in your codebase.
+CodeRabbit Chat is capable of analyzing definitions of code symbols from the symbol graph it generates from your codebase. CodeRabbit can use these code definitions to enhance context when providing a chat response and review comments. CodeRabbit Chat will indicate in its response if it has found relevant symbols and snippets surrounding those symbols in your codebase.
 
-Set the environment variable `ENABLE_CODE_GRAPH` in self-hosted CodeRabbit instances to turn this feature off.
+Set the environment variable `ENABLE_CODE_GRAPH` to false in self-hosted CodeRabbit instances to turn this feature off in self-hosted instances.
 
 ### Jira and Linear Integration
 

docs/overview/introduction.md

@@ -9,56 +9,84 @@ description:
 slug: "/"
 ---
 
-## What is CodeRabbit?
+# Introduction
 
-> **CodeRabbit** is an AI-powered code reviewer that delivers context-aware feedback on pull requests within minutes, reducing the time and effort needed for manual code reviews. It provides a fresh perspective and catches issues that are often missed, enhancing the overall review quality.
+This page provides a conceptual introduction to CodeRabbit. For a hands-on tutorial, see [Quickstart](/getting-started/quickstart/).
 
-Developers can interact directly with the bot within the code, offering additional context, asking questions, or even having the bot generate code. Over time, **CodeRabbit** learns from user input and improves its suggestions.
+**CodeRabbit** is an AI-powered code reviewer that delivers context-aware feedback on pull requests within minutes, reducing the time and effort needed for manual code reviews. It complements manual reviews by providing a fresh perspective and catching issues that manual reviews often miss, enhancing the overall review quality.
 
-:::tip
-See CodeRabbit in action and watch the demo video below to see how it delivers real-time, context-aware feedback on your pull requests in just a few minutes.
-:::
+Developers can interact directly with the CodeRabbit bot within their existing Git platform's pull request interface to add context, ask questions, or even have the bot generate code. Over time, CodeRabbit learns from user input and improves its suggestions.
 
 <div class="video-container">
   <iframe src="https://www.youtube.com/embed/3SyUOSebG7E?si=i0oT9RAnH0PW81lY" title="YouTube video player" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerPolicy="strict-origin-when-cross-origin" allowFullScreen></iframe>
 </div>
 
-## Integration with GitHub, GitLab and Azure DevOps
+## Core features
 
-> **CodeRabbit** integrates with GitHub, GitLab and Azure DevOps repositories to deliver continuous and incremental reviews for each commit in a pull request (PR) or merge request (MR). Review feedback is automatically sent back to the PR/MR and can be committed directly.
+Core CodeRabbit features include the following:
 
-It works via a webhook, monitoring Pull Request (PR) and Merge Request (MR) events. A comprehensive review is performed when a PR or MR is created, and for
-incremental commits and comments addressed to the bot. The feedback is then sent directly back to the Pull Request or Merge Request.
+- Integrates rapidly with popular Git platforms and workflows.
+- Applies dozens of open-source, industry-standard code analyzers to every commit.
+- Implements code reviews as familiar pull-request comments.
+- Works with contributors through natural-language conversation in comments.
+- Learns and adapts to your team's code style and review preferences.
+- Provides an observability dashboard of code-contribution activity.
+- Practices strong privacy and security, with no retention of analyzed code.
+- Offers free use for public repositories, and flexible pricing for private codebases.
 
-![CodeRabbit Code Review Flow showing how AI integrates with GitHub and GitLab for continuous pull request feedback.](/img/about/coderabbit-flow.png "CodeRabbit Code Review Flow")
+## Seamless workflow integration
 
-## Data Privacy and Security
+CodeRabbit shares its reviews as comments attached to pull requests, using the same Git platform that your team already uses. Further commits in the same pull review prompt CodeRabbit to make further reviews, using the earlier reviews as context.
 
-> **CodeRabbit** does not use data collected from code reviews to train or influence its models. All queries to Large Language Models (LLMs) are ephemeral, with zero retention. No data is shared with third parties.
+Each time that it performs a code review, CodeRabbit runs the relevant code changes through [an array of industry-standard code linters, security analyzers, and other tools](/tools/). CodeRabbit synthesizes the output of these tools into its reviews, offering a high-level analysis that can suggest areas for further focus and improvement.
 
-- **Temporary Storage**: Code is temporarily stored in memory during the review process and deleted afterward.
-- **Stored Embeddings**: While the code itself isn’t stored, **CodeRabbit** stores embeddings based on chat conversations and workflow systems (Linear, Jira, GitHub/GitLab issues) to improve future reviews.
-- **Compliance**: All data is kept confidential, isolated by organization, and complies with **SOC2 Type II** and **GDPR** standards.
+Your team can have conversations with CodeRabbit about its reviews by replying to it with follow-up comments on pull requests, asking it questions or making observations about the review using natural language. CodeRabbit continues the conversation appropriately, offering further insights about the code changes, or adjusting its own review style based on feedback.
 
-### Opting Out
+### Customizable review preferences
 
-You can opt out of data storage at any time without affecting your access to **CodeRabbit**.
-:::warning
-However, opting out may reduce the level of personalized review feedback.
-:::
+As you interact with CodeRabbit through chat, it learns the review preferences of your team, and applies them to all future reviews on a given repository.
 
-## Try CodeRabbit Now
+For example, if CodeRabbit uses a linter to suggest that your pull request use four-space indentations, but your team uses a two-space indentation style, then you can reply to CodeRabbit's pull-request comment to tell it exactly that. CodeRabbit acknowledges your feedback and adjusts all of its subsequent reviews with that repository appropriately.
 
-> Ready to experience **CodeRabbit** in action?
+For a video introduction to this feature, see [CodeRabbit Learnings](https://www.youtube.com/watch?v=Yu0cmmOYA-U).
 
-:::tip
-For open source projects CodeRabbit Pro is **_FREE_**, forever.
+If you need to fine-tune CodeRabbit's behavior beyond this, then you can [add a CodeRabbit-specific configuration file](/getting-started/configure-coderabbit) to your repository, or use the CodeRabbit web UI to set further preferences. This file can include [path-based instructions](/guides/review-instructions) for how CodeRabbit should review different files within your codebase.
 
-- No credit card required
-- Unlimited public repositories
+No matter how you tune and customize CodeRabbit, its default settings make it useful out of the box, able to meaningfully review pull requests within minutes of its introduction to a repository.
 
-:::
+### Platform integration options
 
-<div style={{textAlign: 'left', marginTop: '20px'}}>
-  <a href="https://app.coderabbit.ai/login" className="button button--primary button--lg">Start reviewing PR Now</a>
-</div>
+CodeRabbit integrates in just a few clicks with many popular Git platforms:
+
+- GitHub, including GitHub Enterprise Server
+- GitLab, including self-managed GitLab
+- Azure DevOps
+- Bitbucket Cloud
+
+In addition, CodeRabbit can integrate with a number of popular workflow systems:
+
+- Jira
+- Linear
+- CircleCI
+
+## Data privacy and security
+
+CodeRabbit does not use data collected from code reviews to train or influence its models. All queries to large language models (LLMs) are ephemeral, with zero retention. No data is shared with third parties.
+
+- **Temporary Storage**: CodeRabbit temporarily stores your code in memory during the review process, and deletes it afterward.
+- **Stored Embeddings**: While CodeRabbit doesn't store your code, it does store embeddings based on chat conversations and workflow systems (Linear, Jira, GitHub/GitLab issues) to improve future reviews.
+- **Compliance**: All data is kept confidential, isolated by organization, and complies with SOC2 Type II and GDPR standards.
+
+You can opt out of data storage at any time without affecting your access to CodeRabbit. Opting out might reduce the level of personalized review feedback that CodeRabbit can provide you.
+
+## Flexible pricing, free for public repositories
+
+Public repositories can use the Pro tier of CodeRabbit at no charge, including all of the code-review features described on this page. Rate limits might apply.
+
+For private repositories, a number of pricing tiers are available. These range from a Free tier that offers unlimited code-change summaries, to an Enterprise tier with access to advanced features and SLA support. For more information, see [Pricing](https://www.coderabbit.ai/pricing).
+
+## What's next
+
+- [Quickstart](/getting-started/quickstart/) lets you experience your first CodeRabbit code review first-hand.
+
+- [Why CodeRabbit?](/overview/why-coderabbit) dives further into the philosophies and technologies that drive CodeRabbit.