Merge pull request #571 from Codium-ai/tr/user_description

Enhance Documentation and Configuration of 'describe' Tool

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).
 
-<h3>Example results:</h3>
+## 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
 </div>
 <h4><a href="https://github.com/Codium-ai/pr-agent/pull/530">/describe</a></h4>
 <div align="center">
@@ -112,22 +121,17 @@ See the [Tools Guide](./docs/TOOLS_GUIDE.md) for detailed description of the dif
 [//]: # (</div>)
 <div align="left">
 
-## 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)
 </div>
 
 
-## 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:        |
+|       | [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 💎                   |   :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 💎                    |   :white_check_mark:    |   :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<br />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:    |
+|       | [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 💎 |   :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

Usage.md

@@ -2,12 +2,12 @@
 
 ### Table of Contents
 - [Introduction](#introduction)
-- [Working from a local repo (CLI)](#working-from-a-local-repo-cli)
+- [Local Repo (CLI)](#working-from-a-local-repo-cli)
-- [Online usage](#online-usage)
+- [Online Usage](#online-usage)
-- [Working with GitHub App](#working-with-github-app)
+- [GitHub App](#working-with-github-app)
-- [Working with GitHub Action](#working-with-github-action)
+- [GitHub Action](#working-with-github-action)
-- [Working with BitBucket App](#working-with-bitbucket-self-hosted-app)
+- [BitBucket App](#working-with-bitbucket-self-hosted-app)
-- [Appendix - additional configurations walkthrough](#appendix---additional-configurations-walkthrough)
+- [Additional Configurations Walkthrough](#appendix---additional-configurations-walkthrough)
 
 ### Introduction
 

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.
+The `describe` tool scans the PR code changes, and can automatically generate PR description - title, type, summary, walkthrough and labels.
-It can be invoked manually by commenting on any PR:
+
+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:
 
 <kbd><img src=https://codium.ai/images/pr_agent/describe.png width="768"></kbd>
 
-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`.<br>
-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:
 <kbd><img src=https://codium.ai/images/pr_agent/add_native_custom_labels.png width="880"></kbd>
 
-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.
+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.
-
-##### Example:
-```
-        env:
-          pr_description.use_description_markers: 'true'
-```          
 
 <kbd><img src=https://codium.ai/images/pr_agent/describe_markers_before.png width="768"></kbd>
 
@@ -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. <br> 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.
+

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

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 %}