From 7563af08a03a45f9598a4cf3d80bc22aa5fc438e Mon Sep 17 00:00:00 2001 From: mrT23 Date: Thu, 18 Apr 2024 08:44:08 +0300 Subject: [PATCH 1/3] docs --- docs/docs/tools/describe.md | 32 ++++++++----------- .../docs/usage-guide/automations_and_usage.md | 14 ++++---- pr_agent/servers/github_app.py | 2 +- pr_agent/servers/help.py | 4 +-- pr_agent/settings/configuration.toml | 6 ++-- 5 files changed, 26 insertions(+), 32 deletions(-) diff --git a/docs/docs/tools/describe.md b/docs/docs/tools/describe.md index 80e2adb44..dee6f2043 100644 --- a/docs/docs/tools/describe.md +++ b/docs/docs/tools/describe.md @@ -168,24 +168,18 @@ The description should be comprehensive and detailed, indicating when to add the !!! tip "Automation" - When you first install PR-Agent app, the [default mode](../usage-guide/automations_and_usage.md#github-app) for the describe tool is: ``` - pr_commands = ["/describe --pr_description.add_original_user_description=true ..."] + pr_commands = ["/describe", ...] ``` - meaning the `describe` tool will run automatically on every PR, and will add the original user description above the generated description. -
This default settings aim to strike 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.generate_ai_tile=true", ...] - ``` - so the title of the PR 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. + meaning the `describe` tool will run automatically on every PR, with the default configurations. + + + - 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. + - 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/docs/docs/usage-guide/automations_and_usage.md b/docs/docs/usage-guide/automations_and_usage.md index a69c08512..aa9697554 100644 --- a/docs/docs/usage-guide/automations_and_usage.md +++ b/docs/docs/usage-guide/automations_and_usage.md @@ -62,21 +62,21 @@ The configuration parameter `pr_commands` defines the list of tools that will be ``` [github_app] pr_commands = [ - "/describe --pr_description.add_original_user_description=true --pr_description.final_update_message=false", + "/describe --pr_description.final_update_message=false", "/review --pr_reviewer.num_code_suggestions=0", "/improve", ] ``` This means that when a new PR is opened/reopened or marked as ready for review, PR-Agent will run the `describe`, `review` and `improve` tools. -For the `describe` tool, for example, the `add_original_user_description` parameter will be set to true. +For the `review` tool, for example, the `num_code_suggestions` parameter will be set to 0. You can override the default tool parameters by using one the three options for a [configuration file](https://codium-ai.github.io/Docs-PR-Agent/usage-guide/#configuration-options): **wiki**, **local**, or **global**. For example, if your local `.pr_agent.toml` file contains: ``` [pr_description] -add_original_user_description = false +generate_ai_title = true ``` -When a new PR is opened, PR-Agent will run the `describe` tool with the above parameters. +Every time you run the `describe` tool, including automatic runs, the PR title will be generated by the AI. To cancel the automatic run of all the tools, set: ``` @@ -101,7 +101,7 @@ The configuration parameter `push_commands` defines the list of tools that will [github_app] handle_push_trigger = true push_commands = [ - "/describe --pr_description.add_original_user_description=true", + "/describe", "/review --pr_reviewer.num_code_suggestions=0 --pr_reviewer.final_update_message=false", ] ``` @@ -141,7 +141,7 @@ After setting up a GitLab webhook, to control which commands will run automatica ``` [gitlab] pr_commands = [ - "/describe --pr_description.add_original_user_description=true", + "/describe", "/review --pr_reviewer.num_code_suggestions=0", "/improve", ] @@ -201,7 +201,7 @@ To control which commands will run automatically when a new PR is opened, you ca ``` [azure_devops_server] pr_commands = [ - "/describe --pr_description.add_original_user_description=true", + "/describe", "/review --pr_reviewer.num_code_suggestions=0", "/improve", ] diff --git a/pr_agent/servers/github_app.py b/pr_agent/servers/github_app.py index f0d1340dd..be1410848 100644 --- a/pr_agent/servers/github_app.py +++ b/pr_agent/servers/github_app.py @@ -140,7 +140,7 @@ async def handle_new_pr_opened(body: Dict[str, Any], if not (pull_request and api_url): get_logger().info(f"Invalid PR event: {action=} {api_url=}") return {} - if action in get_settings().github_app.handle_pr_actions: # ['opened', 'reopened', 'ready_for_review', 'review_requested'] + if action in get_settings().github_app.handle_pr_actions: # ['opened', 'reopened', 'ready_for_review'] if get_identity_provider().verify_eligibility("github", sender_id, api_url) is not Eligibility.NOT_ELIGIBLE: await _perform_auto_commands_github("pr_commands", agent, body, api_url, log_context) else: diff --git a/pr_agent/servers/help.py b/pr_agent/servers/help.py index b37cedc3b..07ade44c6 100644 --- a/pr_agent/servers/help.py +++ b/pr_agent/servers/help.py @@ -68,9 +68,9 @@ def get_describe_usage_guide(): output += """\ - When you first install the app, the [default mode](https://pr-agent-docs.codium.ai/usage-guide/automations_and_usage/#github-app-automatic-tools-when-a-new-pr-is-opened) for the describe tool is: ``` -pr_commands = ["/describe --pr_description.add_original_user_description=true ..."] +pr_commands = ["/describe", ...] ``` -meaning the `describe` tool will run automatically on every PR, and will add the original user description above the generated description. +meaning the `describe` tool will run automatically on every PR. - Markers are an alternative way to control the generated description, to give maximal control to the user. If you set: ``` diff --git a/pr_agent/settings/configuration.toml b/pr_agent/settings/configuration.toml index bd85b0fe8..22ed6ccc0 100644 --- a/pr_agent/settings/configuration.toml +++ b/pr_agent/settings/configuration.toml @@ -148,7 +148,7 @@ override_deployment_type = true # settings for "pull_request" event handle_pr_actions = ['opened', 'reopened', 'ready_for_review'] pr_commands = [ - "/describe --pr_description.add_original_user_description=true", + "/describe", "/review --pr_reviewer.num_code_suggestions=0", "/improve", ] @@ -160,7 +160,7 @@ push_trigger_wait_for_initial_review = true push_trigger_pending_tasks_backlog = true push_trigger_pending_tasks_ttl = 300 push_commands = [ - "/describe --pr_description.add_original_user_description=true", + "/describe", "/review --pr_reviewer.num_code_suggestions=0", ] ignore_pr_title = [] @@ -169,7 +169,7 @@ ignore_bot_pr = true [gitlab] url = "https://gitlab.com" # URL to the gitlab service pr_commands = [ - "/describe --pr_description.add_original_user_description=true", + "/describe", "/review --pr_reviewer.num_code_suggestions=0", "/improve", ] From f913f02ea6d5069d9f3b668777ab6f61854fa49b Mon Sep 17 00:00:00 2001 From: mrT23 Date: Thu, 18 Apr 2024 08:53:43 +0300 Subject: [PATCH 2/3] docs --- docs/docs/tools/describe.md | 6 ++-- docs/docs/tools/improve.md | 64 ++++++++++++++++++++++++++----------- docs/docs/tools/review.md | 6 ++-- 3 files changed, 51 insertions(+), 25 deletions(-) diff --git a/docs/docs/tools/describe.md b/docs/docs/tools/describe.md index dee6f2043..756c6adc2 100644 --- a/docs/docs/tools/describe.md +++ b/docs/docs/tools/describe.md @@ -8,7 +8,7 @@ The tool can be triggered automatically every time a new PR is [opened](../usage ## Example usage -### Manual invocation +### Manual triggering Invoke the tool manually by commenting `/describe` on any PR: @@ -23,7 +23,7 @@ If you want to edit [configurations](#configuration-options), add the relevant o /describe --pr_description.some_config1=... --pr_description.some_config2=... ``` -### Automatic invocation +### Automatic triggering To run the `describe` automatically when a PR is opened, define in a [configuration file](https://pr-agent-docs.codium.ai/usage-guide/configuration_options/#wiki-configuration-file): ``` @@ -39,7 +39,7 @@ publish_labels = ... ``` - The `pr_commands` lists commands that will be executed automatically when a PR is opened. -- The `[pr_description]` section contains the configurations for the `describe` tool you want to edit. +- The `[pr_description]` section contains the configurations for the `describe` tool you want to edit (if any). ## Configuration options diff --git a/docs/docs/tools/improve.md b/docs/docs/tools/improve.md index 2869b1803..af4eae78e 100644 --- a/docs/docs/tools/improve.md +++ b/docs/docs/tools/improve.md @@ -5,43 +5,51 @@ The tool can be triggered automatically every time a new PR is [opened](../usage /improve ``` -### Summarized vs committable code suggestions +## Example usage -The code suggestions can be presented as a single comment +### Manual triggering + +Invoke the tool manually by commenting `/improve` on any PR. The code suggestions by default are presented as a single comment: ![code suggestions as comment](https://codium.ai/images/pr_agent/code_suggestions_as_comment.png){width=512} -Or as a separate commitable code comment for each suggestion (via `pr_code_suggestions.commitable_code_suggestions=true`):: +To edit [configurations](#configuration-options) related to the improve tool, use the following template: +``` +/improve --pr_code_suggestions.some_config1=... --pr_code_suggestions.some_config2=... +``` + +For example, you can choose to present the suggestions as commitable code comments, by running the following command: +``` +/improve --pr_code_suggestions.commitable_code_suggestions=true +``` -![imporove](https://codium.ai/images/pr_agent/improve.png){width=512} +![improve](https://codium.ai/images/pr_agent/improve.png){width=512} Note that a single comment has a significantly smaller PR footprint. We recommend this mode for most cases. Also note that collapsible are not supported in _Bitbucket_. Hence, the suggestions are presented there as code comments. -### Extended mode +### Automatic triggering -An extended mode, which does not involve PR Compression and provides more comprehensive suggestions, can be invoked by commenting on any PR: -``` -/improve --extended +To run the `improve` automatically when a PR is opened, define in a [configuration file](https://pr-agent-docs.codium.ai/usage-guide/configuration_options/#wiki-configuration-file): ``` +[github_app] +pr_commands = [ + "/improve", + ... +] -or by setting: -``` [pr_code_suggestions] -auto_extended_mode=true +num_code_suggestions = ... +... ``` -(True by default). -Note that the extended mode divides the PR code changes into chunks, up to the token limits, where each chunk is handled separately (might use multiple calls to GPT-4 for large PRs). -Hence, the total number of suggestions is proportional to the number of chunks, i.e., the size of the PR. +- The `pr_commands` lists commands that will be executed automatically when a PR is opened. +- The `[pr_code_suggestions]` section contains the configurations for the `improve` tool you want to edit (if any) -### Configuration options -To edit [configurations](https://github.com/Codium-ai/pr-agent/blob/main/pr_agent/settings/configuration.toml#L66) related to the improve tool (`pr_code_suggestions` section), use the following template: -``` -/improve --pr_code_suggestions.some_config1=... --pr_code_suggestions.some_config2=... -``` + +## Configuration options !!! example "General options" @@ -60,6 +68,24 @@ To edit [configurations](https://github.com/Codium-ai/pr-agent/blob/main/pr_agen - `max_number_of_calls`: maximum number of chunks. Default is 5. - `final_clip_factor`: factor to remove suggestions with low confidence. Default is 0.9.; +## Extended mode + +An extended mode, which does not involve PR Compression and provides more comprehensive suggestions, can be invoked by commenting on any PR: +``` +/improve --extended +``` + +or by setting: +``` +[pr_code_suggestions] +auto_extended_mode=true +``` +(True by default). + +Note that the extended mode divides the PR code changes into chunks, up to the token limits, where each chunk is handled separately (might use multiple calls to GPT-4 for large PRs). +Hence, the total number of suggestions is proportional to the number of chunks, i.e., the size of the PR. + + ## Usage Tips diff --git a/docs/docs/tools/review.md b/docs/docs/tools/review.md index 92a642f42..4c65c7b87 100644 --- a/docs/docs/tools/review.md +++ b/docs/docs/tools/review.md @@ -7,7 +7,7 @@ The tool can be triggered automatically every time a new PR is [opened](../usage ## Example usage -### Manual invocation +### Manual triggering Invoke the tool manually by commenting `/review` on any PR: @@ -22,7 +22,7 @@ If you want to edit [configurations](#configuration-options), add the relevant o /review --pr_reviewer.some_config1=... --pr_reviewer.some_config2=... ``` -### Automatic invocation +### Automatic triggering To run the `review` automatically when a PR is opened, define in a [configuration file](https://pr-agent-docs.codium.ai/usage-guide/configuration_options/#wiki-configuration-file): ``` @@ -38,7 +38,7 @@ num_code_suggestions = ... ``` - The `pr_commands` lists commands that will be executed automatically when a PR is opened. -- The `[pr_reviewer]` section contains the configurations for the `review` tool you want to edit. +- The `[pr_reviewer]` section contains the configurations for the `review` tool you want to edit (if any). ## Configuration options From 0f99db65a9f05a9fe3344c2966d9d074ef454fe3 Mon Sep 17 00:00:00 2001 From: mrT23 Date: Thu, 18 Apr 2024 09:10:14 +0300 Subject: [PATCH 3/3] docs --- docs/docs/tools/ask.md | 3 ++- docs/docs/tools/review.md | 30 +++++++++++++++--------------- 2 files changed, 17 insertions(+), 16 deletions(-) diff --git a/docs/docs/tools/ask.md b/docs/docs/tools/ask.md index 0d477934b..fca5b7254 100644 --- a/docs/docs/tools/ask.md +++ b/docs/docs/tools/ask.md @@ -5,7 +5,8 @@ It can be invoked manually by commenting on any PR: ``` /ask "..." ``` -For example: + +## Example usage ![Ask Comment](https://codium.ai/images/pr_agent/ask_comment.png){width=512} diff --git a/docs/docs/tools/review.md b/docs/docs/tools/review.md index 4c65c7b87..2e5c4bb6a 100644 --- a/docs/docs/tools/review.md +++ b/docs/docs/tools/review.md @@ -46,38 +46,38 @@ num_code_suggestions = ... ### General configurations !!! example "General options" - - `num_code_suggestions`: number of code suggestions provided by the 'review' tool. For manual comments, default is 4. For [PR-Agent app](https://github.com/Codium-ai/pr-agent/blob/main/pr_agent/settings/configuration.toml#L142) auto tools, default is 0, meaning no code suggestions will be provided by the review tool, unless you manually edit `pr_commands`. - - `inline_code_comments`: if set to true, the tool will publish the code suggestions as comments on the code diff. Default is false. - - `persistent_comment`: if set to true, the review comment will be persistent, meaning that every new review request will edit the previous one. Default is true. - - `extra_instructions`: Optional extra instructions to the tool. For example: "focus on the changes in the file X. Ignore change in ...". - - `enable_help_text`: if set to true, the tool will display a help text in the comment. Default is true. + - `num_code_suggestions`: number of code suggestions provided by the 'review' tool. For manual comments, default is 4. For [PR-Agent app](https://github.com/Codium-ai/pr-agent/blob/main/pr_agent/settings/configuration.toml#L142) auto tools, default is 0, meaning no code suggestions will be provided by the review tool, unless you manually edit `pr_commands`. + - `inline_code_comments`: if set to true, the tool will publish the code suggestions as comments on the code diff. Default is false. + - `persistent_comment`: if set to true, the review comment will be persistent, meaning that every new review request will edit the previous one. Default is true. + - `extra_instructions`: Optional extra instructions to the tool. For example: "focus on the changes in the file X. Ignore change in ...". + - `enable_help_text`: if set to true, the tool will display a help text in the comment. Default is true. !!! example "Enable\\disable sub-sections" You can enable or disable specific sub-sections of the review tool: - - `require_score_review`: if set to true, the tool will add a section that scores the PR. Default is false. - - `require_tests_review`: if set to true, the tool will add a section that checks if the PR contains tests. Default is true. - - `require_estimate_effort_to_review`: if set to true, the tool will add a section that estimates the effort needed to review the PR. Default is true. - - `require_can_be_split_review`: if set to true, the tool will add a section that checks if the PR contains several themes, and can be split into smaller PRs. Default is false. + - `require_score_review`: if set to true, the tool will add a section that scores the PR. Default is false. + - `require_tests_review`: if set to true, the tool will add a section that checks if the PR contains tests. Default is true. + - `require_estimate_effort_to_review`: if set to true, the tool will add a section that estimates the effort needed to review the PR. Default is true. + - `require_can_be_split_review`: if set to true, the tool will add a section that checks if the PR contains several themes, and can be split into smaller PRs. Default is false. !!! example "SOC2 ticket compliance 💎" This sub-tool checks if the PR description properly contains a ticket to a project management system (e.g., Jira, Asana, Trello, etc.), as required by SOC2 compliance. If not, it will add a label to the PR: "Missing SOC2 ticket". - - `require_soc2_ticket`: If set to true, the SOC2 ticket checker sub-tool will be enabled. Default is false. - - `soc2_ticket_prompt`: The prompt for the SOC2 ticket review. Default is: `Does the PR description include a link to ticket in a project management system (e.g., Jira, Asana, Trello, etc.) ?`. Edit this field if your compliance requirements are different. + - `require_soc2_ticket`: If set to true, the SOC2 ticket checker sub-tool will be enabled. Default is false. + - `soc2_ticket_prompt`: The prompt for the SOC2 ticket review. Default is: `Does the PR description include a link to ticket in a project management system (e.g., Jira, Asana, Trello, etc.) ?`. Edit this field if your compliance requirements are different. !!! example "Adding PR labels" You can enable the tool to add specific labels to the PR: - - `enable_review_labels_security`: if set to true, the tool will publish a 'possible security issue' label if it detects a security issue. Default is true. - - `enable_review_labels_effort`: if set to true, the tool will publish a 'Review effort [1-5]: x' label. Default is true. + - `enable_review_labels_security`: if set to true, the tool will publish a 'possible security issue' label if it detects a security issue. Default is true. + - `enable_review_labels_effort`: if set to true, the tool will publish a 'Review effort [1-5]: x' label. Default is true. !!! example "Auto-approval" The review tool can approve a PR when a specific comment, `/review auto_approve` is invoked. - - `enable_auto_approval`: if set to true, the tool will approve the PR when invoked with the 'auto_approve' command. Default is false. This flag can be changed only from configuration file. - - `maximal_review_effort`: maximal effort level for auto-approval. If the PR's estimated review effort is above this threshold, the auto-approval will not run. Default is 5. + - `enable_auto_approval`: if set to true, the tool will approve the PR when invoked with the 'auto_approve' command. Default is false. This flag can be changed only from configuration file. + - `maximal_review_effort`: maximal effort level for auto-approval. If the PR's estimated review effort is above this threshold, the auto-approval will not run. Default is 5. ### Incremental Mode Incremental review only considers changes since the last PR-Agent review. This can be useful when working on the PR in an iterative manner, and you want to focus on the changes since the last review instead of reviewing the entire PR again.