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

Improve markdown docs formatting for consistency and readability

Browse Source
This commit is contained in:
Peter Dave Hello
2025-04-18 02:03:47 +08:00
parent 58f6943b12
commit f0fc777a44
62 changed files with 547 additions and 403 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
docs/docs/core-abilities/auto_best_practices.md
View File

@ -1,4 +1,5 @@
# Auto Best Practices 💎
`Supported Git Platforms: GitHub`
## Overview
@ -9,17 +10,16 @@
### Finding Code Problems - Exploration Phase
The `improve` tool identifies potential issues, problems and bugs in Pull Request (PR) code changes.
Rather than focusing on minor issues like code style or formatting, the tool intelligently analyzes code to detect meaningful problems.
The `improve` tool identifies potential issues, problems and bugs in Pull Request (PR) code changes.
Rather than focusing on minor issues like code style or formatting, the tool intelligently analyzes code to detect meaningful problems.
The analysis intentionally takes a flexible, _exploratory_ approach to identify meaningful potential issues, allowing the tool to surface relevant code suggestions without being constrained by predefined categories.
### Tracking Implemented Suggestions
Qodo Merge features a novel [tracking system](https://qodo-merge-docs.qodo.ai/tools/improve/#suggestion-tracking) that automatically detects when PR authors implement AI-generated code suggestions.
Qodo Merge features a novel [tracking system](https://qodo-merge-docs.qodo.ai/tools/improve/#suggestion-tracking) that automatically detects when PR authors implement AI-generated code suggestions.
All accepted suggestions are aggregated in a repository-specific wiki page called [`.pr_agent_accepted_suggestions`](https://github.com/qodo-ai/pr-agent/wiki/.pr_agent_accepted_suggestions)
### Learning and Applying Auto Best Practices
Monthly, Qodo Merge analyzes the collection of accepted suggestions to generate repository-specific best practices, stored in [`.pr_agent_auto_best_practices`](https://github.com/qodo-ai/pr-agent/wiki/.pr_agent_auto_best_practices) wiki file.
@ -33,17 +33,15 @@ This creates a two-phase analysis:
By keeping these phases decoupled, the tool remains free to discover new or unseen issues and problems, while also learning from past experiences.
When presenting the suggestions generated by the `improve` tool, Qodo Merge will add a dedicated label for each suggestion generated from the auto best practices - 'Learned best practice':
![Auto best practice suggestion](https://www.qodo.ai/images/pr_agent/auto_best_practices.png){width=684}
## Auto Best Practices vs Custom Best Practices
Teams and companies can also manually define their own [custom best practices](https://qodo-merge-docs.qodo.ai/tools/improve/#best-practices) in Qodo Merge.
Teams and companies can also manually define their own [custom best practices](https://qodo-merge-docs.qodo.ai/tools/improve/#best-practices) in Qodo Merge.
When custom best practices exist, Qodo Merge will still generate an 'auto best practices' wiki file, though it won't be used by the `improve` tool.
When custom best practices exist, Qodo Merge will still generate an 'auto best practices' wiki file, though it won't be used by the `improve` tool.
However, this auto-generated file can still serve two valuable purposes:
1. It can help enhance your custom best practices with additional insights derived from suggestions your team found valuable enough to implement
@ -66,4 +64,4 @@ extra_instructions = ""
# Max number of patterns to be detected
max_patterns = 5
```
```

5
docs/docs/core-abilities/code_validation.md
View File

@ -1,4 +1,5 @@
## Introduction
The Git environment usually represents the final stage before code enters production. Hence, Detecting bugs and issues during the review process is critical.
The [`improve`](https://qodo-merge-docs.qodo.ai/tools/improve/) tool provides actionable code suggestions for your pull requests, aiming to help detect and fix bugs and problems.
@ -32,8 +33,8 @@ Read more about this process in the [self-reflection](https://qodo-merge-docs.qo
## Conclusion
The validation methods described above enhance the reliability of code suggestions and help PR authors determine which suggestions are safer to apply in the Git environment.
Of course, additional factors should be considered, such as suggestion complexity and potential code impact.
Of course, additional factors should be considered, such as suggestion complexity and potential code impact.
Human judgment remains essential. After clicking 'apply', Qodo Merge still presents the 'before' and 'after' code snippets for review, allowing you to assess the changes before finalizing the commit.
![improve](https://codium.ai/images/pr_agent/improve.png){width=512}
![improve](https://codium.ai/images/pr_agent/improve.png){width=512}

19
docs/docs/core-abilities/compression_strategy.md
View File

@ -1,5 +1,6 @@
## Overview - PR Compression Strategy
There are two scenarios:
1. The PR is small enough to fit in a single prompt (including system and user prompt)
@ -8,6 +9,7 @@ There are two scenarios:
For both scenarios, we first use the following strategy
#### Repo language prioritization strategy
We prioritize the languages of the repo based on the following criteria:
1. Exclude binary files and non code files (e.g. images, pdfs, etc)
@ -15,28 +17,33 @@ We prioritize the languages of the repo based on the following criteria:
3. We sort the PR files by the most common languages in the repo (in descending order):
* ```[[file.py, file2.py],[file3.js, file4.jsx],[readme.md]]```
### Small PR
In this case, we can fit the entire PR in a single prompt:
1. Exclude binary files and non code files (e.g. images, pdfs, etc)
2. We Expand the surrounding context of each patch to 3 lines above and below the patch
### Large PR
#### Motivation
Pull Requests can be very long and contain a lot of information with varying degree of relevance to the pr-agent.
We want to be able to pack as much information as possible in a single LMM prompt, while keeping the information relevant to the pr-agent.
#### Compression strategy
We prioritize additions over deletions:
- Combine all deleted files into a single list (`deleted files`)
- File patches are a list of hunks, remove all hunks of type deletion-only from the hunks in the file patch
#### Adaptive and token-aware file patch fitting
We prioritize additions over deletions:
* Combine all deleted files into a single list (`deleted files`)
* File patches are a list of hunks, remove all hunks of type deletion-only from the hunks in the file patch
#### Adaptive and token-aware file patch fitting
We use [tiktoken](https://github.com/openai/tiktoken) to tokenize the patches after the modifications described above, and we use the following strategy to fit the patches into the prompt:
1. Within each language we sort the files by the number of tokens in the file (in descending order):
- ```[[file2.py, file.py],[file4.jsx, file3.js],[readme.md]]```
* ```[[file2.py, file.py],[file4.jsx, file3.js],[readme.md]]```
2. Iterate through the patches in the order described above
3. Add the patches to the prompt until the prompt reaches a certain buffer from the max token length
4. If there are still patches left, add the remaining patches as a list called `other modified files` to the prompt until the prompt reaches the max token length (hard stop), skip the rest of the patches.

8
docs/docs/core-abilities/dynamic_context.md
View File

@ -7,7 +7,8 @@ This approach balances providing sufficient context for accurate analysis, while
## Introduction
Pull request code changes are retrieved in a unified diff format, showing three lines of context before and after each modified section, with additions marked by '+' and deletions by '-'.
```
```diff
@@ -12,5 +12,5 @@ def func1():
code line that already existed in the file...
code line that already existed in the file...
@ -25,7 +26,6 @@ Pull request code changes are retrieved in a unified diff format, showing three
This unified diff format can be challenging for AI models to interpret accurately, as it provides limited context for understanding the full scope of code changes.
The presentation of code using '+', '-', and ' ' symbols to indicate additions, deletions, and unchanged lines respectively also differs from the standard code formatting typically used to train AI models.
## Challenges of expanding the context window
While expanding the context window is technically feasible, it presents a more fundamental trade-off:
@ -43,6 +43,7 @@ Pull requests often encompass multiple changes across many files, potentially sp
- Increased context expands the token count, increasing processing time and cost, and may prevent the model from processing the entire pull request in a single pass.
## Asymmetric and dynamic context
To address these challenges, Qodo Merge employs an **asymmetric** and **dynamic** context strategy, providing the model with more focused and relevant context information for each code change.
**Asymmetric:**
@ -62,7 +63,8 @@ To prevent overwhelming the model with excessive context, we impose a limit on t
This balance allows for comprehensive understanding while maintaining efficiency and limiting context token usage.
## Appendix - relevant configuration options
```
```toml
[config]
patch_extension_skip_types =[".md",".txt"] # Skip files with these extensions when trying to extend the context
allow_dynamic_context=true # Allow dynamic context extension

12
docs/docs/core-abilities/fetching_ticket_context.md
View File

@ -1,7 +1,9 @@
# Fetching Ticket Context for PRs
`Supported Git Platforms: GitHub, GitLab, Bitbucket`
## Overview
Qodo Merge streamlines code review workflows by seamlessly connecting with multiple ticket management systems.
This integration enriches the review process by automatically surfacing relevant ticket information and context alongside code changes.
@ -27,16 +29,17 @@ Ticket Recognition Requirements:
- For Jira tickets, you should follow the instructions in [Jira Integration](https://qodo-merge-docs.qodo.ai/core-abilities/fetching_ticket_context/#jira-integration) in order to authenticate with Jira.
### Describe tool
Qodo Merge will recognize the ticket and use the ticket content (title, description, labels) to provide additional context for the code changes.
By understanding the reasoning and intent behind modifications, the LLM can offer more insightful and relevant code analysis.
### Review tool
Similarly to the `describe` tool, the `review` tool will use the ticket content to provide additional context for the code changes.
In addition, this feature will evaluate how well a Pull Request (PR) adheres to its original purpose/intent as defined by the associated ticket or issue mentioned in the PR description.
Each ticket will be assigned a label (Compliance/Alignment level), Indicates the degree to which the PR fulfills its original purpose, Options: Fully compliant, Partially compliant or Not compliant.
![Ticket Compliance](https://www.qodo.ai/images/pr_agent/ticket_compliance_review.png){width=768}
By default, the tool will automatically validate if the PR complies with the referenced ticket.
@ -63,6 +66,7 @@ Since Qodo Merge is integrated with GitHub, it doesn't require any additional co
We support both Jira Cloud and Jira Server/Data Center.
### Jira Cloud
There are two ways to authenticate with Jira Cloud:
**1) Jira App Authentication**
@ -101,7 +105,6 @@ jira_api_token = "YOUR_API_TOKEN"
jira_api_email = "YOUR_EMAIL"
```
### Jira Data Center/Server
[//]: # ()
@ -163,7 +166,6 @@ jira_api_email = "YOUR_EMAIL"
[//]: # (* You will be redirected back to Qodo Merge and you will see a success message.)
[//]: # (Personal Access Token (PAT) Authentication)
#### Using Basic Authentication for Jira Data Center/Server
@ -181,7 +183,7 @@ jira_api_token = "your_password"
##### Validating Basic authentication via Python script
If you are facing issues retrieving tickets in Qodo Merge with Basic auth, you can validate the flow using a Python script.
If you are facing issues retrieving tickets in Qodo Merge with Basic auth, you can validate the flow using a Python script.
This following steps will help you check if the basic auth is working correctly, and if you can access the Jira ticket details:
1. run `pip install jira==3.8.0`
@ -237,7 +239,7 @@ jira_api_token = "YOUR_API_TOKEN"
##### Validating PAT token via Python script
If you are facing issues retrieving tickets in Qodo Merge with PAT token, you can validate the flow using a Python script.
If you are facing issues retrieving tickets in Qodo Merge with PAT token, you can validate the flow using a Python script.
This following steps will help you check if the token is working correctly, and if you can access the Jira ticket details:
1. run `pip install jira==3.8.0`

7
docs/docs/core-abilities/impact_evaluation.md
View File

@ -3,22 +3,24 @@
Demonstrating the return on investment (ROI) of AI-powered initiatives is crucial for modern organizations.
To address this need, Qodo Merge has developed an AI impact measurement tools and metrics, providing advanced analytics to help businesses quantify the tangible benefits of AI adoption in their PR review process.
## Auto Impact Validator - Real-Time Tracking of Implemented Qodo Merge Suggestions
### How It Works
When a user pushes a new commit to the pull request, Qodo Merge automatically compares the updated code against the previous suggestions, marking them as implemented if the changes address these recommendations, whether directly or indirectly:
1. **Direct Implementation:** The user directly addresses the suggestion as-is in the PR, either by clicking on the "apply code suggestion" checkbox or by making the changes manually.
2. **Indirect Implementation:** Qodo Merge recognizes when a suggestion's intent is fulfilled, even if the exact code changes differ from the original recommendation. It marks these suggestions as implemented, acknowledging that users may achieve the same goal through alternative solutions.
### Real-Time Visual Feedback
Upon confirming that a suggestion was implemented, Qodo Merge automatically adds a ✅ (check mark) to the relevant suggestion, enabling transparent tracking of Qodo Merge's impact analysis.
Qodo Merge will also add, inside the relevant suggestions, an explanation of how the new code was impacted by each suggestion.
![Suggestion_checkmark](https://codium.ai/images/pr_agent/auto_suggestion_checkmark.png){width=512}
### Dashboard Metrics
The dashboard provides macro-level insights into the overall impact of Qodo Merge on the pull-request process with key productivity metrics.
By offering clear, data-driven evidence of Qodo Merge's impact, it empowers leadership teams to make informed decisions about the tool's effectiveness and ROI.
@ -26,6 +28,7 @@ By offering clear, data-driven evidence of Qodo Merge's impact, it empowers lead
Here are key metrics that the dashboard tracks:
#### Qodo Merge Impacts per 1K Lines
![Dashboard](https://codium.ai/images/pr_agent/impacts_per_1k_llines.png){width=512}
> Explanation: for every 1K lines of code (additions/edits), Qodo Merge had on average ~X suggestions implemented.
@ -36,9 +39,11 @@ Here are key metrics that the dashboard tracks:
3. **Quantifies Value and ROI:** The metric directly correlates with the value Qodo Merge is providing, showing how frequently it offers improvements relative to the amount of new code being written. This provides a clear, quantifiable way to demonstrate Qodo Merge's return on investment to stakeholders.
#### Suggestion Effectiveness Across Categories
![Impacted_Suggestion_Score](https://codium.ai/images/pr_agent/impact_by_category.png){width=512}
> Explanation: This chart illustrates the distribution of implemented suggestions across different categories, enabling teams to better understand Qodo Merge's impact on various aspects of code quality and development practices.
#### Suggestion Score Distribution
![Impacted_Suggestion_Score](https://codium.ai/images/pr_agent/impacted_score_dist.png){width=512}
> Explanation: The distribution of the suggestion score for the implemented suggestions, ensuring that higher-scored suggestions truly represent more significant improvements.

4
docs/docs/core-abilities/index.md
View File

@ -1,4 +1,5 @@
# Core Abilities
Qodo Merge utilizes a variety of core abilities to provide a comprehensive and efficient code review experience. These abilities include:
- [Auto best practices](https://qodo-merge-docs.qodo.ai/core-abilities/auto_best_practices/)
@ -20,13 +21,16 @@ Here are some additional technical blogs from Qodo, that delve deeper into the c
These resources provide more comprehensive insights into leveraging LLMs for software development.
### Code Generation and LLMs
- [Effective AI code suggestions: less is more](https://www.qodo.ai/blog/effective-code-suggestions-llms-less-is-more/)
- [State-of-the-art Code Generation with AlphaCodium – From Prompt Engineering to Flow Engineering](https://www.qodo.ai/blog/qodoflow-state-of-the-art-code-generation-for-code-contests/)
- [RAG for a Codebase with 10k Repos](https://www.qodo.ai/blog/rag-for-large-scale-code-repos/)
### Development Processes
- [Understanding the Challenges and Pain Points of the Pull Request Cycle](https://www.qodo.ai/blog/understanding-the-challenges-and-pain-points-of-the-pull-request-cycle/)
- [Introduction to Code Coverage Testing](https://www.qodo.ai/blog/introduction-to-code-coverage-testing/)
### Cost Optimization
- [Reduce Your Costs by 30% When Using GPT for Python Code](https://www.qodo.ai/blog/reduce-your-costs-by-30-when-using-gpt-3-for-python-code/)

12
docs/docs/core-abilities/interactivity.md
View File

@ -5,7 +5,7 @@
## Overview
Qodo Merge transforms static code reviews into interactive experiences by enabling direct actions from pull request (PR) comments.
Developers can immediately trigger actions and apply changes with simple checkbox clicks.
Developers can immediately trigger actions and apply changes with simple checkbox clicks.
This focused workflow maintains context while dramatically reducing the time between PR creation and final merge.
The approach eliminates manual steps, provides clear visual indicators, and creates immediate feedback loops all within the same interface.
@ -24,8 +24,7 @@ The [`/improve`](https://qodo-merge-docs.qodo.ai/tools/improve/) command deliver
- _**Author self-review**_: Interactive acknowledgment that developers have opened and reviewed collapsed suggestions
### 2\. Interactive `/analyze` Tool
### 2\. Interactive `/analyze` Tool
The [`/analyze`](https://qodo-merge-docs.qodo.ai/tools/analyze/) command provides component-level analysis with interactive options for each identified code component:
@ -35,9 +34,8 @@ The [`/analyze`](https://qodo-merge-docs.qodo.ai/tools/analyze/) command provide
- Component-specific actions that trigger only for the selected elements, providing focused assistance
### 3\. Interactive `/help` Tool
### 3\. Interactive `/help` Tool
The [`/help`](https://qodo-merge-docs.qodo.ai/tools/help/) command not only lists available tools and their descriptions but also enables immediate tool invocation through interactive checkboxes.
When a user checks a tool's checkbox, Qodo Merge instantly triggers that tool without requiring additional commands.
The [`/help`](https://qodo-merge-docs.qodo.ai/tools/help/) command not only lists available tools and their descriptions but also enables immediate tool invocation through interactive checkboxes.
When a user checks a tool's checkbox, Qodo Merge instantly triggers that tool without requiring additional commands.
This transforms the standard help menu into an interactive launch pad for all Qodo Merge capabilities, eliminating context switching by keeping developers within their PR workflow.

4
docs/docs/core-abilities/metadata.md
View File

@ -1,4 +1,5 @@
## Local and global metadata injection with multi-stage analysis
1\.
Qodo Merge initially retrieves for each PR the following data:
@ -23,7 +24,7 @@ This effectively enables multi-stage chain-of-thought analysis, without doing an
For example, when generating code suggestions for different files, Qodo Merge can inject the AI-generated ["Changes walkthrough"](https://github.com/Codium-ai/pr-agent/pull/1202#issue-2511546839) file summary in the prompt:
```
```diff
## File: 'src/file1.py'
### AI-generated file summary:
- edited function `func1` that does X
@ -51,6 +52,5 @@ __old hunk__
3\. The entire PR files that were retrieved are also used to expand and enhance the PR context (see [Dynamic Context](https://qodo-merge-docs.qodo.ai/core-abilities/dynamic_context/)).
4\. All the metadata described above represents several level of cumulative analysis - ranging from hunk level, to file level, to PR level, to organization level.
This comprehensive approach enables Qodo Merge AI models to generate more precise and contextually relevant suggestions and feedback.

10
docs/docs/core-abilities/rag_context_enrichment.md
View File

@ -6,7 +6,6 @@
- RAG is available only for Qodo enterprise plan users, with single tenant or on-premises setup.
- Database setup and codebase indexing must be completed before proceeding. [Contact support](https://www.qodo.ai/contact/) for more information.
## Overview
### What is RAG Context Enrichment?
@ -17,13 +16,13 @@ A feature that enhances AI analysis by retrieving and referencing relevant code
Using Retrieval-Augmented Generation (RAG), it searches your configured repositories for contextually relevant code segments, enriching pull request (PR) insights and accelerating review accuracy.
## Getting started
### Configuration options
In order to enable the RAG feature, add the following lines to your configuration file:
``` toml
```toml
[rag_arguments]
enable_rag=true
```
@ -45,7 +44,7 @@ enable_rag=true
#### 1\. The `/review` Tool
The [`/review`](https://qodo-merge-docs.qodo.ai/tools/review/) tool offers the _Focus area from RAG data_ which contains feedback based on the RAG references analysis.
The [`/review`](https://qodo-merge-docs.qodo.ai/tools/review/) tool offers the _Focus area from RAG data_ which contains feedback based on the RAG references analysis.
The complete list of references found relevant to the PR will be shown in the _References_ section, helping developers understand the broader context by exploring the provided references.
![References](https://codium.ai/images/pr_agent/rag_review.png){width=640}
@ -64,15 +63,16 @@ The _References_ section displays the additional repository content consulted to
![References](https://codium.ai/images/pr_agent/rag_ask.png){width=640}
## Limitations
### Querying the codebase presents significant challenges
- **Search Method**: RAG uses natural language queries to find semantically relevant code sections
- **Result Quality**: No guarantee that RAG results will be useful for all queries
- **Scope Recommendation**: To reduce noise, focus on the PR repository rather than searching across multiple repositories
### This feature has several requirements and restrictions
- **Codebase**: Must be properly indexed for search functionality
- **Security**: Requires secure and private indexed codebase implementation
- **Deployment**: Only available for Qodo Merge Enterprise plan using single tenant or on-premises setup

7
docs/docs/core-abilities/self_reflection.md
View File

@ -6,7 +6,6 @@ Configuration options allow users to set a score threshold for further filtering
## Introduction - Efficient Review with Hierarchical Presentation
Given that not all generated code suggestions will be relevant, it is crucial to enable users to review them in a fast and efficient way, allowing quick identification and filtering of non-applicable ones.
To achieve this goal, Qodo Merge offers a dedicated hierarchical structure when presenting suggestions to users:
@ -42,9 +41,9 @@ This results in a more refined and valuable set of suggestions for the user, sav
![self_reflection](https://codium.ai/images/pr_agent/self_reflection1.png){width=768}
![self_reflection](https://codium.ai/images/pr_agent/self_reflection2.png){width=768}
## Appendix - Relevant Configuration Options
```
```toml
[pr_code_suggestions]
suggestions_score_threshold = 0 # Filter out suggestions with a score below this threshold (0-10)
suggestions_score_threshold = 0 # Filter out suggestions with a score below this threshold (0-10)
```

8
docs/docs/core-abilities/static_code_analysis.md
View File

@ -7,14 +7,13 @@ It scans the PR code changes, finds all the code components (methods, functions,
!!! note "Language that are currently supported:"
Python, Java, C++, JavaScript, TypeScript, C#.
## Capabilities
### Analyze PR
The [`analyze`](https://qodo-merge-docs.qodo.ai/tools/analyze/) tool enables to interactively generate tests, docs, code suggestions and similar code search for each component that changed in the PR.
It can be invoked manually by commenting on any PR:
```
/analyze
```
@ -29,9 +28,11 @@ Clicking on each checkbox will trigger the relevant tool for the selected compon
The [`test`](https://qodo-merge-docs.qodo.ai/tools/test/) tool generate tests for a selected component, based on the PR code changes.
It can be invoked manually by commenting on any PR:
```
/test component_name
```
where 'component_name' is the name of a specific component in the PR, Or be triggered interactively by using the `analyze` tool.
![test1](https://codium.ai/images/pr_agent/test1.png){width=768}
@ -40,6 +41,7 @@ where 'component_name' is the name of a specific component in the PR, Or be tri
The [`add_docs`](https://qodo-merge-docs.qodo.ai/tools/documentation/) tool scans the PR code changes, and automatically generate docstrings for any code components that changed in the PR.
It can be invoked manually by commenting on any PR:
```
/add_docs component_name
```
@ -49,8 +51,10 @@ Or be triggered interactively by using the `analyze` tool.
![Docs single component](https://codium.ai/images/pr_agent/docs_single_component.png){width=768}
### Generate Code Suggestions for a Component
The [`improve_component`](https://qodo-merge-docs.qodo.ai/tools/improve_component/) tool generates code suggestions for a specific code component that changed in the PR.
It can be invoked manually by commenting on any PR:
```
/improve_component component_name
```