mirror of
https://github.com/qodo-ai/pr-agent.git
synced 2025-07-03 12:20:38 +08:00
Update describe.md: Improve image formatting, restructure content, and enhance descriptions
This commit is contained in:
mrT23
@ -7,19 +7,29 @@ The tool can be triggered automatically every time a new PR is [opened](../usage
|
||||
```
|
||||
For example:
|
||||
|
||||
<kbd><img src=https://codium.ai/images/pr_agent/describe_comment.png width="768"></kbd>
|
||||
<kbd>
|
||||
<a href="https://codium.ai/images/pr_agent/describe_comment.png">
|
||||
<img src=https://codium.ai/images/pr_agent/describe_comment.png width="512">
|
||||
</a>
|
||||
</kbd>
|
||||
|
||||
<kbd><img src=https://codium.ai/images/pr_agent/describe_new.png width="768"></kbd>
|
||||
<kbd>
|
||||
<a href="https://codium.ai/images/pr_agent/describe_new.png">
|
||||
<img src=https://codium.ai/images/pr_agent/describe_new.png width="512">
|
||||
</a>
|
||||
</kbd>
|
||||
|
||||
|
||||
|
||||
## Configuration options
|
||||
|
||||
### General configurations
|
||||
To edit [configurations](https://github.com/Codium-ai/pr-agent/blob/main/pr_agent/settings/configuration.toml#L46) related to the describe tool (`pr_description` section), use the following template:
|
||||
```
|
||||
/describe --pr_description.some_config1=... --pr_description.some_config2=...
|
||||
```
|
||||
|
||||
### Possible configurations:
|
||||
!!! example "Possible configurations"
|
||||
|
||||
- `publish_labels`: if set to true, the tool will publish the labels to the PR. Default is true.
|
||||
|
||||
@ -41,29 +51,41 @@ To edit [configurations](https://github.com/Codium-ai/pr-agent/blob/main/pr_agen
|
||||
- `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".
|
||||
|
||||
### Inline file summary 💎
|
||||
> This feature is available only in PR-Agent Pro
|
||||
|
||||
This feature will enable you to quickly understand the changes in each file while reviewing the code changes (diff view).
|
||||
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).
|
||||
|
||||
To add the walkthrough table to the "Files changed" tab, you can click on the checkbox that appears PR Description status message below the main PR Description:
|
||||
To copy the `changes walkthrough` table to the "Files changed" tab, you can click on the checkbox that appears PR Description status message below the main PR Description:
|
||||
|
||||
<kbd><img src=https://codium.ai/images/pr_agent/add_table_checkbox.png width="512"></kbd>
|
||||
<kbd>
|
||||
<a href="https://codium.ai/images/pr_agent/add_table_checkbox.png">
|
||||
<img src=https://codium.ai/images/pr_agent/add_table_checkbox.png width="512">
|
||||
</a>
|
||||
</kbd>
|
||||
|
||||
If you prefer to have the file summaries appear in the "Files changed" tab on every PR, change the `pr_description.inline_file_summary` parameter in the configuration file, possible values are:
|
||||
|
||||
- `'table'`: File changes walkthrough table will be displayed on the top of the "Files changed" tab, in addition to the "Conversation" tab.
|
||||
<kbd><img src=https://codium.ai/images/pr_agent/diffview-table.png width="768"></kbd>
|
||||
|
||||
<kbd>
|
||||
<a href="https://codium.ai/images/pr_agent/diffview-table.png">
|
||||
<img src=https://codium.ai/images/pr_agent/diffview-table.png width="512">
|
||||
</a>
|
||||
</kbd>
|
||||
|
||||
- `true`: A collapsable file comment with changes title and a changes summary for each file in the PR.
|
||||
<kbd><img src=https://codium.ai/images/pr_agent/diffview_changes.png width="768"></kbd>
|
||||
|
||||
<kbd>
|
||||
<a href="https://codium.ai/images/pr_agent/diffview_changes.png">
|
||||
<img src=https://codium.ai/images/pr_agent/diffview_changes.png width="512">
|
||||
</a>
|
||||
</kbd>
|
||||
|
||||
- `false` (`default`): File changes walkthrough will be added only to the "Conversation" tab.
|
||||
|
||||
**Note** that this feature is currently available only for GitHub.
|
||||
**Note**: that this feature is currently available only for GitHub.
|
||||
|
||||
|
||||
### Handle custom labels from the Repo's labels page 💎
|
||||
> This feature is available only in PR-Agent Pro
|
||||
|
||||
You can control the custom labels that will be suggested by the `describe` tool, from the repo's labels page:
|
||||
|
||||
@ -71,11 +93,16 @@ You can control the custom labels that will be suggested by the `describe` tool
|
||||
* 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. For example:
|
||||
<kbd><img src=https://codium.ai/images/pr_agent/add_native_custom_labels.png width="880"></kbd>
|
||||
<kbd>
|
||||
<a href="https://codium.ai/images/pr_agent/custom_labels.png">
|
||||
<img src=https://codium.ai/images/pr_agent/add_native_custom_labels.png width="768">
|
||||
</a>
|
||||
</kbd>
|
||||
|
||||
|
||||
### Markers template
|
||||
@ -98,11 +125,21 @@ pr_agent: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.
|
||||
|
||||
<kbd><img src=https://codium.ai/images/pr_agent/describe_markers_before.png width="768"></kbd>
|
||||
→
|
||||
<kbd><img src=https://codium.ai/images/pr_agent/describe_markers_after.png width="768"></kbd>
|
||||
<kbd>
|
||||
<a href="https://codium.ai/images/pr_agent/describe_markers_before.png">
|
||||
<img src=https://codium.ai/images/pr_agent/describe_markers_before.png width="512">
|
||||
</a>
|
||||
</kbd>
|
||||
|
||||
### Configuration params:
|
||||
→
|
||||
|
||||
<kbd>
|
||||
<a href="https://codium.ai/images/pr_agent/describe_markers_after.png">
|
||||
<img src=https://codium.ai/images/pr_agent/describe_markers_after.png width="512">
|
||||
</a>
|
||||
</kbd>
|
||||
|
||||
**Configuration params**:
|
||||
|
||||
- `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.
|
||||
@ -110,15 +147,15 @@ The marker `pr_agent:type` will be replaced with the PR type, `pr_agent:summary`
|
||||
|
||||
## Usage Tips
|
||||
|
||||
### Automation
|
||||
- When you first install the app, the [default mode](../usage-guide/automations_and_usage.md#github-app) for the describe tool is:
|
||||
!!! 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", ...]
|
||||
```
|
||||
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 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.
|
||||
- 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"
|
||||
@ -130,18 +167,19 @@ so the title will be auto-generated as well.
|
||||
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.
|
||||
* `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.
|
||||
|
||||
### Custom labels
|
||||
!!! tip "Custom labels"
|
||||
|
||||
The default labels of the describe tool are quite generic, since they are meant to be used in any repo: [`Bug fix`, `Tests`, `Enhancement`, `Documentation`, `Other`].
|
||||
|
||||
If you specify [custom labels](#handle-custom-labels-from-the-repos-labels-page) in the repo's labels page, you can get tailored labels for your use cases.
|
||||
Examples for custom labels:
|
||||
|
||||
- `Main topic:performance` - pr_agent:The main topic of this PR is performance
|
||||
- `New endpoint` - pr_agent:A new endpoint was added in this PR
|
||||
- `SQL query` - pr_agent:A new SQL query was added in this PR
|
||||
|
||||
Reference in New Issue
Block a user