From e7f874a4b211484a725a94450473f6419b585f0f Mon Sep 17 00:00:00 2001 From: mrT23 Date: Sun, 19 Jan 2025 14:37:49 +0200 Subject: [PATCH 1/6] docs: improve diff format documentation and code review instructions --- docs/docs/core-abilities/metadata.md | 10 +++---- .../settings/pr_code_suggestions_prompts.toml | 29 ++++++++++++------- .../pr_code_suggestions_reflect_prompts.toml | 10 +++---- pr_agent/settings/pr_reviewer_prompts.toml | 14 ++++----- 4 files changed, 35 insertions(+), 28 deletions(-) diff --git a/docs/docs/core-abilities/metadata.md b/docs/docs/core-abilities/metadata.md index 2b90b0153..c1eb04c0c 100644 --- a/docs/docs/core-abilities/metadata.md +++ b/docs/docs/core-abilities/metadata.md @@ -32,14 +32,14 @@ For example, when generating code suggestions for different files, Qodo Merge ca @@ ... @@ def func1(): __new hunk__ -11 unchanged code line0 in the PR -12 unchanged code line1 in the PR -13 +new code line2 added in the PR -14 unchanged code line3 in the PR +11 unchanged code line0 +12 unchanged code line1 +13 +new code line2 added +14 unchanged code line3 __old hunk__ unchanged code line0 unchanged code line1 --old code line2 removed in the PR +-old code line2 removed unchanged code line3 @@ ... @@ def func2(): diff --git a/pr_agent/settings/pr_code_suggestions_prompts.toml b/pr_agent/settings/pr_code_suggestions_prompts.toml index a3b62aab5..4604174e0 100644 --- a/pr_agent/settings/pr_code_suggestions_prompts.toml +++ b/pr_agent/settings/pr_code_suggestions_prompts.toml @@ -17,30 +17,36 @@ The PR code diff will be in the following structured format: @@ ... @@ def func1(): __new hunk__ - unchanged code line0 in the PR - unchanged code line1 in the PR -+new code line2 added in the PR - unchanged code line3 in the PR + unchanged code line0 + unchanged code line1 ++new code line2 added + unchanged code line3 __old hunk__ unchanged code line0 unchanged code line1 --old code line2 removed in the PR +-old code line2 removed unchanged code line3 @@ ... @@ def func2(): __new hunk__ unchanged code line4 -+new code line5 removed in the PR ++new code line5 removed unchanged code line6 ## File: 'src/file2.py' ... ====== -- In the format above, the diff is organized into separate '__new hunk__' and '__old hunk__' sections for each code chunk. '__new hunk__' contains the updated code, while '__old hunk__' shows the removed code. If no code was removed in a specific chunk, the __old hunk__ section will be omitted. -- Code lines are prefixed with symbols: '+' for new code added in the PR, '-' for code removed, and ' ' for unchanged code. +Important notes about the structred diff format above: +1. Each PR code chunk is decoupled into separate '__new hunk__' and '__old hunk__' sections: + - The '__new hunk__' section shows the code chunk AFTER the PR changes. + - The '__old hunk__' section shows the code chunk BEFORE the PR changes. If no code was removed from the chunk, the '__old hunk__' section will be omitted. +2. The diff uses line prefixes to show changes: + '+' → new line code added (will appear only in '__new hunk__') + '-' → line code removed (will appear only in '__old hunk__') + ' ' → unchanged context lines (will appear in both sections) {%- if is_ai_metadata %} -- When available, an AI-generated summary will precede each file's diff, with a high-level overview of the changes. Note that this summary may not be fully accurate or complete. +3. When available, an AI-generated summary will precede each file's diff, with a high-level overview of the changes. Note that this summary may not be fully accurate or complete. {%- endif %} @@ -50,7 +56,8 @@ Specific guidelines for generating code suggestions: {%- else %} - Provide up to {{ num_code_suggestions }} distinct and insightful code suggestions. Return less suggestions if no pertinent ones are applicable. {%- endif %} -- Focus solely on enhancing new code introduced in the PR, identified by '+' prefixes in '__new hunk__' sections. +- DO NOT suggest implementing changes that are already present in the '+' lines compared to the '-' lines. +- Focus your suggestions ONLY on new code introduced in the PR ('+' lines in '__new hunk__' sections). {%- if not focus_only_on_problems %} - Prioritize suggestions that address potential issues, critical problems, and bugs in the PR code. Avoid repeating changes already implemented in the PR. If no pertinent suggestions are applicable, return an empty list. - Don't suggest to add docstring, type hints, or comments, to remove unused imports, or to use more specific exception types. @@ -59,7 +66,7 @@ Specific guidelines for generating code suggestions: - Do not suggest to change packages versions. {%- endif %} - When mentioning code elements (variables, names, or files) in your response, surround them with backticks (`). For example: "verify that `user_id` is..." -- Remember that Pull Request reviews show only changed code segments (diff hunks), not the entire codebase. Without full context, be cautious about suggesting modifications that could duplicate existing functionality (such as error handling) or questioning variable declarations that may exist elsewhere. Keep your review focused on the visible changes, acknowledging they're part of a larger codebase. +- Remember: PR diffs show only changed code segments, not the full codebase. Focus your review on visible changes and be cautious about suggesting changes that may duplicate existing unseen functionality in the codebase. {%- if extra_instructions %} diff --git a/pr_agent/settings/pr_code_suggestions_reflect_prompts.toml b/pr_agent/settings/pr_code_suggestions_reflect_prompts.toml index 16ffb4357..c8e4b5ac4 100644 --- a/pr_agent/settings/pr_code_suggestions_reflect_prompts.toml +++ b/pr_agent/settings/pr_code_suggestions_reflect_prompts.toml @@ -49,14 +49,14 @@ The PR code diff will be presented in the following structured format: @@ ... @@ def func1(): __new hunk__ -11 unchanged code line0 in the PR -12 unchanged code line1 in the PR -13 +new code line2 added in the PR -14 unchanged code line3 in the PR +11 unchanged code line0 +12 unchanged code line1 +13 +new code line2 added +14 unchanged code line3 __old hunk__ unchanged code line0 unchanged code line1 --old code line2 removed in the PR +-old code line2 removed unchanged code line3 @@ ... @@ def func2(): diff --git a/pr_agent/settings/pr_reviewer_prompts.toml b/pr_agent/settings/pr_reviewer_prompts.toml index fb5a134ef..816416ec1 100644 --- a/pr_agent/settings/pr_reviewer_prompts.toml +++ b/pr_agent/settings/pr_reviewer_prompts.toml @@ -16,20 +16,20 @@ The format we will use to present the PR code diff: @@ ... @@ def func1(): __new hunk__ -11 unchanged code line0 in the PR -12 unchanged code line1 in the PR -13 +new code line2 added in the PR -14 unchanged code line3 in the PR +11 unchanged code line0 +12 unchanged code line1 +13 +new code line2 added +14 unchanged code line3 __old hunk__ unchanged code line0 unchanged code line1 --old code line2 removed in the PR +-old code line2 removed unchanged code line3 @@ ... @@ def func2(): __new hunk__ unchanged code line4 -+new code line5 removed in the PR ++new code line5 removed unchanged code line6 ## File: 'src/file2.py' @@ -43,7 +43,7 @@ __new hunk__ {%- if is_ai_metadata %} - If available, an AI-generated summary will appear and provide a high-level overview of the file changes. Note that this summary may not be fully accurate or complete. {%- endif %} -- When quoting variables or names from the code, use backticks (`) instead of single quote ('). +- When quoting variables, names or file paths from the code, use backticks (`) instead of single quote ('). {%- if extra_instructions %} From ad4a96caf1b7220f81ef5f1bb9c2c2cd44f5cea5 Mon Sep 17 00:00:00 2001 From: mrT23 Date: Sun, 19 Jan 2025 15:05:38 +0200 Subject: [PATCH 2/6] docs: add wiki setup guide and update best practices documentation --- docs/docs/tools/improve.md | 2 +- docs/docs/usage-guide/enabling_a_wiki.md | 23 +++++++++++++++++++++++ docs/docs/usage-guide/index.md | 1 + docs/mkdocs.yml | 1 + 4 files changed, 26 insertions(+), 1 deletion(-) create mode 100644 docs/docs/usage-guide/enabling_a_wiki.md diff --git a/docs/docs/tools/improve.md b/docs/docs/tools/improve.md index ba9a0695f..fd16a609f 100644 --- a/docs/docs/tools/improve.md +++ b/docs/docs/tools/improve.md @@ -122,7 +122,7 @@ Use triple quotes to write multi-line instructions. Use bullet points or numbers >`Platforms supported: GitHub, GitLab, Bitbucket` -Another option to give additional guidance to the AI model is by creating a dedicated [**wiki page**](https://github.com/Codium-ai/pr-agent/wiki) called `best_practices.md`. +Another option to give additional guidance to the AI model is by creating a `best_practices.md` file, either in your repository's root directory or as a [**wiki page**](https://github.com/Codium-ai/pr-agent/wiki) (we recommend the wiki page, as editing and maintaining it over time is easier). This page can contain a list of best practices, coding standards, and guidelines that are specific to your repo/organization. The AI model will use this wiki page as a reference, and in case the PR code violates any of the guidelines, it will create additional suggestions, with a dedicated label: `Organization diff --git a/docs/docs/usage-guide/enabling_a_wiki.md b/docs/docs/usage-guide/enabling_a_wiki.md new file mode 100644 index 000000000..be0dbec78 --- /dev/null +++ b/docs/docs/usage-guide/enabling_a_wiki.md @@ -0,0 +1,23 @@ + + +For optimal functionality of Qodo Merge, we recommend enabling a wiki for each repository where Qodo Merge is installed. The wiki serves several important purposes: + +**Key Wiki Features:** + +- Storing a [configuration file](https://qodo-merge-docs.qodo.ai/usage-guide/configuration_options/#wiki-configuration-file) +- Defining a [`best_practices.md`](https://qodo-merge-docs.qodo.ai/tools/improve/#best-practices) file +- Track [accepted suggestions](https://qodo-merge-docs.qodo.ai/tools/improve/#suggestion-tracking) +- Facilitates learning over time by creating an [auto_best_practices.md]() file + + +**Setup Instructions:** + +To enable a wiki for your repository: + +1. Navigate to your repository's main page on GitHub +2. Select "Settings" from the top navigation bar +3. Locate the "Features" section +4. Enable the "Wikis" option by checking the corresponding box +5. Return to your repository's main page +6. Look for the newly added "Wiki" tab in the top navigation +7. Initialize your wiki by clicking "Create the first page" (this step is important - without creating an initial page, the wiki will not be fully functional) diff --git a/docs/docs/usage-guide/index.md b/docs/docs/usage-guide/index.md index 1b680d8c0..567ba9f33 100644 --- a/docs/docs/usage-guide/index.md +++ b/docs/docs/usage-guide/index.md @@ -5,6 +5,7 @@ It includes information on how to adjust Qodo Merge configurations, define which - [Introduction](./introduction.md) +- [Enabling a Wiki](./enabling_a_wiki) - [Configuration File](./configuration_options.md) - [Usage and Automation](./automations_and_usage.md) - [Local Repo (CLI)](./automations_and_usage.md#local-repo-cli) diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 9159197ed..2a4717a76 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -18,6 +18,7 @@ nav: - Usage Guide: - 'usage-guide/index.md' - Introduction: 'usage-guide/introduction.md' + - Enabling a Wiki: 'usage-guide/enabling_a_wiki.md' - Configuration File: 'usage-guide/configuration_options.md' - Usage and Automation: 'usage-guide/automations_and_usage.md' - Managing Mail Notifications: 'usage-guide/mail_notifications.md' From 24aa15f0749af0deefb5a4fe0837de1279430ac8 Mon Sep 17 00:00:00 2001 From: mrT23 Date: Sun, 19 Jan 2025 15:11:56 +0200 Subject: [PATCH 3/6] fix: correct typo in diff format documentation --- pr_agent/settings/pr_code_suggestions_prompts.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pr_agent/settings/pr_code_suggestions_prompts.toml b/pr_agent/settings/pr_code_suggestions_prompts.toml index 4604174e0..7d82675b3 100644 --- a/pr_agent/settings/pr_code_suggestions_prompts.toml +++ b/pr_agent/settings/pr_code_suggestions_prompts.toml @@ -37,7 +37,7 @@ __new hunk__ ... ====== -Important notes about the structred diff format above: +Important notes about the structured diff format above: 1. Each PR code chunk is decoupled into separate '__new hunk__' and '__old hunk__' sections: - The '__new hunk__' section shows the code chunk AFTER the PR changes. - The '__old hunk__' section shows the code chunk BEFORE the PR changes. If no code was removed from the chunk, the '__old hunk__' section will be omitted. From 87a5a7e1563a4dd47e83927f6f6f1b53a6b4f7f2 Mon Sep 17 00:00:00 2001 From: mrT23 Date: Sun, 19 Jan 2025 17:10:04 +0200 Subject: [PATCH 4/6] fix: improve code review guidelines and clarify scope limitations --- pr_agent/settings/pr_code_suggestions_prompts.toml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pr_agent/settings/pr_code_suggestions_prompts.toml b/pr_agent/settings/pr_code_suggestions_prompts.toml index 7d82675b3..e9232e6aa 100644 --- a/pr_agent/settings/pr_code_suggestions_prompts.toml +++ b/pr_agent/settings/pr_code_suggestions_prompts.toml @@ -63,10 +63,10 @@ Specific guidelines for generating code suggestions: - Don't suggest to add docstring, type hints, or comments, to remove unused imports, or to use more specific exception types. {%- else %} - Only give suggestions that address critical problems and bugs in the PR code. If no relevant suggestions are applicable, return an empty list. -- Do not suggest to change packages versions. +- Do not suggest to change packages version, add missing import statement, or decalre undefined variable. {%- endif %} - When mentioning code elements (variables, names, or files) in your response, surround them with backticks (`). For example: "verify that `user_id` is..." -- Remember: PR diffs show only changed code segments, not the full codebase. Focus your review on visible changes and be cautious about suggesting changes that may duplicate existing unseen functionality in the codebase. +- Note that you only see changed code segments (diff hunks in a PR), not the entire codebase. Avoid suggesting modifications that might duplicate existing functionality or questioning code elements (like variables declerations or import statements) that are not visible from the PR scope but may be defined elsewhere in the codebase. {%- if extra_instructions %} From b335cacffd408faf1802a5b092069649c2786ca9 Mon Sep 17 00:00:00 2001 From: mrT23 Date: Sun, 19 Jan 2025 17:15:02 +0200 Subject: [PATCH 5/6] fix: limit one_sentence_summary to 6 words in code suggestions --- pr_agent/settings/pr_code_suggestions_prompts.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pr_agent/settings/pr_code_suggestions_prompts.toml b/pr_agent/settings/pr_code_suggestions_prompts.toml index e9232e6aa..b2c2e33d0 100644 --- a/pr_agent/settings/pr_code_suggestions_prompts.toml +++ b/pr_agent/settings/pr_code_suggestions_prompts.toml @@ -86,7 +86,7 @@ class CodeSuggestion(BaseModel): suggestion_content: str = Field(description="An actionable suggestion to enhance, improve or fix the new code introduced in the PR. Don't present here actual code snippets, just the suggestion. Be short and concise") existing_code: str = Field(description="A short code snippet from a '__new hunk__' section that the suggestion aims to enhance or fix. Include only complete code lines. Use ellipsis (...) for brevity if needed. This snippet should represent the specific PR code targeted for improvement.") improved_code: str = Field(description="A refined code snippet that replaces the 'existing_code' snippet after implementing the suggestion.") - one_sentence_summary: str = Field(description="A concise, single-sentence overview of the suggested improvement. Focus on the 'what'. Be general, and avoid method or variable names.") + one_sentence_summary: str = Field(description="A concise, single-sentence overview (up to 6 words) of the suggested improvement. Focus on the 'what'. Be general, and avoid method or variable names.") {%- if not focus_only_on_problems %} label: str = Field(description="A single, descriptive label that best characterizes the suggestion type. Possible labels include 'security', 'possible bug', 'possible issue', 'performance', 'enhancement', 'best practice', 'maintainability', 'typo'. Other relevant labels are also acceptable.") {%- else %} From 67d4c96166296b60962594f030a6dad1f428cd84 Mon Sep 17 00:00:00 2001 From: mrT23 Date: Sun, 19 Jan 2025 17:21:48 +0200 Subject: [PATCH 6/6] fix: correct typos in code suggestions prompt --- pr_agent/settings/pr_code_suggestions_prompts.toml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pr_agent/settings/pr_code_suggestions_prompts.toml b/pr_agent/settings/pr_code_suggestions_prompts.toml index b2c2e33d0..3a734a258 100644 --- a/pr_agent/settings/pr_code_suggestions_prompts.toml +++ b/pr_agent/settings/pr_code_suggestions_prompts.toml @@ -63,10 +63,10 @@ Specific guidelines for generating code suggestions: - Don't suggest to add docstring, type hints, or comments, to remove unused imports, or to use more specific exception types. {%- else %} - Only give suggestions that address critical problems and bugs in the PR code. If no relevant suggestions are applicable, return an empty list. -- Do not suggest to change packages version, add missing import statement, or decalre undefined variable. +- Do not suggest to change packages version, add missing import statement, or declare undefined variable. {%- endif %} - When mentioning code elements (variables, names, or files) in your response, surround them with backticks (`). For example: "verify that `user_id` is..." -- Note that you only see changed code segments (diff hunks in a PR), not the entire codebase. Avoid suggesting modifications that might duplicate existing functionality or questioning code elements (like variables declerations or import statements) that are not visible from the PR scope but may be defined elsewhere in the codebase. +- Note that you only see changed code segments (diff hunks in a PR), not the entire codebase. Avoid suggestions that might duplicate existing functionality or questioning code elements (like variables declerations or import statements) that may be defined elsewhere in the codebase. {%- if extra_instructions %}