xiaxinhang/pr-agent
1
0
Fork 0
mirror of https://github.com/qodo-ai/pr-agent.git synced 2025-07-05 05:10:38 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: Enhance 'improve' tool documentation and update 'DESCRIBE.md' with hyperlink

Browse Source
This commit is contained in:
mrT23
2024-01-07 11:19:47 +02:00
parent 94172104f0
commit d9872d7031
2 changed files with 50 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/DESCRIBE.md
View File

@ -128,7 +128,7 @@ Note that when markers are enabled, if the original PR description does not cont
### Custom labels ### 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`]. 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 in the repo's labels page, you can get tailored labels for your use cases. If you specify [custom labels](#handle-custom-labels-from-the-repos-labels-page-gem) in the repo's labels page, you can get tailored labels for your use cases.
Examples for custom labels: Examples for custom labels:
- `Main topic:performence` - pr_agent:The main topic of this PR is performance - `Main topic:performence` - pr_agent:The main topic of this PR is performance
- `New endpoint` - pr_agent:A new endpoint was added in this PR - `New endpoint` - pr_agent:A new endpoint was added in this PR
@ -138,4 +138,4 @@ Examples for custom labels:
The list above is eclectic, and aims to give an idea of different possibilities. Define custom labels that are relevant for your repo and use cases. The list above is eclectic, and aims to give an idea of different possibilities. Define custom labels that are relevant for your repo and use cases.
Note that Labels are not mutually exclusive, so you can add multiple label categories. Note that Labels are not mutually exclusive, so you can add multiple label categories.
Make sure to provide proper title, and detailed and well-phrased description for each label, so the tool will know when to suggest it. <br>Make sure to provide proper title, and detailed and well-phrased description for each label, so the tool will know when to suggest it.

62
docs/IMPROVE.md
View File

@ -1,27 +1,40 @@
# Improve Tool # Improve Tool
## Table of Contents
- [Overview](#overview)
- [Configuration options](#configuration-options)
- [summarize mode](#summarize-mode)
- [Usage Tips](#usage-tips)
- [Extra instructions](#extra-instructions)
- [PR footprint - regular vs summarize mode](#pr-footprint---regular-vs-summarize-mode)
- [A note on code suggestions quality](#a-note-on-code-suggestions-quality)
## Overview
The `improve` tool scans the PR code changes, and automatically generates committable suggestions for improving the PR code. The `improve` tool scans the PR code changes, and automatically generates committable suggestions for improving the PR code.
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:
``` ```
/improve /improve
``` ```
For example: For example:
<kbd><img src=https://codium.ai/images/pr_agent/improve_comment.png width="768"></kbd> <kbd><img src=https://codium.ai/images/pr_agent/improve_comment.png width="768"></kbd>
---
<kbd><img src=https://codium.ai/images/pr_agent/improve.png width="768"></kbd> <kbd><img src=https://codium.ai/images/pr_agent/improve.png width="768"></kbd>
---
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: An extended mode, which does not involve PR Compression and provides more comprehensive suggestions, can be invoked by commenting on any PR:
``` ```
/improve --extended /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). 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. Hence, the total number of suggestions is proportional to the number of chunks, i.e., the size of the PR.
### Configuration options ### Configuration options
Under the section 'pr_code_suggestions', the [configuration file](./../pr_agent/settings/configuration.toml#L40) contains options to customize the 'improve' tool: To edit [configurations](./../pr_agent/settings/configuration.toml#46) related to the improve tool (`pr_code_suggestions` section), use the following template:
```
/improve --pr_code_suggestions.some_config1=... --pr_code_suggestions.some_config2=...
```
- `num_code_suggestions`: number of code suggestions provided by the 'improve' tool. Default is 4. - `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 ...". - `extra_instructions`: Optional extra instructions to the tool. For example: "focus on the changes in the file X. Ignore change in ...".
@ -35,25 +48,46 @@ Under the section 'pr_code_suggestions', the [configuration file](./../pr_agent/
- `max_number_of_calls`: maximum number of chunks. Default is 5. - `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.
#### summarize mode ### summarize mode
- `summarize`: if set to true, the tool will present the code suggestions in a compact way. Default is false.
In this mode, instead of presenting committable suggestions, the different suggestions will be combined into a single compact comment, with significantly smaller PR footprint. In this mode, instead of presenting committable suggestions, the different suggestions will be combined into a single compact comment, with significantly smaller PR footprint.
To invoke the summarize mode, use the following command:
```
/improve --pr_code_suggestions.summarize=true
```
For example: For example:
`/improve --pr_code_suggestions.summarize=true`
<kbd><img src=https://codium.ai/images/pr_agent/improved_summerize_open.png width="768"></kbd> <kbd><img src=https://codium.ai/images/pr_agent/improved_summerize_open.png width="768"></kbd>
___ ___
## Usage Tips
### Extra instructions
Extra instructions are very important for the `imrpove` tool, since they enable you to guide the model to suggestions that are more relevant to the specific needs of the project.
Be specific, clear, and concise in the instructions. With extra instructions, you are the prompter. Specify relevant aspects that you want the model to focus on.
Examples for extra instructions:
```
[pr_code_suggestions] # /improve #
extra_instructions="""
Emphasize the following aspects:
- Does the code logic covers relevant edge cases?
- Is the code logic clear and easy to understand?
- Is the code logic efficient?
...
"""
```
Use triple quotes to write multi-line instructions. Use bullet points to make the instructions more readable.
### PR footprint - regular vs summarize mode
The default mode of the `improve` tool provides committable suggestions. This mode as a high PR footprint, since each suggestion is a separate comment you need to resolve.
If you prefer something more compact, use the [`summarize`](#summarize-mode) mode, which combines all the suggestions into a single comment.
### A note on code suggestions quality ### A note on code suggestions quality
- While the current AI for code is getting better and better (GPT-4), it's not flawless. Not all the suggestions will be perfect, and a user should not accept all of them automatically. - While the current AI for code is getting better and better (GPT-4), it's not flawless. Not all the suggestions will be perfect, and a user should not accept all of them automatically.
- Suggestions are not meant to be [simplistic](./../pr_agent/settings/pr_code_suggestions_prompts.toml#L34). Instead, they aim to give deep feedback and raise questions, ideas and thoughts to the user, who can then use his judgment, experience, and understanding of the code base. - Suggestions are not meant to be [simplistic](./../pr_agent/settings/pr_code_suggestions_prompts.toml#L34). Instead, they aim to give deep feedback and raise questions, ideas and thoughts to the user, who can then use his judgment, experience, and understanding of the code base.
- Recommended to use the 'extra_instructions' field to guide the model to suggestions that are more relevant to the specific needs of the project. - Recommended to use the 'extra_instructions' field to guide the model to suggestions that are more relevant to the specific needs of the project.
- Best quality will be obtained by using 'improve --extended' mode. - Best quality will be obtained by using 'improve --extended' mode.