From 805d9cac69af9ebc000654d9977656d9d4ae0903 Mon Sep 17 00:00:00 2001 From: mrT23 Date: Sun, 26 Jan 2025 16:39:25 +0200 Subject: [PATCH] docs: add auto best practices diagrams and wiki usage explanation --- .../core-abilities/auto_best_practices.md | 24 +++++++++++-------- docs/docs/usage-guide/enabling_a_wiki.md | 15 +++++++++--- 2 files changed, 26 insertions(+), 13 deletions(-) diff --git a/docs/docs/core-abilities/auto_best_practices.md b/docs/docs/core-abilities/auto_best_practices.md index 99ab1f97..b9c9fba9 100644 --- a/docs/docs/core-abilities/auto_best_practices.md +++ b/docs/docs/core-abilities/auto_best_practices.md @@ -3,18 +3,21 @@ ## Overview +![Auto best practice suggestion graph](https://www.qodo.ai/images/pr_agent/auto_best_practices_graph.png){width=684} + + ### Finding Code Problems - Exploration Phase -Qodo Merge `improve` tool identifies potential issues, problems and bugs in Pull Request (PR) code changes. -Rather than focusing on generic concepts like code style, 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 is intentionally broad to allow identifying a wide range of potential issues. -This open-ended _exploration_ enables the tool to surface any relevant issues without being constrained to predefined categories. +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. -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). +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) +(Why Wiki - see [here](https://qodo-merge-docs.qodo.ai/usage-guide/enabling_a_wiki/#why-wiki)). ### Learning and Applying Auto Best Practices @@ -29,22 +32,23 @@ 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=512} +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 to evaluate PR code changes. +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 use it in the `improve` tool analysis. +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 2. It demonstrates effective patterns for writing AI-friendly best practices -We recommend regularly reviewing the auto best practices file to refine your custom rules, even when using custom best practices. +Even when using custom best practices, we recommend regularly reviewing the auto best practices file to refine your custom rules. ## Relevant configurations diff --git a/docs/docs/usage-guide/enabling_a_wiki.md b/docs/docs/usage-guide/enabling_a_wiki.md index 68782716..ff82327f 100644 --- a/docs/docs/usage-guide/enabling_a_wiki.md +++ b/docs/docs/usage-guide/enabling_a_wiki.md @@ -3,12 +3,12 @@ For optimal functionality of Qodo Merge, we recommend enabling a wiki for each repository where Qodo Merge is installed. The wiki serves several important purposes: -**Key Wiki Features:** +**Key Wiki Features: 💎** - Storing a [configuration file](https://qodo-merge-docs.qodo.ai/usage-guide/configuration_options/#wiki-configuration-file) - Defining a [`best_practices.md`](https://qodo-merge-docs.qodo.ai/tools/improve/#best-practices) file - Track [accepted suggestions](https://qodo-merge-docs.qodo.ai/tools/improve/#suggestion-tracking) -- Facilitates learning over time by creating an [auto_best_practices.md]() file +- Facilitates learning over time by creating an [auto_best_practices.md](https://qodo-merge-docs.qodo.ai/core-abilities/auto_best_practices) file **Setup Instructions (GitHub):** @@ -21,4 +21,13 @@ To enable a wiki for your repository: 4. Enable the "Wikis" option by checking the corresponding box 5. Return to your repository's main page 6. Look for the newly added "Wiki" tab in the top navigation -7. Initialize your wiki by clicking "Create the first page" (this step is important - without creating an initial page, the wiki will not be fully functional) +7. Initialize your wiki by clicking "Create the first page" and saving (this step is important - without creating an initial page, the wiki will not be fully functional) + +### Why Wiki? + +- Your code (and its derivatives, including accepted code suggestions) is yours. Qodo Merge will never store it on external servers. +- Repository changes typically require pull requests, which create overhead and are time-consuming. This process is too cumbersome for auto data aggregation, and is not very convenient even for managing frequently updated content like configuration files and best practices. +- A repository wiki page provides an ideal balance: + - It lives within your repository, making it suitable for code-related documentation + - It enables quick updates without the overhead of pull requests + - It maintains full Git version control, allowing you to track changes over time.