From 5917903a5a43797062d3290c0e696786435b865e Mon Sep 17 00:00:00 2001 From: ofir-frd Date: Tue, 3 Jun 2025 13:46:06 +0300 Subject: [PATCH] docs: implement hierarchical best practices system with detailed documentation --- docs/docs/tools/improve.md | 189 ++++++++++++++---- .../docs/usage-guide/configuration_options.md | 2 +- 2 files changed, 156 insertions(+), 35 deletions(-) diff --git a/docs/docs/tools/improve.md b/docs/docs/tools/improve.md index 2ca0c74c..21433bb5 100644 --- a/docs/docs/tools/improve.md +++ b/docs/docs/tools/improve.md @@ -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 diff --git a/docs/docs/usage-guide/configuration_options.md b/docs/docs/usage-guide/configuration_options.md index f3b91031..de00fdbc 100644 --- a/docs/docs/usage-guide/configuration_options.md +++ b/docs/docs/usage-guide/configuration_options.md @@ -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.