Improve

The improve tool scans the PR code changes, and automatically generates meaningful suggestions for improving the PR code.

Example usage

Suggestions Overview

Selecting a Specific Suggestion

Committable Code Comments

How to use the improve tool

Manual usage

Comment on the PR:

/improve

You can also add configuration flags to the command to customize behavior:

/improve --pr_code_suggestions.some_config1=... --pr_code_suggestions.some_config2=...

Automatic usage

To run the tool automatically when a PR is opened, add it to your configuration file:

[github_app]
pr_commands = [
    "/improve",
    ...
]

[pr_code_suggestions]
num_code_suggestions_per_chunk = ...
...

Learn more about automatic usage of tools.

When you first install Qodo Merge app, the default mode for the improve tool is:

pr_commands = ["/improve", ...]

Meaning the review tool will run automatically on every PR, without any additional configurations. Edit this field to enable/disable the tool, or to change the configurations used.

Code suggestions elements

Each generated suggestion consists of three key elements:

1. A single-line summary of the proposed change.

2. An expandable section containing a description of the suggestion.

3. A diff snippet showing the recommended code modification (before and after).

Interactive options

After using the improve tool, you can immediately trigger actions and apply changes with simple checkbox clicks:

• Apply this suggestion button: Clicking this checkbox instantly converts a suggestion into a committable code change. When committed to the PR, changes made to code that was flagged for improvement will be marked with a check mark, allowing developers to easily track and review implemented recommendations.

• More button: Triggers additional suggestions generation while keeping each suggestion focused and relevant as the original set

• Update button: Triggers a re-analysis of the code, providing updated suggestions based on the latest changes

• Author self-review button: Interactive acknowledgment that developers have opened and reviewed collapsed suggestions

Configuration Options

Configuration Options Table

Configure the improve tool by setting configurations under the pr_code_suggestions part in your configuration file.

General options

Params for number of suggestions and AI calls

Other features of the improve tool

Best Practices

Another option to give additional guidance to the AI model is by creating a best_practices.md file in your repository's root directory.

You can also setup a wiki page in GitHub.

Extra instructions

Extra instructions are important. The imrpove tool can be configured with extra instructions, which can be used to guide Qodo Merge to a feedback tailored to the needs of your project.

Be specific, clear, and concise in the instructions. With extra instructions, you are the prompter. Specify the relevant sub-tool, and the relevant aspects of the PR that you want to emphasize.

Examples of extra instructions:

[pr_code_suggestions]
extra_instructions="""\
(1) Answer in Japanese
(2) Don't suggest to add try-except block
(3) Ignore changes in toml files
...
"""

Use triple quotes to write multi-line instructions.

Dual publishing mode

Dual publishing mode allows code suggestions to appear as commit-ready comments in the PR.

This mode helps highlight suggestions that are more critical.

To activate dual publishing mode, use the following setting:

[pr_code_suggestions]
dual_publishing_score_threshold = x # The minimum score threshold >=

Where x represents the minimum score threshold (>=) for suggestions to be presented as commitable PR comments in addition to the table. The default value is -1 (disabled).

Self-review

You can set the improve tool to add a checkbox below the suggestions, prompting users to acknowledge that they have reviewed them.

In your configuration file, set:

[pr_code_suggestions]
demand_code_suggestions_self_review = true 

You can set the content of the checkbox text via:

[pr_code_suggestions]
code_suggestions_self_review_text = "... (your text here) ..."

Make self-review mandatory

To enforce self-review before merging, add the following to your configuration file:

[pr_code_suggestions]
approve_pr_on_self_review = true

This allows Qodo Merge to automatically approve the PR when the author checks the self-review box.

When used together with a minimum of 2 as the required number of approvals, this ensures the PR author must complete a self-review for the PR to be mergeable.

Auto-approval

Qodo Merge can auto-approve a PR when a specific comment is invoked, or when the PR meets certain criteria.

To ensure safety, the auto-approval feature is disabled by default.

To enable auto-approval features, you need to set one or both of the following options in your configuration file:

1. Auto-approval by commenting

To enable auto-approval by commenting, set in the configuration file:

[config]
enable_comment_approval = true

After setting, comment on a PR:

/review auto_approve

Qodo Merge will automatically approve the PR, and add a comment with the approval.

2. Auto-approval when the PR meets a condition

To enable auto-approval based on specific criteria, set in the configuration file:

[config]
enable_auto_approval = true

You can configure auto-approval to trigger based on either of these two conditions:

1. Review effort score

[config]
enable_auto_approval = true
auto_approve_for_low_review_effort = X # X is a number between 1 to 5

When the review effort score is lower or equal to X, the PR will be auto-approved.

1. No code suggestions

[config]
enable_auto_approval = true
auto_approve_for_no_suggestions = true

When no code suggestion were found for the PR, the PR will be auto-approved.

Automatic updates on new commits - the Update button

When new commits are pushed after a recent code suggestions report on a pull request, an Update button appears (as shown below).

Clicking this button triggers the /improve tool, which:

1. Detects what's changed since the last report

2. Generates suggestions based on those new changes

3. Merges these suggestions with the overall PR feedback, highlighting recent updates

4. Marks change-related comments with a note and an asterisk (*), including a link to this page for easy reference

Benefits for Developers

• Stay focused: Get feedback on the most recent changes first

• Stay organized: Comments related to new commits are clearly marked

• Stay efficient: Tackle feedback in order, starting with what's new