diff --git a/docs/DESCRIBE.md b/docs/DESCRIBE.md index b08f563c..da33c344 100644 --- a/docs/DESCRIBE.md +++ b/docs/DESCRIBE.md @@ -1,6 +1,15 @@ # Describe Tool +## Table of Contents +- [Overview](#overview) + - [Handle custom labels from the Repo's labels page :gem:](#handle-custom-labels-from-the-repos-labels-page-gem) + - [Configuration options](#configuration-options) + - [Markers template](#markers-template) +- [Usage Tips](#usage-tips) + - [Automation](#automation) + - [Custom labels](#custom-labels) -The `describe` tool scans the PR code changes, and can automatically generate PR description - title, type, summary, walkthrough and labels. +## Overview +The `describe` tool scans the PR code changes, and generates a description for the PR - title, type, summary, walkthrough and labels. 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: ``` @@ -81,22 +90,25 @@ The marker `pr_agent:type` will be replaced with the PR type, `pr_agent:summary` -##### Configuration params: +**Configuration params:** - `use_description_markers`: if set to true, the tool will use markers template. It replaces every marker of the form `pr_agent:marker_name` with the relevant content. Default is false. - `include_generated_by_header`: if set to true, the tool will add a dedicated header: 'Generated by PR Agent at ...' to any automatic content. Default is true. ## Usage Tips +### 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: 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: @@ -110,3 +122,17 @@ the tool will replace every marker of the form `pr_agent:marker_name` in the PR Note that when markers are enabled, if the original PR description does not contain any markers, the tool will not alter the description at all. +### Custom labels +The default labels of the describe tool are quite generic, since they are meant to be used in any repo. The default labels are: [`Bug fix`, `Tests`, `Enhancement`, `Documentation`, `Other`]. + +If you specify custom labels in the repo's labels page, you can get tailored labels for your repo and use cases. +Examples for custom labels: +- `Main topic:performence` - pr_agent:The main topic of this PR is performance +- `New endpoint` - pr_agent:A new endpoint was added in this PR +- `SQL query` - pr_agent:A new SQL query was added in this PR +- `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. +Note that Labels are not mutually exclusive, so you can add multiple label categories. +Make sure to provide detailed well-phrased description for each label, so the tool will know when to suggest it. \ No newline at end of file