Skip to content

Commit

Permalink
Merge commit '8d075b76ae081d0d38813f789478e4fa0f404cd8' into hl/add_docs
Browse files Browse the repository at this point in the history 
# Conflicts:
#	README.md
  • Loading branch information
@hussam789
hussam789 committed Oct 1, 2023
2 parents ab5ac8f + 8d075b7 commit b2369c6
Show file tree
Hide file tree
Showing 31 changed files with 244 additions and 64 deletions.
8 changes: 4 additions & 4 deletions INSTALL.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -89,10 +89,10 @@ chmod 600 pr_agent/settings/.secrets.toml

```
export PYTHONPATH=[$PYTHONPATH:]<PATH to pr_agent folder>
python pr_agent/cli.py --pr_url <pr_url> /review
python pr_agent/cli.py --pr_url <pr_url> /ask <your question>
python pr_agent/cli.py --pr_url <pr_url> /describe
python pr_agent/cli.py --pr_url <pr_url> /improve
python3 -m pr_agent.cli --pr_url <pr_url> /review
python3 -m pr_agent.cli --pr_url <pr_url> /ask <your question>
python3 -m pr_agent.cli --pr_url <pr_url> /describe
python3 -m pr_agent.cli --pr_url <pr_url> /improve
```

---
Expand Down
20 changes: 11 additions & 9 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,23 +17,25 @@ Making pull requests less painful with an AI agent

CodiumAI `PR-Agent` is an open-source tool aiming to help developers review pull requests faster and more efficiently. It automatically analyzes the pull request and can provide several types of commands:

