From 94172104f0640487895b094616221bc6468ab218 Mon Sep 17 00:00:00 2001 From: mrT23 Date: Sun, 7 Jan 2024 09:56:09 +0200 Subject: [PATCH] docs: Reorganize and enhance documentation for review and describe tools --- docs/DESCRIBE.md | 13 +++++++------ docs/REVIEW.md | 4 ++-- 2 files changed, 9 insertions(+), 8 deletions(-) diff --git a/docs/DESCRIBE.md b/docs/DESCRIBE.md index 0d077ed3..0e3cf4e4 100644 --- a/docs/DESCRIBE.md +++ b/docs/DESCRIBE.md @@ -102,15 +102,16 @@ The marker `pr_agent:type` will be replaced with the PR type, `pr_agent:summary` ### Automation - When you first install the app, the [default mode](https://github.com/Codium-ai/pr-agent/blob/main/Usage.md#github-app-automatic-tools) for the describe tool is: ``` -pr_commands = ["/describe --pr_description.add_original_user_description=true - --pr_description.keep_original_user_title=true", ...] +pr_commands = ["/describe --pr_description.add_original_user_description=true" + "--pr_description.keep_original_user_title=true", ...] ``` -meaning the `describe` tool will run automatically on every PR, will keep the original title, and will add the original user description above the generated description.
This default is quite conservative, and strikes a good balance between automation and control: +meaning the `describe` tool will run automatically on every PR, will keep the original title, and will add the original user description above the generated description. +
This default settings aim to strike a good balance between automation and control: If you want more automation, just give the PR a title, and the tool will auto-write a full description; If you want more control, you can add a detailed description, and the tool will add the complementary description below it. - For maximal automation, you can change the default mode to: ``` -pr_commands = ["/describe --pr_description.add_original_user_description=false - --pr_description.keep_original_user_title=true", ...] +pr_commands = ["/describe --pr_description.add_original_user_description=false" + "--pr_description.keep_original_user_title=true", ...] ``` so the title will be auto-generated as well. - Markers are an alternative way to control the generated description, to give maximal control to the user. If you set: @@ -135,6 +136,6 @@ Examples for custom labels: - `Dockerfile changes` - pr_agent:The PR contains changes in the Dockerfile - ... -The list above is eclectic, and aims to give an idea of different possibilities. Define the custom labels that are relevant for your repo and use cases. +The list above is eclectic, and aims to give an idea of different possibilities. Define custom labels that are relevant for your repo and use cases. Note that Labels are not mutually exclusive, so you can add multiple label categories. Make sure to provide proper title, and detailed and well-phrased description for each label, so the tool will know when to suggest it. \ No newline at end of file diff --git a/docs/REVIEW.md b/docs/REVIEW.md index 965af272..741d4936 100644 --- a/docs/REVIEW.md +++ b/docs/REVIEW.md @@ -14,7 +14,7 @@ ## Overview The `review` tool scans the PR code changes, and automatically generates a PR review. -The tool can be triggered automatically every time a new PR is [opened](https://github.com/Codium-ai/pr-agent/blob/main/Usage.md#github-app-automatic-tools), or it can be invoked manually by commenting on any PR: +The tool can be triggered automatically every time a new PR is [opened](https://github.com/Codium-ai/pr-agent/blob/main/Usage.md#github-app-automatic-tools), or can be invoked manually by commenting on any PR: ``` /review ``` @@ -122,7 +122,7 @@ Edit this field to enable/disable the tool, or to change the used configurations ### Auto-labels The `review` tool can auto-generate two specific types of labels for a PR: -- a `possible security issue` label if it detects a security issue (`enable_review_labels_security` flag) +- a `possible security issue` label if it detects a [security issue](https://github.com/Codium-ai/pr-agent/blob/tr/user_description/pr_agent/settings/pr_reviewer_prompts.toml#L136) (`enable_review_labels_security` flag) - a `Review effort [1-5]: x` label, where x is the estimated effort to review the PR (`enable_review_labels_effort` flag) Both modes are useful, and we recommended to enable them.