Merge pull request #268 from Codium-ai/tr/readme_updates

Update Documentation and Reorder Installation Methods

INSTALL.md

@@ -9,8 +9,8 @@ To get started with PR-Agent quickly, you first need to acquire two tokens:
 There are several ways to use PR-Agent:
 
 - [Method 1: Use Docker image (no installation required)](INSTALL.md#method-1-use-docker-image-no-installation-required)
-- [Method 2: Run as a GitHub Action](INSTALL.md#method-2-run-as-a-github-action)
+- [Method 2: Run from source](INSTALL.md#method-2-run-from-source)
-- [Method 3: Run from source](INSTALL.md#method-3-run-from-source)
+- [Method 3: Run as a GitHub Action](INSTALL.md#method-3-run-as-a-github-action)
 - [Method 4: Run as a polling server](INSTALL.md#method-4-run-as-a-polling-server)
 - [Method 5: Run as a GitHub App](INSTALL.md#method-5-run-as-a-github-app)
 - [Method 6: Deploy as a Lambda Function](INSTALL.md#method-6---deploy-as-a-lambda-function)
@@ -55,7 +55,41 @@ Possible questions you can ask include:
 
 ---
 
-### Method 2: Run as a GitHub Action
+### Method 2: Run from source
+
+1. Clone this repository:
+
+```
+git clone https://github.com/Codium-ai/pr-agent.git
+```
+
+2. Install the requirements in your favorite virtual environment:
+
+```
+pip install -r requirements.txt
+```
+
+3. Copy the secrets template file and fill in your OpenAI key and your GitHub user token:
+
+```
+cp pr_agent/settings/.secrets_template.toml pr_agent/settings/.secrets.toml
+chmod 600 pr_agent/settings/.secrets.toml
+# Edit .secrets.toml file
+```
+
+4. Add the pr_agent folder to your PYTHONPATH, then run the cli.py script:
+
+```
+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
+```
+
+---
+
+### Method 3: Run as a GitHub Action
 
 You can use our pre-built Github Action Docker image to run PR-Agent as a Github Action. 
 
@@ -114,7 +148,7 @@ The GITHUB_TOKEN secret is automatically created by GitHub.
 3. Merge this change to your main branch. 
 When you open your next PR, you should see a comment from `github-actions` bot with a review of your PR, and instructions on how to use the rest of the tools.
 
-4. You may configure PR-Agent by adding environment variables under the env section corresponding to any configurable property in the [configuration](./CONFIGURATION.md) file. Some examples:
+4. You may configure PR-Agent by adding environment variables under the env section corresponding to any configurable property in the [configuration](./Usage.md) file. Some examples:
 ```yaml
       env:
         # ... previous environment values
@@ -125,40 +159,6 @@ When you open your next PR, you should see a comment from `github-actions` bot w
 
 ---
 
-### Method 3: Run from source
-
-1. Clone this repository:
-
-```
-git clone https://github.com/Codium-ai/pr-agent.git
-```
-
-2. Install the requirements in your favorite virtual environment:
-
-```
-pip install -r requirements.txt
-```
-
-3. Copy the secrets template file and fill in your OpenAI key and your GitHub user token:
-
-```
-cp pr_agent/settings/.secrets_template.toml pr_agent/settings/.secrets.toml
-chmod 600 pr_agent/settings/.secrets.toml
-# Edit .secrets.toml file
-```
-
-4. Add the pr_agent folder to your PYTHONPATH, then run the cli.py script:
-
-```
-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
-```
-
----
-
 ### Method 4: Run as a polling server
 Request reviews by tagging your Github user on a PR
 
@@ -253,7 +253,7 @@ docker push codiumai/pr-agent:github_app  # Push to your Docker repository
 
 > **Note:** When running PR-Agent from GitHub App, the default configuration file (configuration.toml) will be loaded.<br>
 > However, you can override the default tool parameters by uploading a local configuration file<br>
-> For more information please check out [CONFIGURATION.md](CONFIGURATION.md#working-from-github-app-pre-built-repo)
+> For more information please check out [CONFIGURATION.md](Usage.md#working-from-github-app-pre-built-repo)
 ---
 
 ### Method 6 - Deploy as a Lambda Function

README.md

@@ -87,7 +87,7 @@ CodiumAI `PR-Agent` is an open-source tool aiming to help developers review pull
 - [Overview](#overview)
 - [Try it now](#try-it-now)
 - [Installation](#installation)
-- [Configuration](./CONFIGURATION.md)
+- [Usage guide](./Usage.md)
 - [How it works](#how-it-works)
 - [Why use PR-Agent](#why-use-pr-agent)
 - [Roadmap](#roadmap)
@@ -117,7 +117,7 @@ CodiumAI `PR-Agent` is an open-source tool aiming to help developers review pull
 |       | Multiple models support |   :white_check_mark:    |   :white_check_mark:    |   :white_check_mark:       | :white_check_mark: |   :white_check_mark:       |
 |       | Incremental PR Review |   :white_check_mark:    |      |      |      |      |
 
-Review the **[configuration](./CONFIGURATION.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
 
@@ -145,8 +145,8 @@ To get started with PR-Agent quickly, you first need to acquire two tokens:
 There are several ways to use PR-Agent:
 
 - [Method 1: Use Docker image (no installation required)](INSTALL.md#method-1-use-docker-image-no-installation-required)
-- [Method 2: Run as a GitHub Action](INSTALL.md#method-2-run-as-a-github-action)
+- [Method 2: Run from source](INSTALL.md#method-2-run-from-source)
-- [Method 3: Run from source](INSTALL.md#method-3-run-from-source)
+- [Method 3: Run as a GitHub Action](INSTALL.md#method-3-run-as-a-github-action)
 - [Method 4: Run as a polling server](INSTALL.md#method-4-run-as-a-polling-server)
   - Request reviews by tagging your GitHub user on a PR
 - [Method 5: Run as a GitHub App](INSTALL.md#method-5-run-as-a-github-app)
@@ -170,7 +170,7 @@ Here are some advantages of PR-Agent:
 
 - We emphasize **real-life practical usage**. Each tool (review, improve, ask, ...) has a single GPT-4 call, no more. We feel that this is critical for realistic team usage - obtaining an answer quickly (~30 seconds) and affordably.
 - Our [PR Compression strategy](./PR_COMPRESSION.md)  is a core ability that enables to effectively tackle both short and long PRs.
-- Our JSON prompting strategy enables to have **modular, customizable tools**. For example, the '/review' tool categories can be controlled via the [configuration](./CONFIGURATION.md) file. Adding additional categories is easy and accessible.
+- Our JSON prompting strategy enables to have **modular, customizable tools**. For example, the '/review' tool categories can be controlled via the [configuration](pr_agent/settings/configuration.toml) file. Adding additional categories is easy and accessible.
 - We support **multiple git providers** (GitHub, Gitlab, Bitbucket, CodeCommit), **multiple ways** to use the tool (CLI, GitHub Action, GitHub App, Docker, ...), and **multiple models** (GPT-4, GPT-3.5, Anthropic, Cohere, Llama2).
 - We are open-source, and welcome contributions from the community.
 

Usage.md

@@ -1,20 +1,52 @@
-## Configuration
+## Usage guide
 
-The different tools and sub-tools used by CodiumAI PR-Agent are adjustable via the **[configuration file](pr_agent/settings/configuration.toml)**
+### 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)
+- [Appendix - additional configurations walkthrough](#appendix---additional-configurations-walkthrough)
 
+### Introduction
+
+There are 3 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.
+
+
+#### The configuration file
+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 [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"
 `
 
-Options that are available in the configuration file can be specified at run time when calling actions. Two examples:
+[//]: # (** online usage:**)
-```
-- /review --pr_reviewer.extra_instructions="focus on the file: ..."
-- /describe --pr_description.add_original_user_description=false -pr_description.extra_instructions="make sure to mention: ..."
-```
 
-### Working from CLI
+[//]: # (Options that are available in the configuration file can be specified at run time when calling actions. Two examples:)
-When running from source (CLI), your local configuration file will be used.
+
+[//]: # (```)
+
+[//]: # (- /review --pr_reviewer.extra_instructions="focus on the file: ...")
+
+[//]: # (- /describe --pr_description.add_original_user_description=false -pr_description.extra_instructions="make sure to mention: ...")
+
+[//]: # (```)
+
+### 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:
 
@@ -29,7 +61,10 @@ Examples for invoking the different tools via the CLI:
 
 **Notes:**
 
-(1) In addition to general configuration options, each tool has its own configurations. For example, the 'review' tool will use parameters from the `[pr_reviewer]` section in the [configuration file](/pr_agent/settings/configuration.toml#L16)
+(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: ..."
+```
 
 (2) You can print results locally, without publishing them, by setting in `configuration.toml`:
 ```
@@ -39,11 +74,33 @@ verbosity_level=2
 ```
 This is useful for debugging or experimenting with the different tools.
 
-### Working from GitHub App (pre-built repo)
-When running PR-Agent from GitHub App, the default configuration file (`configuration.toml`) will be initially loaded.
 
-#### GitHub app default tools
+### Online usage
-The `[github_app]` section defines the GitHub app specific configurations. 
+
+Online usage means invoking PR-Agent tools by [comments](https://github.com/Codium-ai/pr-agent/pull/229#issuecomment-1695021901) on a PR.
+Commands for invoking the different tools via comments:
+
+- **Review**:       `/review`
+- **Describe**:     `/describe`
+- **Improve**:      `/improve`
+- **Ask**:          `/ask "..."`
+- **Reflect**:      `/reflect`
+- **Update Changelog**:      `/update_changelog`
+
+
+To edit a specific configuration value, just add `--config_path=<value>` to any command.
+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.
+
+
+### 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.
+
+#### 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**:
 ```
 [github_app]
@@ -62,15 +119,15 @@ For example, if your local `.pr_agent.toml` file contains:
 add_original_user_description = false
 keep_original_user_title = false
 ```
-Then when a new PR is opened, PR-Agent will run the `describe` tool with the above parameters.
+When a new PR is opened, PR-Agent will run the `describe` tool with the above parameters.
 
 Note that a local `.pr_agent.toml` file enables you to edit and customize the default parameters of any tool, not just the ones that are run automatically.
 
 #### 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,
+In practice, the prompts are loaded and stored as a standard setting object. 
-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.
+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.
 
 For example, if you want to edit the prompts of the [describe](./pr_agent/settings/pr_description_prompts.toml) tool, you can add the following to your `.pr_agent.toml` file:
 ```
@@ -84,16 +141,10 @@ user="""
 ```
 Note that the new prompt will need to generate an output compatible with the relevant [post-process function](./pr_agent/tools/pr_description.py#L137).
 
-#### Online usage
+### Working with GitHub Action
-For online usage (calling tools by comments on a PR like `/ask ...`), just add `--config_path=<value>` to any command, to edit a specific configuration value.
+TBD
-For example if you want to edit `pr_reviewer` configurations, you can run:
-```
-/review --pr_reviewer.extra_instructions="..." --pr_reviewer.require_score_review=false ...
-```
-Any configuration value in `configuration.toml` file can be similarly edited.
 
-
+### Appendix - additional configurations walkthrough
-### General configuration walkthrough
 
 #### Changing a model
 See [here](pr_agent/algo/__init__.py) for the list of available models.