+
+ | 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 original description. Default is false. |
+
+
+ | publish_description_as_comment_persistent |
+ If set to true and `publish_description_as_comment` is true, the tool will publish the description as a persistent comment to the PR. Default is true. |
+
+
+ | add_original_user_description |
+ If set to true, the tool will add the original user description to the generated description. 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 ..." |
+
+
+ | enable_pr_type |
+ If set to false, it will not show the `PR type` as a text value in the description content. Default is true. |
+
+
+ | final_update_message |
+ If set to true, it will add a comment message [`PR Description updated to latest commit...`](https://github.com/Codium-ai/pr-agent/pull/499#issuecomment-1837412176) after finishing calling `/describe`. Default is true. |
+
+
+ | enable_semantic_files_types |
+ If set to true, "Changes walkthrough" section will be generated. Default is true. |
+
+
+ | 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". |
+
+
+ | enable_help_text |
+ If set to true, the tool will display a help text in the comment. Default is false. |
+
+
- - `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 original description. Default is false.
- - `publish_description_as_comment_persistent`: if set to true and `publish_description_as_comment` is true, the tool will publish the description as a persistent comment to the PR. Default is true.
-
- - `add_original_user_description`: if set to true, the tool will add the original user description to the generated description. 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 ...".
-
- - To enable `custom labels`, apply the configuration changes described [here](./custom_labels.md#configuration-options)
-
- - `enable_pr_type`: if set to false, it will not show the `PR type` as a text value in the description content. Default is true.
-
- - `final_update_message`: if set to true, it will add a comment message [`PR Description updated to latest commit...`](https://github.com/Codium-ai/pr-agent/pull/499#issuecomment-1837412176) after finishing calling `/describe`. Default is true.
-
- - `enable_semantic_files_types`: if set to true, "Changes walkthrough" section will be generated. Default is true.
- - `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".
- - `enable_help_text`: if set to true, the tool will display a help text in the comment. Default is false.
-
-### Inline file summary 💎
+## Inline file summary 💎
This feature enables you to copy the `changes walkthrough` table to the "Files changed" tab, so you can quickly understand the changes in each file while reviewing the code changes (diff view).
@@ -93,7 +117,7 @@ If you prefer to have the file summaries appear in the "Files changed" tab on ev
**Note**: that this feature is currently available only for GitHub.
-### Markers template
+## 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.
diff --git a/docs/docs/tools/improve.md b/docs/docs/tools/improve.md
index 5980b955..96001490 100644
--- a/docs/docs/tools/improve.md
+++ b/docs/docs/tools/improve.md
@@ -40,52 +40,82 @@ pr_commands = [
]
[pr_code_suggestions]
-num_code_suggestions = ...
+num_code_suggestions_per_chunk = ...
...
```
- 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)
+### Extended mode
+
+An extended mode, which does not involve PR Compression and provides more comprehensive suggestions, can be invoked by commenting on any PR by setting:
+```
+[pr_code_suggestions]
+auto_extended_mode=true
+```
+(This mode is 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.
+
## Configuration options
!!! example "General options"
- - `num_code_suggestions`: number of code suggestions provided by the 'improve' tool. Default is 4 for CLI, 0 for auto tools.
- - `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.
- - `commitable_code_suggestions`: if set to true, the tool will display the suggestions as commitable code comments. Default is false.
- - `persistent_comment`: if set to true, the improve comment will be persistent, meaning that every new improve request will edit the previous one. Default is false.
- - `enable_help_text`: if set to true, the tool will display a help text in the comment. Default is true.
-
-!!! example "params for '/improve --extended' mode"
-
- - `auto_extended_mode`: enable extended mode automatically (no need for the `--extended` option). Default is true.
- - `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.;
-
-## 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.
+
+
+ | num_code_suggestions |
+ Number of code suggestions provided by the 'improve' tool. Default is 4 for CLI, 0 for auto tools. |
+
+
+ | 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. |
+
+
+ | commitable_code_suggestions |
+ If set to true, the tool will display the suggestions as commitable code comments. Default is false. |
+
+
+ | persistent_comment |
+ If set to true, the improve comment will be persistent, meaning that every new improve request will edit the previous one. Default is false. |
+
+
+ | enable_help_text |
+ If set to true, the tool will display a help text in the comment. Default is true. |
+
+
+!!! example "params for 'extended' mode"
+
+
+ | auto_extended_mode |
+ Enable extended mode automatically (no need for the --extended option). Default is true. |
+
+
+ | 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. |
+
+
## Usage Tips
@@ -110,7 +140,7 @@ Hence, the total number of suggestions is proportional to the number of chunks,
!!! tip "Review vs. Improve tools comparison"
- - The [`review`](https://pr-agent-docs.codium.ai/tools/review/) tool includes a section called 'Possible issues', that also provide feedback on the PR Code.
+ - The [review](https://pr-agent-docs.codium.ai/tools/review/) tool includes a section called 'Possible issues', that also provide feedback on the PR Code.
In this section, the model is instructed to focus **only** on [major bugs and issues](https://github.com/Codium-ai/pr-agent/blob/main/pr_agent/settings/pr_reviewer_prompts.toml#L71).
- The `improve` tool, on the other hand, has a broader mandate, and in addition to bugs and issues, it can also give suggestions for improving code quality and making the code more efficient, readable, and maintainable (see [here](https://github.com/Codium-ai/pr-agent/blob/main/pr_agent/settings/pr_code_suggestions_prompts.toml#L34)).
- Hence, if you are interested only in feedback about clear bugs, the `review` tool might suffice. If you want a more detailed feedback, including broader suggestions for improving the PR code, also enable the `improve` tool to run on each PR.
diff --git a/docs/docs/tools/review.md b/docs/docs/tools/review.md
index 2e5c4bb6..97ea5e9f 100644
--- a/docs/docs/tools/review.md
+++ b/docs/docs/tools/review.md
@@ -40,45 +40,6 @@ 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 (if any).
-
-## 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 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 specific sub-sections"
+
+
+
+ | 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".
+
+