# Issue and Pull Request Templates Some projects have a standard list of questions that users need to answer when creating an issue or pull request. Forgejo supports adding templates to the **default branch of the repository** so that they can autopopulate the form when users are creating issues and pull requests. This will cut down on the initial back-and-forth of getting some clarifying details. It is currently not possible to provide generic issue/pull-request templates globally. In general, there is the choice of using either multiple or a single issue template file(s), a single pull-request template file and additionally the possibility of adding an issue config. Additionally, the New Issue page URL can be suffixed with `?title=Issue+Title&body=Issue+Text` and the form will be populated with those strings. Those strings will be used instead of the template if there is one. ## Directory names Users can create multiple template files inside a special directory and this allows different use cases: users can choose to use the template that is suited to address their specific problem. Please note that there can be multiple issue templates. However, there may only be a single pull request template in one repository. Forgejo will check for template files in the following directories, since Forgejo checks these services to make migration from them easier: - `.forgejo` - `.gitea` - `.github` - `docs` Inside the directory can be multiple markdown (`.md`) or yaml (`.yaml`/`.yml`) files for templates of the form - these are the three allowed file extensions. ## File names For the three file types - issue templates, pull request templates, and issue configs, there are various possible file names that may be used in the directories listed above. **Issue templates** are arbitrarily named files with any of the three file extensions mentioned above, and there may be any number of them, so they each get their dedicated subdirectory: `issue_template` and `ISSUE_TEMPLATE` are the possible names for the subdirectory that the issue templates go into. In contrast, there may only be a single pull request template per repository, so there is no extra subdirectory for it. It can reside in any of the `.` directories (with the exception of the `.gitlab` directory, this is not supported!) listed in the previous section. A pull request template has a fixed name (see options below) and can end with any of the three file extensions mentioned above. Possible file names and file extensions for **PR templates**: - `PULL_REQUEST_TEMPLATE.md` - `PULL_REQUEST_TEMPLATE.yaml` - `PULL_REQUEST_TEMPLATE.yml` - `pull_request_template.md` - `pull_request_template.yaml` - `pull_request_template.yml` Issue config template files need to go into the same subdirectory as issue template files (see above section). Possible file names and file extensions for **issue config**: - `config.yaml` - `config.yml` An example setup for a single issue template file together with a single pull request template file could look like this: ``` .forgejo/ ISSUE_TEMPLATE/ issue_template.yaml pull_request_template.yml ``` Another example setup but with multiple issue template files instead could look like this: ``` .forgejo/ issue_template/ bug.yaml config.yml feature.yaml pull_request_template.md ``` ## Syntax for markdown template ```md --- name: 'Template Name' about: 'This template is for testing!' title: '[TEST] ' ref: 'main' labels: - bug - 'help needed' --- This is the template! ``` In the above example, when a user is presented with the list of issues they can submit, this would show as `Template Name` with the description `This template is for testing!`. When submitting an issue with the above example, the issue title would be pre-populated with `[TEST] ` while the issue body would be pre-populated with `This is the template!`. The issue would also be assigned two labels, `bug` and `help needed`, and the issue will have a reference to `main`. ## Syntax for yaml template This example YAML configuration file defines an issue form using several inputs to report a bug. ```yaml name: Bug Report about: File a bug report title: '[Bug]: ' ref: 'main' labels: - bug - 'help needed' body: - type: markdown attributes: value: | Thanks for taking the time to fill out this bug report! # some markdown that will only be visible once the issue has been created - type: markdown attributes: value: | This issue was created by an issue **template** :) visible: [content] - type: input id: contact attributes: label: Contact Details description: How can we get in touch with you if we need more info? placeholder: ex. email@example.com validations: required: false - type: textarea id: what-happened attributes: label: What happened? description: Also tell us, what did you expect to happen? placeholder: Tell us what you see! value: 'A bug happened!' validations: required: true - type: dropdown id: version attributes: label: Version description: What version of our software are you running? options: - 1.0.2 (Default) - 1.0.3 (Edge) validations: required: true - type: dropdown id: browsers attributes: label: What browsers are you seeing the problem on? multiple: true options: - Firefox - Chrome - Safari - Microsoft Edge - type: textarea id: logs attributes: label: Relevant log output description: Please copy and paste any relevant log output. This will be automatically formatted into code, so no need for backticks. render: shell - type: checkboxes id: terms attributes: label: Code of Conduct description: By submitting this issue, you agree to follow our [Code of Conduct](https://example.com) options: - label: I agree to follow this project's Code of Conduct required: true - label: I have also read the CONTRIBUTION.MD required: true visible: [form] - label: This is a TODO only visible after issue creation visible: [content] ``` ### Markdown You can use a `markdown` element to display Markdown in your form that provides extra context to the user, but is not submitted by default. Attributes: | Key | Description | Required | Type | Default | Valid values | | ----- | ------------------------------------------------------------ | -------- | ------ | ------- | ------------ | | value | The text that is rendered. Markdown formatting is supported. | Required | String | - | - | visible: Default is **[form]** ### Textarea You can use a `textarea` element to add a multi-line text field to your form. Contributors can also attach files in `textarea` fields. Attributes: | Key | Description | Required | Type | Default | Valid values | | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------ | ------------ | --------------------------- | | label | A brief description of the expected user input, which is also displayed in the form. | Required | String | - | - | | description | A description of the text area to provide context or guidance, which is displayed in the form. | Optional | String | Empty String | - | | placeholder | A semi-opaque placeholder that renders in the text area when empty. | Optional | String | Empty String | - | | value | Text that is pre-filled in the text area. | Optional | String | - | - | | render | If a value is provided, submitted text will be formatted into a codeblock. When this key is provided, the text area will not expand for file attachments or Markdown editing. | Optional | String | - | Languages known to Forgejo. | Validations: | Key | Description | Required | Type | Default | Valid values | | -------- | ---------------------------------------------------- | -------- | ------- | ------- | ------------ | | required | Prevents form submission until element is completed. | Optional | Boolean | false | - | visible: Default is **[form, content]** ### Input You can use an `input` element to add a single-line text field to your form. Attributes: | Key | Description | Required | Type | Default | Valid values | | ----------- | ------------------------------------------------------------------------------------------ | -------- | ------ | ------------ | ------------ | | label | A brief description of the expected user input, which is also displayed in the form. | Required | String | - | - | | description | A description of the field to provide context or guidance, which is displayed in the form. | Optional | String | Empty String | - | | placeholder | A semi-transparent placeholder that renders in the field when empty. | Optional | String | Empty String | - | | value | Text that is pre-filled in the field. | Optional | String | - | - | Validations: | Key | Description | Required | Type | Default | Valid values | | --------- | ------------------------------------------------------------------------------------------------ | -------- | ------- | ------- | ------------------------------------------------------------------------ | | required | Prevents form submission until element is completed. | Optional | Boolean | false | - | | is_number | Prevents form submission until element is filled with a number. | Optional | Boolean | false | - | | regex | Prevents form submission until element is filled with a value that match the regular expression. | Optional | String | - | a [regular expression](https://en.wikipedia.org/wiki/Regular_expression) | visible: Default is **[form, content]** ### Dropdown You can use a `dropdown` element to add a dropdown menu in your form. Attributes: | Key | Description | Required | Type | Default | Valid values | | ----------- | --------------------------------------------------------------------------------------------------- | -------- | ------------ | ------------ | ------------ | | label | A brief description of the expected user input, which is displayed in the form. | Required | String | - | - | | description | A description of the dropdown to provide extra context or guidance, which is displayed in the form. | Optional | String | Empty String | - | | multiple | Determines if the user can select more than one option. | Optional | Boolean | false | - | | options | An array of options the user can choose from. Cannot be empty and all choices must be distinct. | Required | String array | - | - | Validations: | Key | Description | Required | Type | Default | Valid values | | -------- | ---------------------------------------------------- | -------- | ------- | ------- | ------------ | | required | Prevents form submission until element is completed. | Optional | Boolean | false | - | visible: Default is **[form, content]** ### Checkboxes You can use the `checkboxes` element to add a set of checkboxes to your form. Attributes: | Key | Description | Required | Type | Default | Valid values | | ----------- | ----------------------------------------------------------------------------------------------------- | -------- | ------ | ------------ | ------------ | | label | A brief description of the expected user input, which is displayed in the form. | Required | String | - | - | | description | A description of the set of checkboxes, which is displayed in the form. Supports Markdown formatting. | Optional | String | Empty String | - | | options | An array of checkboxes that the user can select. For syntax, see below. | Required | Array | - | - | For each value in the options array, you can set the following keys. | Key | Description | Required | Type | Default | Options | | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------ | ------- | ------- | | label | The identifier for the option, which is displayed in the form. Markdown is supported for bold or italic text formatting, and hyperlinks. | Required | String | - | - | | required | Prevents form submission until element is completed. | Optional | Boolean | false | - | | visible | Whether a specific checkbox appears in the form only, in the created issue only, or both. Valid options are "form" and "content". | Optional | String array | false | - | visible: Default is **[form, content]** ## Syntax for issue config This is an example for an issue config file ```yaml blank_issues_enabled: true contact_links: - name: Forgejo url: https://forgejo.org/ about: Visit the Forgejo Website ``` ### Possible Options | Key | Description | Type | Default | | -------------------- | ----------------------------------------------------- | ------------------ | ----------- | | blank_issues_enabled | If set to false, the user is forced to use a template | Boolean | true | | contact_links | Custom links to show in the choose box | Contact Link Array | Empty Array | ### Contact Link | Key | Description | Type | Required | | ----- | -------------------------------- | ------ | -------- | | name | the name of your link | String | true | | url | The URL of your link | String | true | | about | A short description of your link | String | true |