Merge pull request #865 from Codium-ai/tr/readme

Tr/readme

.pr_agent.toml

@@ -4,4 +4,4 @@ enable_auto_approval = true
 
 
 [pr_code_suggestions]
-summarize=true
+commitable_code_suggestions=false

docs/docs/tools/describe.md

@@ -18,7 +18,7 @@ After ~30 seconds, the tool will generate a description for the PR:
 
 ![Describe New](https://codium.ai/images/pr_agent/describe_new.png){width=512}
 
-If you want to edit [configurations](https://github.com/Codium-ai/pr-agent/blob/main/pr_agent/settings/configuration.toml#L46), add the relevant ones to the command:
+If you want to edit [configurations](#configuration-options), add the relevant ones to the command:
 ```
 /describe --pr_description.some_config1=... --pr_description.some_config2=...
 ```
@@ -36,10 +36,9 @@ pr_commands = [
 [pr_description]
 publish_labels = ...
 ...
-
 ```
 
-- The `pr_commands` lists commands that will be executed on every PR.
+- 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.
 
 
@@ -57,7 +56,7 @@ publish_labels = ...
 
     - `add_original_user_description`: if set to true, the tool will add the original user description to the generated description. Default is true.
 
-    - `keep_original_user_title`: if set to true, the tool will keep the original PR title, and won't change it. Default is true.
+    - `generate_ai_title`: if set to true, the tool will also generate an AI title for the PR. Default is false.
 
     - `extra_instructions`: Optional extra instructions to the tool. For example: "focus on the changes in the file X. Ignore change in ...".
 
@@ -169,18 +168,17 @@ 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_description.keep_original_user_title=true", ...]
+    pr_commands = ["/describe --pr_description.add_original_user_description=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. 
+    meaning the `describe` tool will run automatically on every PR, and will add the original user description above the generated description. 
     <br> 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.keep_original_user_title=true", ...]
+                                 " --pr_description.generate_ai_tile=true", ...]
         ```
-        so the title will be auto-generated as well.
+        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", ...]

docs/docs/tools/improve.md

@@ -7,11 +7,11 @@ The tool can be triggered automatically every time a new PR is [opened](../usage
 
 ### Summarized vs committable code suggestions
 
-The code suggestions can be presented as a single comment (via `pr_code_suggestions.summarize=true`):
+The code suggestions can be 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:
+Or as a separate commitable code comment for each suggestion  (via `pr_code_suggestions.commitable_code_suggestions=true`)::
 
 ![imporove](https://codium.ai/images/pr_agent/improve.png){width=512}
 
@@ -58,7 +58,7 @@ To edit [configurations](https://github.com/Codium-ai/pr-agent/blob/main/pr_agen
     - `num_code_suggestions_per_chunk`: number of code suggestions provided by the 'improve' tool, per chunk. Default is 5.
     - `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.
+    - `final_clip_factor`: factor to remove suggestions with low confidence. Default is 0.9.;
 
 
 ## Usage Tips

docs/docs/tools/review.md

@@ -4,22 +4,47 @@ The tool can be triggered automatically every time a new PR is [opened](../usage
 ```
 /review
 ```
-For example:
 
-![review comment](https://codium.ai/images/pr_agent/review_comment.png){width=512}
+## Example usage
 
-![review](https://codium.ai/images/pr_agent/review3.png){width=512}
+### Manual invocation
 
+Invoke the tool manually by commenting `/review` on any PR:
 
-## Configuration options
+![review comment](https://codium.ai/images/pr_agent/review_comment.png){width=512}
 
-### General configurations
+After ~30 seconds, the tool will generate a review for the PR:
 
-To edit [configurations](https://github.com/Codium-ai/pr-agent/blob/main/pr_agent/settings/configuration.toml#L19)  related to the review tool (`pr_reviewer` section), use the following template:
+![review](https://codium.ai/images/pr_agent/review3.png){width=512}
+
+If you want to edit [configurations](#configuration-options), add the relevant ones to the command:
 ```
 /review --pr_reviewer.some_config1=... --pr_reviewer.some_config2=...
 ```
 
+### Automatic invocation
+
+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):
+```
+[github_app]
+pr_commands = [
+    "/review",
+    ...
+]
+
+[pr_reviewer]
+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.
+
+
+## Configuration options
+
+### 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.

docs/docs/usage-guide/automations_and_usage.md

@@ -62,20 +62,19 @@ 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.keep_original_user_title=true --pr_description.final_update_message=false",
+    "/describe --pr_description.add_original_user_description=true --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` and `keep_original_user_title` parameters will be set to true.
+For the `describe` tool, for example, the `add_original_user_description` parameter will be set to true.
 
 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
-keep_original_user_title = false
 ```
 When a new PR is opened, PR-Agent will run the `describe` tool with the above parameters.
 
@@ -102,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 --pr_description.keep_original_user_title=true",
+    "/describe --pr_description.add_original_user_description=true",
     "/review  --pr_reviewer.num_code_suggestions=0 --pr_reviewer.final_update_message=false",
 ]
 ```
@@ -142,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 --pr_description.keep_original_user_title=true",
+    "/describe --pr_description.add_original_user_description=true",
     "/review --pr_reviewer.num_code_suggestions=0",
     "/improve",
 ]
@@ -170,7 +169,7 @@ Specifically, set the following values:
 [bitbucket_app]
 pr_commands = [
     "/review --pr_reviewer.num_code_suggestions=0",
-    "/improve --pr_code_suggestions.summarize=false",
+    "/improve --pr_code_suggestions.commitable_code_suggestions=true",
 ]
 ```
 
@@ -202,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 --pr_description.keep_original_user_title=true",
+    "/describe --pr_description.add_original_user_description=true",
     "/review --pr_reviewer.num_code_suggestions=0",
     "/improve",
 ]

docs/docs/usage-guide/configuration_options.md

@@ -23,7 +23,7 @@ An example content:
 
 ```
 [pr_description]
-keep_original_user_title=false
+generate_ai_title=true
 ```
 
 PR-Agent will know to remove the triple-quotes when reading the configuration content.

pr_agent/servers/help.py

@@ -68,10 +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_description.keep_original_user_title=true", ...]
+pr_commands = ["/describe --pr_description.add_original_user_description=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. 
+meaning the `describe` tool will run automatically on every PR, and will add the original user description above the generated description. 
 
 - Markers are an alternative way to control the generated description, to give maximal control to the user. If you set:
 ```

pr_agent/settings/configuration.toml

@@ -53,7 +53,7 @@ maximal_review_effort=5
 [pr_description] # /describe #
 publish_labels=true
 add_original_user_description=true
-keep_original_user_title=true
+generate_ai_title=false
 use_bullet_points=true
 extra_instructions = ""
 enable_pr_type=true
@@ -80,7 +80,7 @@ enable_help_text=true
 [pr_code_suggestions] # /improve #
 max_context_tokens=8000
 num_code_suggestions=4
-summarize = true
+commitable_code_suggestions = false
 extra_instructions = ""
 rank_suggestions = false
 enable_help_text=true
@@ -148,9 +148,9 @@ 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 --pr_description.keep_original_user_title=true",
+    "/describe --pr_description.add_original_user_description=true",
     "/review --pr_reviewer.num_code_suggestions=0",
-    "/improve --pr_code_suggestions.summarize=true",
+    "/improve",
 ]
 # settings for "pull_request" event with "synchronize" action - used to detect and handle push triggers for new commits
 handle_push_trigger = false
@@ -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 --pr_description.keep_original_user_title=true",
+    "/describe --pr_description.add_original_user_description=true",
     "/review --pr_reviewer.num_code_suggestions=0",
 ]
 ignore_pr_title = []
@@ -169,15 +169,15 @@ ignore_bot_pr = true
 [gitlab]
 url = "https://gitlab.com" # URL to the gitlab service
 pr_commands = [
-    "/describe --pr_description.add_original_user_description=true --pr_description.keep_original_user_title=true",
+    "/describe --pr_description.add_original_user_description=true",
     "/review --pr_reviewer.num_code_suggestions=0",
-    "/improve --pr_code_suggestions.summarize=true",
+    "/improve",
 ]
 
 [bitbucket_app]
 pr_commands = [
     "/review --pr_reviewer.num_code_suggestions=0",
-    "/improve --pr_code_suggestions.summarize=false",
+    "/improve --pr_code_suggestions.commitable_code_suggestions=true",
 ]
 
 

pr_agent/tools/pr_code_suggestions.py

@@ -57,7 +57,7 @@ def __init__(self, pr_url: str, cli_mode=False, args: list = None,
             "language": self.main_language,
             "diff": "",  # empty diff for initial calculation
             "num_code_suggestions": num_code_suggestions,
-            "summarize_mode": get_settings().pr_code_suggestions.summarize,
+            "commitable_code_suggestions_mode": get_settings().pr_code_suggestions.commitable_code_suggestions,
             "extra_instructions": get_settings().pr_code_suggestions.extra_instructions,
             "commit_messages_str": self.git_provider.get_commit_messages(),
         }
@@ -105,7 +105,7 @@ async def run(self):
 
             if get_settings().config.publish_output:
                 self.git_provider.remove_initial_comment()
-                if get_settings().pr_code_suggestions.summarize and self.git_provider.is_supported("gfm_markdown"):
+                if (not get_settings().pr_code_suggestions.commitable_code_suggestions) and self.git_provider.is_supported("gfm_markdown"):
 
                     # generate summarized suggestions
                     pr_body = self.generate_summarized_suggestions(data)
@@ -197,7 +197,7 @@ def _prepare_pr_code_suggestions(self) -> Dict:
         one_sentence_summary_list = []
         for i, suggestion in enumerate(data['code_suggestions']):
             try:
-                if get_settings().pr_code_suggestions.summarize:
+                if not get_settings().pr_code_suggestions.commitable_code_suggestions:
                     if not suggestion or 'one_sentence_summary' not in suggestion or 'label' not in suggestion or 'relevant_file' not in suggestion:
                         get_logger().debug(f"Skipping suggestion {i + 1}, because it is invalid: {suggestion}")
                         continue
@@ -213,7 +213,7 @@ def _prepare_pr_code_suggestions(self) -> Dict:
                 if ('existing_code' in suggestion) and ('improved_code' in suggestion) and (
                         suggestion['existing_code'] != suggestion['improved_code']):
                     suggestion = self._truncate_if_needed(suggestion)
-                    if get_settings().pr_code_suggestions.summarize:
+                    if not get_settings().pr_code_suggestions.commitable_code_suggestions:
                         one_sentence_summary_list.append(suggestion['one_sentence_summary'])
                     suggestion_list.append(suggestion)
                 else:

pr_agent/tools/pr_description.py

@@ -301,7 +301,7 @@ def _prepare_pr_answer(self) -> Tuple[str, str, str, List[dict]]:
 
         # Remove the 'PR Title' key from the dictionary
         ai_title = self.data.pop('title', self.vars["title"])
-        if get_settings().pr_description.keep_original_user_title:
+        if (not get_settings().pr_description.generate_ai_title):
             # Assign the original PR title to the 'title' variable
             title = self.vars["title"]
         else: