docs: update hierarchical repository examples with generic naming conventions

[ofir-frd]

PR Type

Documentation

---

Description

• Replace Qodo-specific repository names with generic examples

• Add clarification note about hardcoded vs customizable names

• Update hierarchical repository structure examples consistently

---

Diagram Walkthrough

flowchart LR
  A["Qodo-specific names"] --> B["Generic examples"]
  B --> C["Added clarification note"]
  C --> D["Updated documentation"]

Loading

File Walkthrough

Relevant files

Documentation

compliance.md Update compliance tool examples with generic names              docs/docs/tools/compliance.md Replace qodo-merge, qodo-monorepo, qodo-github, qodo-gitlab with generic names Add note explaining hardcoded vs customizable naming conventions Update YAML configuration examples with new generic names +12/-10  improve.md Update improve tool examples with generic names                    docs/docs/tools/improve.md Replace Qodo-specific repository names with generic examples Add clarification note about required vs customizable names Update metadata YAML configuration with generic naming +14/-12

---

[qodo-free-for-open-source-projects]

PR Reviewer Guide 🔍

(Review updated until commit 08a683c)

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 2 🔵🔵⚪⚪⚪

🧪 No relevant tests

✅ No TODO sections

🔒 No security concerns identified

⚡ Recommended focus areas for review Consistency Verify that the new hardcoded directory name codebase_standards is consistently used across all related docs, examples, and configuration references to avoid confusion with the previously used compliance_standards. └── codebase_standards/ # Root for all compliance definitions ├── global/ # Global compliance, inherited widely │ └── pr_compliance_checklist.yaml ├── groups/ # For groups of repositories │ ├── frontend_repos/ │ │ └── pr_compliance_checklist.yaml │ ├── backend_repos/ │ │ └── pr_compliance_checklist.yaml │ ├── python_repos/ │ │ └── pr_compliance_checklist.yaml │ ├── cpp_repos/ │ │ └── pr_compliance_checklist.yaml │ └── ... ├── repo_a/ # For standalone repositories │ └── pr_compliance_checklist.yaml ├── monorepo-name/ # For monorepo-specific compliance │ ├── pr_compliance_checklist.yaml # Root-level monorepo compliance │ ├── service-a/ # Subproject compliance │ │ └── pr_compliance_checklist.yaml │ └── service-b/ # Another subproject │ └── pr_compliance_checklist.yaml └── ... # More repositories Note: In this structure, pr-agent-settings, codebase_standards, global, groups, metadata.yaml, and pr_compliance_checklist.yaml are hardcoded names that must be used exactly as shown. All other names (such as frontend_repos, backend_repos, repo_a, monorepo-name, service-a, etc.) are examples and should be replaced with your actual repository and service names. </details> <details><summary><a href='https://github.com/qodo-ai/pr-agent/pull/2019/files#diff-29b3d9a5a635d6b84da6187f673b2e128c0b5fbdba0c257c89de4b8c98ca3353R241-R291'><strong>Cross-doc Alignment</strong></a> Ensure the hardcoded names list and examples in Improve docs match the Compliance docs (e.g., `codebase_standards`, `metadata.yaml`) so users see a single, unified convention. </summary> ```markdown │ ├── cpp_repos/ │ │ └── best_practices.md │ └── ... ├── repo_a/ # For standalone repositories │ └── best_practices.md ├── monorepo-name/ # For monorepo-specific rules │ ├── best_practices.md # Root level monorepo rules │ ├── service-a/ # Subproject best practices │ │ └── best_practices.md │ └── service-b/ # Another subproject │ └── best_practices.md └── ... # More repositories Note: In this structure, pr-agent-settings, codebase_standards, global, groups, metadata.yaml, and best_practices.md are hardcoded names that must be used exactly as shown. All other names (such as frontend_repos, backend_repos, repo_a, monorepo-name, service-a, etc.) are examples and should be replaced with your actual repository and service names. ???+ tip "Grouping and categorizing best practices" - Each folder (including the global folder) can contain a single best_practices.md file - Organize repository best practices by creating subfolders within the groups folder. Group them by purpose, programming languages, or other categories 3. Define the metadata file metadata.yaml that maps your repositories to their relevant best practices paths, for example: # Standalone repos repo_a: best_practices_paths: - "repo_a" # 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 monorepo-name: best_practices_paths: - "monorepo-name" monorepo_subprojects: service-a: best_practices_paths: - "monorepo-name/service-a" service-b: best_practices_paths: - "monorepo-name/service-b" </details> </td></tr> </table>

[qodo-free-for-open-source-projects]

PR Code Suggestions ✨

Latest suggestions up to 08a683c

Category	Suggestion	Impact
Incremental [*]	Fix misaligned tree indentation Remove the extra space before monorepo-name/ to keep indentation aligned and ensure the tree renders correctly in monospace environments docs/docs/tools/compliance.md [168-193] ```bash pr-agent-settings/ ├── metadata.yaml # Maps repos/folders to compliance paths └── codebase_standards/ # Root for all compliance definitions ├── global/ # Global compliance, inherited widely │ └── pr_compliance_checklist.yaml ├── groups/ # For groups of repositories │ ├── cpp_repos/ │ │ └── pr_compliance_checklist.yaml │ └── ... ├── repo_a/ # For standalone repositories │ └── pr_compliance_checklist.yaml - ├── monorepo-name/ # For monorepo-specific compliance + ├── monorepo-name/ # For monorepo-specific compliance │ ├── pr_compliance_checklist.yaml # Root-level monorepo compliance │ ├── service-a/ # Subproject compliance │ │ └── pr_compliance_checklist.yaml │ └── service-b/ # Another subproject │ └── pr_compliance_checklist.yaml └── ... # More repositories `[To ensure code accuracy, apply this suggestion manually]` <details><summary>Suggestion importance[1-10]: 4</summary> __ Why: The suggestion correctly identifies and fixes a minor indentation inconsistency in the documentation's directory tree, which improves visual presentation. </details></details></td><td align=center>Low </td></tr><tr><td rowspan=2>General</td> <td> <details><summary>Clarify placeholder vs required names</summary> ___ **Clarify that only directory/file names are hardcoded while repository <br>identifiers in <code>metadata.yaml</code> (like <code>repo_a</code>, <code>monorepo-name</code>, subproject keys) must <br>match actual repo names. This prevents users from mistakenly keeping example <br>names in config, which would break path resolution.** [docs/docs/tools/compliance.md [195]](https://github.com/qodo-ai/pr-agent/pull/2019/files#diff-b8045d5c169d90b7c27ecb56d07893db83e096b854691b7f49eb73306201711aR195-R195) ```diff -> **Note:** In this structure, `pr-agent-settings`, `codebase_standards`, `global`, `groups`, `metadata.yaml`, and `pr_compliance_checklist.yaml` are hardcoded names that must be used exactly as shown. All other names (such as `frontend_repos`, `backend_repos`, `repo_a`, `monorepo-name`, `service-a`, etc.) are examples and should be replaced with your actual repository and service names. +> **Note:** The following names are hardcoded and must be used exactly as shown: folders `pr-agent-settings`, `codebase_standards`, `global`, `groups` and files `metadata.yaml`, `pr_compliance_checklist.yaml`. All other names (e.g., `frontend_repos`, `backend_repos`, `repo_a`, `monorepo-name`, `service-a`) are placeholders and must be replaced with your actual repository and subproject names. Ensure that repository and subproject identifiers in `metadata.yaml` exactly match your real repo and subproject names. Apply / Chat Suggestion importance[1-10]: 4 __ Why: The suggestion improves documentation clarity by explicitly distinguishing between hardcoded names and placeholders, which can help prevent user configuration errors.	Low
Emphasize required filename and consistency Explicitly state that best_practices.md is the required filename in each relevant directory and that placeholders must be replaced consistently across both the folder names and the metadata.yaml mappings. This avoids misconfigurations that cause the tool to fail loading best practices. docs/docs/tools/improve.md [255] -> **Note:** In this structure, `pr-agent-settings`, `codebase_standards`, `global`, `groups`, `metadata.yaml`, and `best_practices.md` are hardcoded names that must be used exactly as shown. All other names (such as `frontend_repos`, `backend_repos`, `repo_a`, `monorepo-name`, `service-a`, etc.) are examples and should be replaced with your actual repository and service names. +> **Note:** Use these names exactly: folders `pr-agent-settings`, `codebase_standards`, `global`, `groups`; files `metadata.yaml`, `best_practices.md` (the filename inside each relevant directory must be `best_practices.md`). All other names (e.g., `frontend_repos`, `backend_repos`, `repo_a`, `monorepo-name`, `service-a`) are placeholders and must be replaced consistently in both the folder structure and the `metadata.yaml` mappings. Apply / Chat Suggestion importance[1-10]: 4 __ Why: This suggestion enhances the documentation by clarifying the usage of best_practices.md and stressing the need for consistency, which helps prevent user misconfiguration.	Low
More

• Author self-review: I have reviewed the PR code suggestions, and addressed the relevant ones.

---

Previous suggestions

✅ Suggestions up to commit a53a935

Category	Suggestion	Impact
High-level	Align examples and constraints The monorepo_subprojects examples are inconsistent between compliance.md (frontend/backend keys referencing service-a/b paths) and improve.md (service-a/b keys), which is likely to confuse users; standardize the subproject identifiers across docs and clarify whether keys must match directory names. Also re-verify the new “hardcoded” list (pr-agent-settings, codebase_standards, global, groups, metadata.yaml, pr_compliance_checklist.yaml/best_practices.md); if any are configurable, document them as defaults and link to the configuration that controls them. Examples: docs/docs/tools/compliance.md [224-230] monorepo_subprojects: frontend: pr_compliance_checklist_paths: - "monorepo-name/service-a" backend: pr_compliance_checklist_paths: - "monorepo-name/service-b" docs/docs/tools/improve.md [284-290] monorepo_subprojects: service-a: best_practices_paths: - "monorepo-name/service-a" service-b: best_practices_paths: - "monorepo-name/service-b" Solution Walkthrough: Before: # In compliance.md monorepo-name: monorepo_subprojects: frontend: # logical name pr_compliance_checklist_paths: - "monorepo-name/service-a" backend: # logical name pr_compliance_checklist_paths: - "monorepo-name/service-b" # In improve.md monorepo-name: monorepo_subprojects: service-a: # directory name best_practices_paths: - "monorepo-name/service-a" service-b: # directory name best_practices_paths: - "monorepo-name/service-b" After: # In both compliance.md and improve.md (standardized) monorepo-name: monorepo_subprojects: # Key can be a logical name, not necessarily matching the directory. frontend_service: ..._paths: - "monorepo-name/service-a" backend_service: ..._paths: - "monorepo-name/service-b" # Note added to documentation: # > **Note:** ... `metadata.yaml`... are hardcoded names. # > The keys under `monorepo_subprojects` are logical names for your subprojects. Suggestion importance[1-10]: 9 __ Why: The suggestion correctly identifies a significant inconsistency in the documentation examples for monorepo_subprojects that could confuse users, and also wisely questions the absolute "hardcoded" nature of newly documented file names.	High
General	✅ Make subproject keys consistent Suggestion Impact: The commit changed the subproject keys from frontend/backend to service-a/service-b in the documented example, matching the suggestion. code diff: @@ -222,10 +222,10 @@ pr_compliance_checklist_paths: - "monorepo-name" monorepo_subprojects: - frontend: + service-a: pr_compliance_checklist_paths: - "monorepo-name/service-a" - backend: + service-b: pr_compliance_checklist_paths: - "monorepo-name/service-b" Align subproject keys with the directory names used in the tree and paths to avoid misconfiguration. Replace frontend/backend with service-a/service-b for consistency with the examples and the improve doc. docs/docs/tools/compliance.md [220-230] # Monorepo with subprojects monorepo-name: pr_compliance_checklist_paths: - "monorepo-name" monorepo_subprojects: - frontend: + service-a: pr_compliance_checklist_paths: - "monorepo-name/service-a" - backend: + service-b: pr_compliance_checklist_paths: - "monorepo-name/service-b" [Suggestion processed] Suggestion importance[1-10]: 7 __ Why: The suggestion correctly identifies an inconsistency in the documentation where subproject keys (frontend/backend) do not match the example directory names (service-a/service-b), and aligning them as suggested improves clarity and consistency with another documentation file.	Medium

[qodo-free-for-open-source-projects]

Persistent review updated to latest commit 08a683c