diff --git a/README.md b/README.md index af0b5af2..5f886e87 100644 --- a/README.md +++ b/README.md @@ -17,22 +17,24 @@ Making pull requests less painful with an AI agent CodiumAI `PR-Agent` is an open-source tool aiming to help developers review pull requests faster and more efficiently. It automatically analyzes the pull request and can provide several types of commands: -‣ **Auto Description (`/describe`)**: Automatically generating [PR description](https://github.com/Codium-ai/pr-agent/pull/229#issue-1860711415) - title, type, summary, code walkthrough and labels. +‣ **Auto Description ([`/describe`](./docs/DESCRIBE.md))**: Automatically generating PR description - title, type, summary, code walkthrough and labels. \ -‣ **Auto Review (`/review`)**: [Adjustable feedback](https://github.com/Codium-ai/pr-agent/pull/229#issuecomment-1695022908) about the PR main theme, type, relevant tests, security issues, score, and various suggestions for the PR content. +‣ **Auto Review ([`/review`](./docs/REVIEW.md))**: Adjustable feedback about the PR main theme, type, relevant tests, security issues, score, and various suggestions for the PR content. \ -‣ **Question Answering (`/ask ...`)**: Answering [free-text questions](https://github.com/Codium-ai/pr-agent/pull/229#issuecomment-1695021332) about the PR. +‣ **Question Answering ([`/ask ...`](./docs/ASK.md))**: Answering free-text questions about the PR. \ -‣ **Code Suggestions (`/improve`)**: [Committable code suggestions](https://github.com/Codium-ai/pr-agent/pull/229#discussion_r1306919276) for improving the PR. +‣ **Code Suggestions ([`/improve`](./docs/IMPROVE.md))**: Committable code suggestions for improving the PR. \ -‣ **Update Changelog (`/update_changelog`)**: Automatically updating the CHANGELOG.md file with the [PR changes](https://github.com/Codium-ai/pr-agent/pull/168#discussion_r1282077645). +‣ **Update Changelog ([`/update_changelog`](./docs/UPDATE_CHANGELOG.md))**: Automatically updating the CHANGELOG.md file with the PR changes. \ -‣ **Find similar issue (`/similar_issue`)**: Automatically retrieves and presents [similar issues](https://github.com/Alibaba-MIIL/ASL/issues/107). +‣ **Find similar issue ([`/similar_issue`](./docs/SIMILAR_ISSUE.md))**: Automatically retrieves and presents similar issues -See the [usage guide](./Usage.md) for instructions how to run the different tools from [CLI](./Usage.md#working-from-a-local-repo-cli), or by [online usage](./Usage.md#online-usage), as well as additional details on optional commands and configurations. +See the [Usage Guide](./Usage.md) for instructions how to run the different tools from _CLI_, _online usage_, Or by _automatically triggering_ them when a new PR is opened. -[Release notes](./RELEASE_NOTES.md) +See the [Tools Guide](./docs/TOOLS_GUIDE.md) for detailed description of the different tools. + +See the [Release notes](./RELEASE_NOTES.md) for updates on the latest changes.

Example results:

diff --git a/Usage.md b/Usage.md index 7f6fcb9b..fcef2412 100644 --- a/Usage.md +++ b/Usage.md @@ -1,4 +1,4 @@ -## Usage guide +## Usage Guide ### Table of Contents - [Introduction](#introduction) @@ -15,7 +15,7 @@ There are 3 basic ways to invoke CodiumAI PR-Agent: 2. Online usage - by [commenting](https://github.com/Codium-ai/pr-agent/pull/229#issuecomment-1695021901) on a PR 3. Enabling PR-Agent tools to run automatically when a new PR is opened -See the [installation guide](/INSTALL.md) for instructions on how to setup your own PR-Agent. +See the **[installation guide](/INSTALL.md)** for instructions on how to setup your own PR-Agent. Specifically, CLI commands can be issued by invoking a pre-built [docker image](/INSTALL.md#running-from-source), or by invoking a [locally cloned repo](INSTALL.md#method-2-run-from-source). @@ -261,26 +261,4 @@ And use the following settings (you have to replace the values) in .secrets.toml [azure_devops] org = "https://dev.azure.com/YOUR_ORGANIZATION/" pat = "YOUR_PAT_TOKEN" -``` - -#### Similar issue tool - -[Example usage](https://github.com/Alibaba-MIIL/ASL/issues/107) - - - -To enable usage of the '**similar issue**' tool, you need to set the following keys in `.secrets.toml` (or in the relevant environment variables): -``` -[pinecone] -api_key = "..." -environment = "..." -``` -These parameters can be obtained by registering to [Pinecone](https://app.pinecone.io/?sessionType=signup/). - -- To invoke the 'similar issue' tool from **CLI**, run: -`python3 cli.py --issue_url=... similar_issue` - -- To invoke the 'similar' issue tool via online usage, [comment](https://github.com/Codium-ai/pr-agent/issues/178#issuecomment-1716934893) on a PR: -`/similar_issue` - -- You can also enable the 'similar issue' tool to run automatically when a new issue is opened, by adding it to the [pr_commands list in the github_app section](https://github.com/Codium-ai/pr-agent/blob/main/pr_agent/settings/configuration.toml#L66) +``` \ No newline at end of file diff --git a/docs/ASK.md b/docs/ASK.md new file mode 100644 index 00000000..9ac737e5 --- /dev/null +++ b/docs/ASK.md @@ -0,0 +1,11 @@ +# ASK Tool + +The `ask` tool answers questions about the PR, based on the PR code changes. +It can be invoked manually by commenting on any PR: +``` +/ask "..." +``` +For example: + + + \ No newline at end of file diff --git a/docs/DESCRIBE.md b/docs/DESCRIBE.md new file mode 100644 index 00000000..bb07668c --- /dev/null +++ b/docs/DESCRIBE.md @@ -0,0 +1,51 @@ +# Describe Tool + +The `describe` tool scans the PR code changes, and automatically generates PR description - title, type, summary, code walkthrough and labels. +It can be invoked manually by commenting on any PR: +``` +/describe +``` +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) + +### Configuration options + +Under the section 'pr_description', the [configuration file](./../pr_agent/settings/configuration.toml#L28) contains options to customize the 'describe' tool: + +- `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. + +- `add_original_user_description`: if set to true, the tool will add the original user description to the generated description. Default is false. + +- `add_original_user_title`: if set to true, the tool will keep the original PR title, and won't change it. Default is false. + +- `extra_instructions`: Optional extra instructions to the tool. For example: "focus on the changes in the file X. Ignore change in ...". + +#### Markers template + +markers enable to easily integrate user's content and auto-generated content, with a template-like mechanism. + +- `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. + +For example, if the PR original description was: +``` +User content... + +## PR Type: +pr_agent:pr_type + +## PR Description: +pr_agent:summary + +## PR Walkthrough: +pr_agent:walkthrough +``` +The marker `pr_agent:pr_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. + +- `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. \ No newline at end of file diff --git a/docs/IMPROVE.md b/docs/IMPROVE.md new file mode 100644 index 00000000..73682c1b --- /dev/null +++ b/docs/IMPROVE.md @@ -0,0 +1,34 @@ +# Describe Tool + +The `improve` tool scans the PR code changes, and automatically generate committable suggestions for improving the PR code. +It can be invoked manually by commenting on any PR: +``` +/improve +``` +For example: + + + + +The `improve` 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) + +An extended mode, which does not involve PR Compression and provides more comprehensive suggestions, can be invoked by commenting on any PR: +``` +/improve --extended +``` +Note that the extended mode divides the PR code changes into chunks, up to the token limits, where each chunk is handled separately (multiple calls to GPT-4). +Hence, the total number of suggestions is proportional to the number of chunks, i.e. the size of the PR. + +### Configuration options + +Under the section 'pr_code_suggestions', the [configuration file](./../pr_agent/settings/configuration.toml#L40) contains options to customize the 'improve' tool: + +- `num_code_suggestions`: number of code suggestions provided by the 'improve' tool. Default is 4. +- `extra_instructions`: Optional extra instructions to the tool. For example: "focus on the changes in the file X. Ignore change in ...". +- `rank_suggestions`: if set to true, the tool will rank the suggestions, based on importance. Default is false. + +#### params for '/improve --extended' mode +- `num_code_suggestions_per_chunk`: number of code suggestions provided by the 'improve' tool, per chunk. Default is 8. +- `rank_extended_suggestions`: if set to true, the tool will rank the suggestions, based on importance. Default is true. +- `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. \ No newline at end of file diff --git a/docs/REVIEW.md b/docs/REVIEW.md new file mode 100644 index 00000000..6312a19c --- /dev/null +++ b/docs/REVIEW.md @@ -0,0 +1,38 @@ +# Describe Tool + +The `review` tool scans the PR code changes, and automatically generates a PR review. +It can be invoked manually by commenting on any PR: +``` +/review +``` +For example: + + + + +The `review` 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) + +### Configuration options + +Under the section 'pr_reviewer', the [configuration file](./../pr_agent/settings/configuration.toml#L16) contains options to customize the 'review' tool: + +- `require_focused_review`: if set to true, the tool will add a section - 'is the PR a focused one'. 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_security_review`: if set to true, the tool will add a section that checks if the PR contains security issues. Default is true. +- `require_estimate_effort_to_review`: if set to true, the tool will add a section that estimates thed effort needed to review the PR. Default is true. +- `num_code_suggestions`: number of code suggestions provided by the 'review' tool. Default is 4. +- `inline_code_comments`: if set to true, the tool will publish the code suggestions as comments on the code diff. Default is false. +- `automatic_review`: if set to false, no automatic reviews will be done. Default is true. +- `extra_instructions`: Optional extra instructions to the tool. For example: "focus on the changes in the file X. Ignore change in ...". + +#### PR Reflection +By invoking: +``` +/reflect_and_review +``` +The tool will first ask the author questions about the PR, and will guide the review based on his answers. + + + + \ No newline at end of file diff --git a/docs/SIMILAR_ISSUE.md b/docs/SIMILAR_ISSUE.md new file mode 100644 index 00000000..695ef459 --- /dev/null +++ b/docs/SIMILAR_ISSUE.md @@ -0,0 +1,31 @@ +# Similar Issue Tool +The similar issue tool retrieves the most similar issues to the current issue. +It can be invoked manually by commenting on any PR: +``` +/similar_issue +``` +For example: + + + + + +Note that to perform retrieval, the `similar_issue` tool indexes all the repo previous issues (once). + +To enable usage of the '**similar issue**' tool, you need to set the following keys in `.secrets.toml` (or in the relevant environment variables): +``` +[pinecone] +api_key = "..." +environment = "..." +``` +These parameters can be obtained by registering to [Pinecone](https://app.pinecone.io/?sessionType=signup/). + + +### How to use: +- To invoke the 'similar issue' tool from **CLI**, run: +`python3 cli.py --issue_url=... similar_issue` + +- To invoke the 'similar' issue tool via online usage, [comment](https://github.com/Codium-ai/pr-agent/issues/178#issuecomment-1716934893) on a PR: +`/similar_issue` + +- You can also enable the 'similar issue' tool to run automatically when a new issue is opened, by adding it to the [pr_commands list in the github_app section](https://github.com/Codium-ai/pr-agent/blob/main/pr_agent/settings/configuration.toml#L66) diff --git a/docs/TOOLS_GUIDE.md b/docs/TOOLS_GUIDE.md new file mode 100644 index 00000000..65e17ea9 --- /dev/null +++ b/docs/TOOLS_GUIDE.md @@ -0,0 +1,9 @@ +## Tools Guide +- [DESCRIBE](./DESCRIBE.md) +- [REVIEW](./REVIEW.md) +- [IMPROVE](./IMPROVE.md) +- [ASK](./ASK.md) +- [SIMILAR_ISSUE](./SIMILAR_ISSUE.md) +- [UPDATE CHANGELOG](./UPDATE_CHANGELOG.md) + +See the **[installation guide](/INSTALL.md)** for instructions on how to setup your own PR-Agent. \ No newline at end of file diff --git a/docs/UPDATE_CHANGELOG.md b/docs/UPDATE_CHANGELOG.md new file mode 100644 index 00000000..3491feeb --- /dev/null +++ b/docs/UPDATE_CHANGELOG.md @@ -0,0 +1,19 @@ +# Update Changelog Tool + +The `update_changelog` tool automatically updates the CHANGELOG.md file with the PR changes. +It can be invoked manually by commenting on any PR: +``` +/update_changelog +``` +For example: + + + + + +### Configuration options + +Under the section 'pr_update_changelog', the [configuration file](./../pr_agent/settings/configuration.toml#L50) contains options to customize the 'update changelog' tool: + +- `push_changelog_changes`: whether to push the changes to CHANGELOG.md, or just print them. Default is false (print only). +- `extra_instructions`: Optional extra instructions to the tool. For example: "focus on the changes in the file X. Ignore change in ... \ No newline at end of file diff --git a/pics/ask.png b/pics/ask.png new file mode 100644 index 00000000..4923829c Binary files /dev/null and b/pics/ask.png differ diff --git a/pics/ask_comment.png b/pics/ask_comment.png new file mode 100644 index 00000000..a9d0204d Binary files /dev/null and b/pics/ask_comment.png differ diff --git a/pics/describe.png b/pics/describe.png new file mode 100644 index 00000000..06ad2a6e Binary files /dev/null and b/pics/describe.png differ diff --git a/pics/describe_comment.png b/pics/describe_comment.png new file mode 100644 index 00000000..952c63ec Binary files /dev/null and b/pics/describe_comment.png differ diff --git a/pics/improve.png b/pics/improve.png new file mode 100644 index 00000000..1442a63b Binary files /dev/null and b/pics/improve.png differ diff --git a/pics/improve_comment.png b/pics/improve_comment.png new file mode 100644 index 00000000..3438a4ba Binary files /dev/null and b/pics/improve_comment.png differ diff --git a/pics/reflection_answers.png b/pics/reflection_answers.png new file mode 100644 index 00000000..2a08e0ab Binary files /dev/null and b/pics/reflection_answers.png differ diff --git a/pics/reflection_insights.png b/pics/reflection_insights.png new file mode 100644 index 00000000..c8e06d08 Binary files /dev/null and b/pics/reflection_insights.png differ diff --git a/pics/reflection_questions.png b/pics/reflection_questions.png new file mode 100644 index 00000000..4512a8a9 Binary files /dev/null and b/pics/reflection_questions.png differ diff --git a/pics/review.png b/pics/review.png new file mode 100644 index 00000000..51262f97 Binary files /dev/null and b/pics/review.png differ diff --git a/pics/review_comment.png b/pics/review_comment.png new file mode 100644 index 00000000..e314dcc4 Binary files /dev/null and b/pics/review_comment.png differ diff --git a/pics/similar_issue.png b/pics/similar_issue.png new file mode 100644 index 00000000..923fe97a Binary files /dev/null and b/pics/similar_issue.png differ diff --git a/pics/similar_issue_comment.png b/pics/similar_issue_comment.png new file mode 100644 index 00000000..0e8d2efc Binary files /dev/null and b/pics/similar_issue_comment.png differ diff --git a/pics/similar_issue_original_issue.png b/pics/similar_issue_original_issue.png new file mode 100644 index 00000000..b133a872 Binary files /dev/null and b/pics/similar_issue_original_issue.png differ diff --git a/pics/similar_issue_tool.png b/pics/similar_issue_tool.png deleted file mode 100644 index 4ec51c81..00000000 Binary files a/pics/similar_issue_tool.png and /dev/null differ diff --git a/pics/update_changelog.png b/pics/update_changelog.png new file mode 100644 index 00000000..dd959d9b Binary files /dev/null and b/pics/update_changelog.png differ diff --git a/pics/update_changelog_comment.png b/pics/update_changelog_comment.png new file mode 100644 index 00000000..52caf585 Binary files /dev/null and b/pics/update_changelog_comment.png differ diff --git a/pr_agent/agent/pr_agent.py b/pr_agent/agent/pr_agent.py index 07c34c51..11db4dec 100644 --- a/pr_agent/agent/pr_agent.py +++ b/pr_agent/agent/pr_agent.py @@ -67,8 +67,8 @@ class PRAgent: args = update_settings_from_args(args) action = action.lstrip("/").lower() - if action == "reflect_and_review" and not get_settings().pr_reviewer.ask_and_reflect: - action = "review" + if action == "reflect_and_review": + get_settings().pr_reviewer.ask_and_reflect = True if action == "answer": if notify: notify()