docs: implement hierarchical best practices system with detailed documentation

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.
+Qodo Merge supports both simple and hierarchical best practices configurations to provide guidance to the AI model for generating relevant code suggestions.
-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 `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
+???- tip "Writing effective best practices files"
-best practice`.
+    
+    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
+    ```python
-## Project best practices
+    # Some code that might raise an exception
-- Make sure that I/O operations are encapsulated in a try-except block
+    return process_pr_data(data)
-- 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
-...
-```
 
-Tips for writing an effective `best_practices.md` file:
+    Example code after:
 
-- Write clearly and concisely
+    ```python
-- Include brief code examples when helpful
+    try:
-- Focus on project-specific guidelines, that will result in relevant suggestions you actually want to get
+        # Some code that might raise an exception
-- Keep the file relatively short, under 800 lines, since:
+        return process_pr_data(data)
-  - AI models may not process effectively very long documents
+    except Exception as e:
-  - Long files tend to contain generic guidelines already known to AI
+        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
+    ```python
-[best_practices]
+    def get_pr_code(pr_data):
-num_best_practice_suggestions = 2
+        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
+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.
-[best_practices]
-enable_global_best_practices = true
-```
 
-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
 

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.