‣ **Auto Description (`/describe`)**: Automatically generating [PR description](https://github.com/Codium-ai/pr-agent/pull/229#issue-1860711415) - title, type, summary, code walkthrough and labels.
‣ **Auto Description ([`/describe`](./docs/DESCRIBE.md))**: Automatically generating PR description - title, type, summary, code walkthrough and labels.
\
‣ **Auto Review (`/review`)**: [Adjustable feedback](https://github.com/Codium-ai/pr-agent/pull/229#issuecomment-1695022908) about the PR main theme, type, relevant tests, security issues, score, and various suggestions for the PR content.
‣ **Auto Review ([`/review`](./docs/REVIEW.md))**: Adjustable feedback about the PR main theme, type, relevant tests, security issues, score, and various suggestions for the PR content.
\
‣ **Question Answering (`/ask ...`)**: Answering [free-text questions](https://github.com/Codium-ai/pr-agent/pull/229#issuecomment-1695021332) about the PR.
‣ **Question Answering ([`/ask ...`](./docs/ASK.md))**: Answering free-text questions about the PR.
\
‣ **Code Suggestions (`/improve`)**: [Committable code suggestions](https://github.com/Codium-ai/pr-agent/pull/229#discussion_r1306919276) for improving the PR.
‣ **Code Suggestions ([`/improve`](./docs/IMPROVE.md))**: Committable code suggestions for improving the PR.
\
‣ **Update Changelog (`/update_changelog`)**: Automatically updating the CHANGELOG.md file with the [PR changes](https://github.com/Codium-ai/pr-agent/pull/168#discussion_r1282077645).
‣ **Update Changelog ([`/update_changelog`](./docs/UPDATE_CHANGELOG.md))**: Automatically updating the CHANGELOG.md file with the PR changes.
\
‣ **Find similar issue (`/similar_issue`)**: Automatically retrieves and presents [similar issues](https://github.com/Alibaba-MIIL/ASL/issues/107).
‣ **Find similar issue ([`/similar_issue`](./docs/SIMILAR_ISSUE.md))**: Automatically retrieves and presents similar issues
\
‣ **Add Documentation (`/add_docs`)**: Automatically adds [documentation](https://github.com/Codium-ai/pr-agent/pull/337#discussion_r1342111682) to un-documented functions/classes in the PR.

See the [usage guide](./Usage.md) for instructions how to run the different tools from [CLI](./Usage.md#working-from-a-local-repo-cli), or by [online usage](./Usage.md#online-usage), as well as additional details on optional commands and configurations.
See the [Usage Guide](./Usage.md) for instructions how to run the different tools from _CLI_, _online usage_, Or by _automatically triggering_ them when a new PR is opened.

[Release notes](./RELEASE_NOTES.md)
See the [Tools Guide](./docs/TOOLS_GUIDE.md) for detailed description of the different tools.

See the [Release notes](./RELEASE_NOTES.md) for updates on the latest changes.

<h3>Example results:</h3>
</div>
Expand Down Expand Up @@ -124,7 +126,7 @@ See the [usage guide](./Usage.md) for instructions how to run the different tool
| | Multiple models support | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| | Incremental PR Review | :white_check_mark: | | | | | |

Review the **[usage guide](./Usage.md)** section for detailed instructions how to use the different tools, select the relevant git provider (GitHub, Gitlab, Bitbucket,...), and adjust the configuration file to your needs.
Review the [usage guide](./Usage.md) section for detailed instructions how to use the different tools, select the relevant git provider (GitHub, Gitlab, Bitbucket,...), and adjust the configuration file to your needs.

## Try it now

Expand Down
75 changes: 27 additions & 48 deletions Usage.md
View file
Original file line number Diff line number Diff line change
@@ -1,24 +1,23 @@
## Usage guide
## Usage Guide

### Table of Contents
- [Introduction](#introduction)
- [Working from a local repo (CLI)](#working-from-a-local-repo-cli)
- [Online usage](#online-usage)
- [Working with GitHub App](#working-with-github-app)
- [Working with GitHub Action](#working-with-github-action)
- [Changing a model](#changing-a-model)
- [Appendix - additional configurations walkthrough](#appendix---additional-configurations-walkthrough)

### Introduction

There are 3 basic ways to invoke CodiumAI PR-Agent:
See the **[installation guide](/INSTALL.md)** for instructions on how to setup PR-Agent. After installation, there are three basic ways to invoke CodiumAI PR-Agent:
1. Locally running a CLI command
2. Online usage - by [commenting](https://github.com/Codium-ai/pr-agent/pull/229#issuecomment-1695021901) on a PR
3. Enabling PR-Agent tools to run automatically when a new PR is opened

See the [installation guide](/INSTALL.md) for instructions on how to setup your own PR-Agent.

Specifically, CLI commands can be issued by invoking a pre-built [docker image](/INSTALL.md#running-from-source), or by invoking a [locally cloned repo](INSTALL.md#method-2-run-from-source).

For online usage, you will need to setup either a [GitHub App](INSTALL.md#method-5-run-as-a-github-app), or a [GitHub Action](INSTALL.md#method-3-run-as-a-github-action).
GitHub App and GitHub Action also enable to run PR-Agent specific tool automatically when a new PR is opened.

Expand All @@ -27,10 +26,12 @@ GitHub App and GitHub Action also enable to run PR-Agent specific tool automatic
The different tools and sub-tools used by CodiumAI PR-Agent are adjustable via the **[configuration file](pr_agent/settings/configuration.toml)**.
In addition to general configuration options, each tool has its own configurations. For example, the `review` tool will use parameters from the [pr_reviewer](/pr_agent/settings/configuration.toml#L16) section in the configuration file.

**git provider:**
The [Tools Guide](./docs/TOOLS_GUIDE.md) provides a detailed description of the different tools and their configurations.

#### git provider
The [git_provider](pr_agent/settings/configuration.toml#L4) field in the configuration file determines the GIT provider that will be used by PR-Agent. Currently, the following providers are supported:
`
"github", "gitlab", "azure", "codecommit", "local"
"github", "gitlab", "azure", "codecommit", "local", "gerrit"
`

[//]: # (** online usage:**)
Expand All @@ -47,23 +48,22 @@ The [git_provider](pr_agent/settings/configuration.toml#L4) field in the configu

### Working from a local repo (CLI)
When running from your local repo (CLI), your local configuration file will be used.

Examples for invoking the different tools via the CLI:

- **Review**: `python cli.py --pr_url=<pr_url> review`
- **Describe**: `python cli.py --pr_url=<pr_url> describe`
- **Improve**: `python cli.py --pr_url=<pr_url> improve`
- **Ask**: `python cli.py --pr_url=<pr_url> ask "Write me a poem about this PR"`
- **Reflect**: `python cli.py --pr_url=<pr_url> reflect`
- **Update Changelog**: `python cli.py --pr_url=<pr_url> update_changelog`
- **Review**: `python -m pr_agent.cli --pr_url=<pr_url> review`
- **Describe**: `python -m pr_agent.cli --pr_url=<pr_url> describe`
- **Improve**: `python -m pr_agent.cli --pr_url=<pr_url> improve`
- **Ask**: `python -m pr_agent.cli --pr_url=<pr_url> ask "Write me a poem about this PR"`
- **Reflect**: `python -m pr_agent.cli --pr_url=<pr_url> reflect`
- **Update Changelog**: `python -m pr_agent.cli --pr_url=<pr_url> update_changelog`

`<pr_url>` is the url of the relevant PR (for example: https://github.com/Codium-ai/pr-agent/pull/50).

**Notes:**

(1) in addition to editing your local configuration file, you can also change any configuration value by adding it to the command line:
```
python cli.py --pr_url=<pr_url> /review --pr_reviewer.extra_instructions="focus on the file: ..."
python -m pr_agent.cli --pr_url=<pr_url> /review --pr_reviewer.extra_instructions="focus on the file: ..."
```

(2) You can print results locally, without publishing them, by setting in `configuration.toml`:
Expand Down Expand Up @@ -93,15 +93,15 @@ For example if you want to edit the `review` tool configurations, you can run:
```
/review --pr_reviewer.extra_instructions="..." --pr_reviewer.require_score_review=false
```
Any configuration value in [configuration file](pr_agent/settings/configuration.toml) file can be similarly edited.
Any configuration value in [configuration file](pr_agent/settings/configuration.toml) file can be similarly edited. comment `/config` to see the list of available configurations.


### Working with GitHub App
When running PR-Agent from [GitHub App](INSTALL.md#method-5-run-as-a-github-app), the default configurations from a pre-built repo will be initially loaded.
When running PR-Agent from [GitHub App](INSTALL.md#method-5-run-as-a-github-app), the default configurations from a pre-built docker will be initially loaded.

#### GitHub app automatic tools
The [github_app](pr_agent/settings/configuration.toml#L56) section defines GitHub app specific configurations.
An important parameter is `pr_commands`, which is a list of tools that will be **run automatically when a new PR is opened**:
An important parameter is `pr_commands`, which is a list of tools that will be **run automatically** when a new PR is opened:
```
[github_app]
pr_commands = [
Expand All @@ -112,7 +112,7 @@ pr_commands = [
This means that when a new PR is opened, PR-Agent will run the `describe` and `auto_review` tools.
For the describe tool, the `add_original_user_description` and `keep_original_user_title` parameters will be set to true.

However, you can override the default tool parameters by uploading a local configuration file called `.pr_agent.toml` to the root of your repo.
You can override the default tool parameters by uploading a local configuration file called `.pr_agent.toml` to the root of your repo.
For example, if your local `.pr_agent.toml` file contains:
```
[pr_description]
Expand All @@ -125,7 +125,6 @@ Note that a local `.pr_agent.toml` file enables you to edit and customize the de

#### Editing the prompts
The prompts for the various PR-Agent tools are defined in the `pr_agent/settings` folder.

In practice, the prompts are loaded and stored as a standard setting object.
Hence, editing them is similar to editing any other configuration value - just place the relevant key in `.pr_agent.toml`file, and override the default value.

Expand Down Expand Up @@ -155,24 +154,23 @@ You can configure settings in GitHub action by adding environment variables unde
```
specifically, `github_action.auto_review`, `github_action.auto_describe` and `github_action.auto_improve` are used to enable/disable automatic tools that run when a new PR is opened.

if not set, the default option is that only the `review` tool will run automatically when a new PR is opened.

If not set, the default option is that only the `review` tool will run automatically when a new PR is opened.

### Appendix - additional configurations walkthrough
### Changing a model

#### Changing a model
See [here](pr_agent/algo/__init__.py) for the list of available models.
To use a different model than the default (GPT-4), you need to edit [configuration file](pr_agent/settings/configuration.toml#L2).
For models and environments not from OPENAI, you might need to provide additional keys and other parameters. See below for instructions.

#### Azure
To use Azure, set:
To use Azure, set in your .secrets.toml:
```
api_key = "" # your azure api key
api_type = "azure"
api_version = '2023-05-15' # Check Azure documentation for the current API version
api_base = "" # The base URL for your Azure OpenAI resource. e.g. "https://<your resource name>.openai.azure.com"
deployment_id = "" # The deployment name you chose when you deployed the engine
```
in your .secrets.toml

and
```
Expand Down Expand Up @@ -242,6 +240,9 @@ key = ...
Also review the [AiHandler](pr_agent/algo/ai_handler.py) file for instruction how to set keys for other models.
### Appendix - additional configurations walkthrough
#### Extra instructions
All PR-Agent tools have a parameter called `extra_instructions`, that enables to add free-text extra instructions. Example usage:
```
Expand All @@ -261,26 +262,4 @@ And use the following settings (you have to replace the values) in .secrets.toml
[azure_devops]
org = "https://dev.azure.com/YOUR_ORGANIZATION/"
pat = "YOUR_PAT_TOKEN"
```
#### Similar issue tool
[Example usage](https://github.com/Alibaba-MIIL/ASL/issues/107)
<img src=./pics/similar_issue_tool.png width="768">
To enable usage of the '**similar issue**' tool, you need to set the following keys in `.secrets.toml` (or in the relevant environment variables):
```
[pinecone]
api_key = "..."
environment = "..."
```
These parameters can be obtained by registering to [Pinecone](https://app.pinecone.io/?sessionType=signup/).
- To invoke the 'similar issue' tool from **CLI**, run:
`python3 cli.py --issue_url=... similar_issue`
- To invoke the 'similar' issue tool via online usage, [comment](https://github.com/Codium-ai/pr-agent/issues/178#issuecomment-1716934893) on a PR:
`/similar_issue`
- You can also enable the 'similar issue' tool to run automatically when a new issue is opened, by adding it to the [pr_commands list in the github_app section](https://github.com/Codium-ai/pr-agent/blob/main/pr_agent/settings/configuration.toml#L66)
```
11 changes: 11 additions & 0 deletions docs/ASK.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# ASK Tool

The `ask` tool answers questions about the PR, based on the PR code changes.
It can be invoked manually by commenting on any PR:
```
/ask "..."
```
For example:

<kbd><img src=./../pics/ask_comment.png width="768"></kbd>
<kbd><img src=./../pics/ask.png width="768"></kbd>
51 changes: 51 additions & 0 deletions docs/DESCRIBE.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
# Describe Tool

The `describe` tool scans the PR code changes, and automatically generates PR description - title, type, summary, code walkthrough and labels.
It can be invoked manually by commenting on any PR:
```
/describe
```
For example:

<kbd><img src=./../pics/describe_comment.png width="768"></kbd>

<kbd><img src=./../pics/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)

### Configuration options

Under the section 'pr_description', the [configuration file](./../pr_agent/settings/configuration.toml#L28) contains options to customize the 'describe' tool:

- `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.

- `add_original_user_description`: if set to true, the tool will add the original user description to the generated description. Default is false.

- `add_original_user_title`: if set to true, the tool will keep the original PR title, and won't change it. Default is false.

- `extra_instructions`: Optional extra instructions to the tool. For example: "focus on the changes in the file X. Ignore change in ...".

#### Markers template

markers enable to easily integrate user's content and auto-generated content, with a template-like mechanism.

- `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.

For example, if the PR original description was:
```
User content...
## PR Type:
pr_agent:pr_type
## PR Description:
pr_agent:summary
## PR Walkthrough:
pr_agent:walkthrough
```
The marker `pr_agent:pr_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.

- `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.
34 changes: 34 additions & 0 deletions docs/IMPROVE.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
# Improve Tool

The `improve` tool scans the PR code changes, and automatically generate committable suggestions for improving the PR code.
It can be invoked manually by commenting on any PR:
```
/improve
```
For example:

<kbd><img src=./../pics/improve_comment.png width="768"></kbd>
<kbd><img src=./../pics/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:
```
/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).
Hence, the total number of suggestions is proportional to the number of chunks, i.e. the size of the PR.

### Configuration options

Under the section 'pr_code_suggestions', the [configuration file](./../pr_agent/settings/configuration.toml#L40) contains options to customize the 'improve' tool:

- `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 ...".
- `rank_suggestions`: if set to true, the tool will rank the suggestions, based on importance. Default is false.

#### params for '/improve --extended' mode
- `num_code_suggestions_per_chunk`: number of code suggestions provided by the 'improve' tool, per chunk. Default is 8.
- `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.
Loading

0 comments on commit b2369c6

Please sign in to comment.