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

Merge pull request #1844 from qodo-ai/of/best-practices-hierarchy

Browse Source 
docs: add global hierarchical best practices system
This commit is contained in:
ofir-frd
2025-06-04 08:14:46 +03:00
committed by GitHub
parent 7d21c84c93 5917903a5a
commit 2a84c841da
2 changed files with 156 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files

189
docs/docs/tools/improve.md
View File

@ -144,52 +144,173 @@ Use triple quotes to write multi-line instructions. Use bullet points or numbers
> `💎 feature. Platforms supported: GitHub, GitLab, Bitbucket`
Another option to give additional guidance to the AI model is by creating a `best_practices.md` file in your repository's root directory.
This page can contain a list of best practices, coding standards, and guidelines that are specific to your repo/organization.
Qodo Merge supports both simple and hierarchical best practices configurations to provide guidance to the AI model for generating relevant code suggestions.
The AI model will use this `best_practices.md` file as a reference, and in case the PR code violates any of the guidelines, it will create additional suggestions, with a dedicated label: `Organization
best practice`.
???- tip "Writing effective best practices files"
The following guidelines apply to all best practices files:
- Write clearly and concisely
- Include brief code examples when helpful with before/after patterns
- Focus on project-specific guidelines that will result in relevant suggestions you actually want to get
- Keep each file relatively short, under 800 lines, since:
- AI models may not process effectively very long documents
- Long files tend to contain generic guidelines already known to AI
- Use pattern-based structure rather than simple bullet points for better clarity
Example for a Python `best_practices.md` content:
???- tip "Example of a best practices file"
Pattern 1: Add proper error handling with try-except blocks around external function calls.
Example code before:
```markdown
## Project best practices
- Make sure that I/O operations are encapsulated in a try-except block
- Use the `logging` module for logging instead of `print` statements
- Use `is` and `is not` to compare with `None`
- Use `if __name__ == '__main__':` to run the code only when the script is executed
- Use `with` statement to open files
...
```
```python
# Some code that might raise an exception
return process_pr_data(data)
```
Tips for writing an effective `best_practices.md` file:
Example code after:
- Write clearly and concisely
- Include brief code examples when helpful
- Focus on project-specific guidelines, that will result in relevant suggestions you actually want to get
- Keep the file relatively short, under 800 lines, since:
- AI models may not process effectively very long documents
- Long files tend to contain generic guidelines already known to AI
```python
try:
# Some code that might raise an exception
return process_pr_data(data)
except Exception as e:
logger.exception("Failed to process request", extra={"error": e})
```
To control the number of best practices suggestions generated by the `improve` tool, give the following configuration:
Pattern 2: Add defensive null/empty checks before accessing object properties or performing operations on potentially null variables to prevent runtime errors.
Example code before:
```toml
[best_practices]
num_best_practice_suggestions = 2
```
```python
def get_pr_code(pr_data):
if "changed_code" in pr_data:
return pr_data.get("changed_code", "")
return ""
```
#### Local and global best practices
Example code after:
By default, Qodo Merge will look for a local `best_practices.md` in the root of the relevant local repo.
```python
def get_pr_code(pr_data):
if pr_data is None:
return ""
if "changed_code" in pr_data:
return pr_data.get("changed_code", "")
return ""
```
If you want to enable also a global `best_practices.md` file, set first in the global configuration file:
#### Local best practices
```toml
[best_practices]
enable_global_best_practices = true
```
For basic usage, create a `best_practices.md` file in your repository's root directory containing a list of best practices, coding standards, and guidelines specific to your repository.
Then, create a `best_practices.md` file in the root of [global](https://qodo-merge-docs.qodo.ai/usage-guide/configuration_options/#global-configuration-file) configuration repository, `pr-agent-settings`.
The AI model will use this `best_practices.md` file as a reference, and in case the PR code violates any of the guidelines, it will create additional suggestions, with a dedicated label: `Organization best practice`.
#### Global hierarchical best practices
For organizations managing multiple repositories with different requirements, Qodo Merge supports a hierarchical best practices system using a dedicated global configuration repository.
**Supported scenarios:**
1. **Standalone repositories**: Individual repositories can have their own specific best practices tailored to their unique requirements
2. **Groups of repositories**: Repositories can be mapped to shared group-level best practices for consistent standards across similar projects
3. **Monorepos with subprojects**: Large monorepos can have both repository-level and subproject-level best practices, with automatic path-based matching
???- info "Setting up global hierarchical best practices"
1\. Create a new repository named `pr-agent-settings` in your organization/workspace.
2\. Build the folder hierarchy in your `pr-agent-settings` repository, for example:
```bash
pr-agent-settings/
├── metadata.yaml # Maps repos/folders to best practice paths
└── codebase_standards/ # Root for all best practice definitions
├── global/ # Global rules, inherited widely
│ └── best_practices.md
├── groups/ # For groups of repositories
│ ├── frontend_repos/
│ │ └── best_practices.md
│ ├── backend_repos/
│ │ └── best_practices.md
│ └── ...
├── qodo-merge/ # For standalone repositories
│ └── best_practices.md
├── qodo-monorepo/ # For monorepo-specific rules
│ ├── best_practices.md # Root level monorepo rules
│ ├── qodo-github/ # Subproject best practices
│ │ └── best_practices.md
│ └── qodo-gitlab/ # Another subproject
│ └── best_practices.md
└── ... # More repositories
```
3\. Define the metadata file `metadata.yaml` that maps your repositories to their relevant best practices paths, for example:
```yaml
# Standalone repos
qodo-merge:
best_practices_paths:
- "qodo-merge"
# Group-associated repos
repo_b:
best_practices_paths:
- "groups/backend_repos"
# Multi-group repos
repo_c:
best_practices_paths:
- "groups/frontend_repos"
- "groups/backend_repos"
# Monorepo with subprojects
qodo-monorepo:
best_practices_paths:
- "qodo-monorepo"
monorepo_subprojects:
qodo-github:
best_practices_paths:
- "qodo-monorepo/qodo-github"
qodo-gitlab:
best_practices_paths:
- "qodo-monorepo/qodo-gitlab"
```
4\. Set the following configuration in your global configuration file:
```toml
[best_practices]
enable_global_best_practices = true
```
???- info "Best practices priority and fallback behavior"
When global best practices are enabled, Qodo Merge follows this priority order:
1\. **Primary**: Global hierarchical best practices from `pr-agent-settings` repository:
1.1 If the repository is mapped in `metadata.yaml`, it uses the specified paths
1.2 For monorepos, it automatically collects best practices matching PR file paths
1.3 If no mapping exists, it falls back to the global best practices
2\. **Fallback**: Local repository `best_practices.md` file:
2.1 Used when global best practices are not found or configured
2.2 Acts as a safety net for repositories not yet configured in the global system
2.3 Local best practices are completely ignored when global best practices are successfully loaded
???- info "Edge cases and behavior"
- **Missing paths**: If specified paths in `metadata.yaml` don't exist in the file system, those paths are skipped
- **Monorepo subproject matching**: For monorepos, Qodo Merge automatically matches PR file paths against subproject paths to apply relevant best practices
- **Multiple group inheritance**: Repositories can inherit from multiple groups, and all applicable best practices are combined
#### Best practices for multiple languages

2
docs/docs/usage-guide/configuration_options.md
View File

@ -88,7 +88,7 @@ Create a dedicated project to hold a global configuration file that affects all
1. Create a new project with both the name and key: PR_AGENT_SETTINGS.
2. Inside the PR_AGENT_SETTINGS project, create a repository named pr-agent-settings.
3. In this repository, add a `.pr_agent.toml` configuration file—structured similarly to the global configuration file described above.
4. Optionally, you can add organizational-level [global best practices file](https://qodo-merge-docs.qodo.ai/usage-guide/configuration_options/#global-configuration-file).
4. Optionally, you can add organizational-level [global best practices](https://qodo-merge-docs.qodo.ai/tools/improve/#global-hierarchical-best-practices).
Repositories across your entire Bitbucket organization will inherit the configuration from this file.