diff --git a/README.md b/README.md index aa759d5f..4f8507c2 100644 --- a/README.md +++ b/README.md @@ -48,7 +48,16 @@ See the [Usage Guide](./Usage.md) for running the PR-Agent commands via differen See the [Tools Guide](./docs/TOOLS_GUIDE.md) for detailed description of the different tools (tools are run via the commands). -

Example results:

+## Table of Contents +- [Example results](#example-results) +- [Features overview](#features-overview) +- [Try it now](#try-it-now) +- [Installation](#installation) +- [PR-Agent Pro 💎](#pr-agent-pro) +- [How it works](#how-it-works) +- [Why use PR-Agent?](#why-use-pr-agent) + +## Example results

/describe

@@ -112,22 +121,17 @@ See the [Tools Guide](./docs/TOOLS_GUIDE.md) for detailed description of the dif [//]: # (
)
-## Table of Contents -- [Overview](#overview) -- [Try it now](#try-it-now) -- [Installation](#installation) -- [How it works](#how-it-works) -- [Why use PR-Agent?](#why-use-pr-agent) +
-## Overview +## Features Overview `PR-Agent` offers extensive pull request functionalities across various git providers: | | | GitHub | Gitlab | Bitbucket | |-------|---------------------------------------------|:------:|:------:|:---------:| | TOOLS | Review | :white_check_mark: | :white_check_mark: | :white_check_mark: | | | ⮑ Incremental | :white_check_mark: | | | -| | ⮑ SOC2 Compliance 💎 | :white_check_mark: | :white_check_mark: | :white_check_mark: | +| | ⮑ [SOC2 Compliance](https://github.com/Codium-ai/pr-agent/blob/main/docs/REVIEW.md#soc2-ticket-compliance-) 💎 | :white_check_mark: | :white_check_mark: | :white_check_mark: | | | Ask | :white_check_mark: | :white_check_mark: | :white_check_mark: | | | Describe | :white_check_mark: | :white_check_mark: | :white_check_mark: | | | Improve | :white_check_mark: | :white_check_mark: | :white_check_mark: | @@ -135,9 +139,9 @@ See the [Tools Guide](./docs/TOOLS_GUIDE.md) for detailed description of the dif | | Reflect and Review | :white_check_mark: | :white_check_mark: | :white_check_mark: | | | Update CHANGELOG.md | :white_check_mark: | :white_check_mark: | :white_check_mark: | | | Find Similar Issue | :white_check_mark: | | | -| | Add PR Documentation 💎 | :white_check_mark: | :white_check_mark: | :white_check_mark: | -| | Generate Custom Labels 💎 | :white_check_mark: | :white_check_mark: | | -| | Analyze PR Components 💎 | :white_check_mark: | :white_check_mark: | :white_check_mark: | +| | [Add PR Documentation](https://github.com/Codium-ai/pr-agent/blob/main/docs/ADD_DOCUMENTATION.md) 💎 | :white_check_mark: | :white_check_mark: | :white_check_mark: | +| | [Generate Custom Labels](https://github.com/Codium-ai/pr-agent/blob/main/docs/DESCRIBE.md#handle-custom-labels-from-the-repos-labels-page-gem) 💎 | :white_check_mark: | :white_check_mark: | | +| | [Analyze PR Components](https://github.com/Codium-ai/pr-agent/blob/main/docs/Analyze.md) 💎 | :white_check_mark: | :white_check_mark: | :white_check_mark: | | | | | | | | USAGE | CLI | :white_check_mark: | :white_check_mark: | :white_check_mark: | | | App / webhook | :white_check_mark: | :white_check_mark: | | @@ -149,8 +153,8 @@ See the [Tools Guide](./docs/TOOLS_GUIDE.md) for detailed description of the dif | | Adaptive and token-aware
file patch fitting | :white_check_mark: | :white_check_mark: | :white_check_mark: | | | Multiple models support | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | | | Incremental PR review | :white_check_mark: | | | -| | Static code analysis 💎 | :white_check_mark: | :white_check_mark: | :white_check_mark: | -| | Global configuration 💎 | :white_check_mark: | :white_check_mark: | :white_check_mark: | +| | [Static code analysis](https://github.com/Codium-ai/pr-agent/blob/main/docs/Analyze.md) 💎 | :white_check_mark: | :white_check_mark: | :white_check_mark: | +| | [Global configuration](https://github.com/Codium-ai/pr-agent/blob/main/Usage.md#global-configuration-file-) 💎 | :white_check_mark: | :white_check_mark: | :white_check_mark: | - 💎 means this feature is available only in [PR-Agent Pro](https://www.codium.ai/pricing/) @@ -174,9 +178,6 @@ Note that when you set your own PR-Agent or use CodiumAI hosted PR-Agent, there --- ## Installation -When you sign up to [PR-Agent-Pro 💎](https://www.codium.ai/pricing/), you will get access to a hosted PR-Agent, which is regularly updated with the latest features and abilities. This is the easiest way to use PR-Agent. - - To use your own version of PR-Agent, you first need to acquire two tokens: 1. An OpenAI key from [here](https://platform.openai.com/), with access to GPT-4. @@ -196,6 +197,21 @@ There are several ways to use PR-Agent: - [Method 8: Run a GitLab webhook server](INSTALL.md#method-8---run-a-gitlab-webhook-server) - [Method 9: Run as a Bitbucket Pipeline](INSTALL.md#method-9-run-as-a-bitbucket-pipeline) +## PR-Agent Pro 💎 +[PR-Agent Pro](https://www.codium.ai/pricing/) is a hosted version of PR-Agent, provided by CodiumAI. It is available for a monthly fee, and provides the following benefits: +1. **Self-hosting** - We take care of everything for you - hosting, models, regular updates, and more. Installation is as simple as signing up and adding the PR-Agent app to your GitHub\BitBucket repo. +2. **Improved privacy** - No data will be stored or used to train models. PR-Agent Pro will employ zero data retention, and will use an OpenAI account with zero data retention. +3. **Improved support** - PR-Agent Pro users will receive priority support, and will be able to request new features and capabilities. +4. **Extra features** -In addition to the benefits listed above, PR-Agent Pro will emphasize more customization, and the usage of static code analysis, in addition to LLM logic, to improve results. It has the following additional feature: + - [**SOC2 compliance check**](https://github.com/Codium-ai/pr-agent/blob/main/docs/REVIEW.md#soc2-ticket-compliance-) + - [**PR documentation**](https://github.com/Codium-ai/pr-agent/blob/main/docs/ADD_DOCUMENTATION.md) + - [**Custom labels**](https://github.com/Codium-ai/pr-agent/blob/main/docs/DESCRIBE.md#handle-custom-labels-from-the-repos-labels-page-gem) + - [**Global configuration**](https://github.com/Codium-ai/pr-agent/blob/main/Usage.md#global-configuration-file-) + - [**Analyze PR components**](https://github.com/Codium-ai/pr-agent/blob/main/docs/Analyze.md) + - **Custom Code Suggestions** [WIP] + - **Chat on Specific Code Lines** [WIP] + + ## How it works The following diagram illustrates PR-Agent tools and their flow: @@ -221,7 +237,7 @@ Here are some advantages of PR-Agent: If you host PR-Agent with your OpenAI API key, it is between you and OpenAI. You can read their API data privacy policy here: https://openai.com/enterprise-privacy -When using PR-Agent-Pro 💎, hosted by CodiumAI, we will not store any of your data, nor will we used it for training. +When using PR-Agent Pro 💎, hosted by CodiumAI, we will not store any of your data, nor will we used it for training. You will also benefit from an OpenAI account with zero data retention. ## Links diff --git a/Usage.md b/Usage.md index 02135aec..76bef1d7 100644 --- a/Usage.md +++ b/Usage.md @@ -2,12 +2,12 @@ ### Table of Contents - [Introduction](#introduction) -- [Working from a local repo (CLI)](#working-from-a-local-repo-cli) -- [Online usage](#online-usage) -- [Working with GitHub App](#working-with-github-app) -- [Working with GitHub Action](#working-with-github-action) -- [Working with BitBucket App](#working-with-bitbucket-self-hosted-app) -- [Appendix - additional configurations walkthrough](#appendix---additional-configurations-walkthrough) +- [Local Repo (CLI)](#working-from-a-local-repo-cli) +- [Online Usage](#online-usage) +- [GitHub App](#working-with-github-app) +- [GitHub Action](#working-with-github-action) +- [BitBucket App](#working-with-bitbucket-self-hosted-app) +- [Additional Configurations Walkthrough](#appendix---additional-configurations-walkthrough) ### Introduction diff --git a/docs/DESCRIBE.md b/docs/DESCRIBE.md index 222d79d3..b08f563c 100644 --- a/docs/DESCRIBE.md +++ b/docs/DESCRIBE.md @@ -1,7 +1,8 @@ # Describe Tool -The `describe` tool scans the PR code changes, and automatically generates PR description - title, type, summary, walkthrough and labels. -It can be invoked manually by commenting on any PR: +The `describe` tool scans the PR code changes, and can automatically generate PR description - title, type, summary, walkthrough and labels. + +The tool can be triggered automatically every time a new PR is [opened](https://github.com/Codium-ai/pr-agent/blob/main/Usage.md#github-app-automatic-tools), or it can be invoked manually by commenting on any PR: ``` /describe ``` @@ -11,27 +12,31 @@ For example: -The `describe` tool can also be triggered automatically every time a new PR is opened. See examples for automatic triggers for [GitHub App](https://github.com/Codium-ai/pr-agent/blob/main/Usage.md#github-app-automatic-tools) and [GitHub Action](https://github.com/Codium-ai/pr-agent/blob/main/Usage.md#working-with-github-action) ### Handle custom labels from the Repo's labels page :gem: > This feature is available only in PR-Agent Pro -* GitHub : `https://github.com/{owner}/{repo}/labels`, or click on the "Labels" tab in the issues or PRs page. -* GitLab : `https://gitlab.com/{owner}/{repo}/-/labels`, or click on "Manage" -> "Labels" on the left menu. -b. Add/edit the custom labels. It should be formatted as follows: +You can control the custom labels that will be suggested by the `describe` tool, from the repo's labels page: + +* GitHub : go to `https://github.com/{owner}/{repo}/labels` (or click on the "Labels" tab in the issues or PRs page) +* GitLab : go to `https://gitlab.com/{owner}/{repo}/-/labels` (or click on "Manage" -> "Labels" on the left menu) + +Now add/edit the custom labels. they should be formatted as follows: * Label name: The name of the custom label. * Description: Start the description of with prefix `pr_agent:`, for example: `pr_agent: Description of when AI should suggest this label`.
-The description should be comprehensive and detailed, indicating when to add the desired label. + +The description should be comprehensive and detailed, indicating when to add the desired label. For example: -c. Now the custom labels will be included in the `generate_labels` tool. - -*This feature is supported in GitHub and GitLab. - + ### Configuration options +To edit [configurations](./../pr_agent/settings/configuration.toml#L28) related to the describe tool, use the following template: -Under the section 'pr_description', the [configuration file](./../pr_agent/settings/configuration.toml#L28) contains options to customize the 'describe' tool: +``` +/describe --pr_description.some_config1=... --pr_description.some_config2=... +``` +**Possible configurations:** - `publish_labels`: if set to true, the tool will publish the labels to the PR. Default is true. - `publish_description_as_comment`: if set to true, the tool will publish the description as a comment to the PR. If false, it will overwrite the origianl description. Default is false. @@ -52,13 +57,15 @@ Under the section 'pr_description', the [configuration file](./../pr_agent/setti - `collapsible_file_list`: if set to true, the file list in the "Changes walkthrough" section will be collapsible. If set to "adaptive", the file list will be collapsible only if there are more than 8 files. Default is "adaptive". ### Markers template - +To enable markers, set `pr_description.use_description_markers=true`. markers enable to easily integrate user's content and auto-generated content, with a template-like mechanism. For example, if the PR original description was: ``` User content... +## PR Type: +pr_agent:type ## PR Description: pr_agent:summary @@ -66,13 +73,7 @@ pr_agent:summary ## PR Walkthrough: pr_agent:walkthrough ``` -The marker `pr_agent:summary` will be replaced with the PR summary, and `pr_agent:walkthrough` will be replaced with the PR walkthrough. - -##### Example: -``` - env: - pr_description.use_description_markers: 'true' -``` +The marker `pr_agent:type` will be replaced with the PR type, `pr_agent:summary` will be replaced with the PR summary, and `pr_agent:walkthrough` will be replaced with the PR walkthrough. @@ -84,3 +85,28 @@ The marker `pr_agent:summary` will be replaced with the PR summary, and `pr_agen - `use_description_markers`: if set to true, the tool will use markers template. It replaces every marker of the form `pr_agent:marker_name` with the relevant content. Default is false. - `include_generated_by_header`: if set to true, the tool will add a dedicated header: 'Generated by PR Agent at ...' to any automatic content. Default is true. + + +## Usage Tips +- When you first install the app, the [default mode](https://github.com/Codium-ai/pr-agent/blob/main/Usage.md#github-app-automatic-tools) for the describe tool is: +``` +pr_commands = ["describe --pr_description.add_original_user_description=true --pr_description.keep_original_user_title=true", ...] +``` +meaning the `describe` tool will run automatically on every PR, will keep the original title, and will add the original user description above the generated description.
This default is quite conservative, and strikes a good balance between automation and control: +If you want more automation, just give the PR a title, and the tool will auto-write a full description; If you want more control, you can add a detailed description, and the tool will add the complementary description below it. +- For maximal automation, you can change the default mode to: +``` +pr_commands = ["describe --pr_description.add_original_user_description=false --pr_description.keep_original_user_title=true", ...] +``` +so the title will be auto-generated as well. +- Markers are an alternative way to control the generated description, to give maximal control to the user. If you set: +``` +pr_commands = ["describe --pr_description.use_description_markers=true", ...] +``` +the tool will replace every marker of the form `pr_agent:marker_name` in the PR description with the relevant content, where `marker_name` is one of the following: + - `type`: the PR type. + - `summary`: the PR summary. + - `walkthrough`: the PR walkthrough. + +Note that when markers are enabled, if the original PR description does not contain any markers, the tool will not alter the description at all. + diff --git a/pr_agent/settings/configuration.toml b/pr_agent/settings/configuration.toml index 8048443f..51984bae 100644 --- a/pr_agent/settings/configuration.toml +++ b/pr_agent/settings/configuration.toml @@ -111,7 +111,7 @@ duplicate_requests_cache_ttl = 60 # in seconds handle_pr_actions = ['opened', 'reopened', 'ready_for_review', 'review_requested'] pr_commands = [ "/describe --pr_description.add_original_user_description=true --pr_description.keep_original_user_title=true", - "/auto_review", + "/review", ] # settings for "pull_request" event with "synchronize" action - used to detect and handle push triggers for new commits handle_push_trigger = false diff --git a/pr_agent/settings/pr_description_prompts.toml b/pr_agent/settings/pr_description_prompts.toml index be4f70a0..2b0664b9 100644 --- a/pr_agent/settings/pr_description_prompts.toml +++ b/pr_agent/settings/pr_description_prompts.toml @@ -44,7 +44,7 @@ Class FileDescription(BaseModel): {%- endif %} Class PRDescription(BaseModel): - type: List[PRType] = Field(description="one or more types that describe the PR content. Return the label value, not the name.") + type: List[PRType] = Field(description="one or more types that describe the PR content. Return the label member value (e.g. 'Bug fix', not 'bug_fix')") {%- if enable_semantic_files_types %} pr_files[List[FileDescription]] = Field(max_items=15, description="a list of the files in the PR, and their changes summary.") {%- endif %}