gitea/docs/content/doc/usage/issue-pull-request-templates.en-us.md
Jason Song 84447df4d3
Support Issue forms and PR forms (#20987)
* feat: extend issue template for yaml

* feat: support yaml template

* feat: render form to markdown

* feat: support yaml template for pr

* chore: rename to Fields

* feat: template unmarshal

* feat: split template

* feat: render to markdown

* feat: use full name as template file name

* chore: remove useless file

* feat: use dropdown of fomantic ui

* feat: update input style

* docs: more comments

* fix: render text without render

* chore: fix lint error

* fix: support use description as about in markdown

* fix: add field class in form

* chore: generate swagger

* feat: validate template

* feat: support is_nummber and regex

* test: fix broken unit tests

* fix: ignore empty body of md template

* fix: make multiple easymde editors work in one page

* feat: better UI

* fix: js error in pr form

* chore: generate swagger

* feat: support regex validation

* chore: generate swagger

* fix: refresh each markdown editor

* chore: give up required validation

* fix: correct issue template candidates

* fix: correct checkboxes style

* chore: ignore .hugo_build.lock in docs

* docs: separate out a new doc for merge templates

* docs: introduce syntax of yaml template

* feat: show a alert for invalid templates

* test: add case for a valid template

* fix: correct attributes of required checkbox

* fix: add class not-under-easymde for dropzone

* fix: use more back-quotes

* chore: remove translation in zh-CN

* fix EasyMDE statusbar margin

* fix: remove repeated blocks

* fix: reuse regex for quotes

Co-authored-by: wxiaoguang <wxiaoguang@gmail.com>
2022-09-02 15:58:49 +08:00

13 KiB

date title slug weight toc draft menu
2018-05-10T16:00:00+02:00 Usage: Issue and Pull Request templates issue-pull-request-templates 15 false false
sidebar
parent name weight identifier
usage Issue and Pull Request templates 15 issue-pull-request-templates

Issue and Pull Request Templates

Table of Contents

{{< toc >}}

Some projects have a standard list of questions that users need to answer when creating an issue or pull request. Gitea supports adding templates to the main 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.

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.

File names

Possible file names for issue templates:

  • ISSUE_TEMPLATE.md
  • ISSUE_TEMPLATE.yaml
  • ISSUE_TEMPLATE.yml
  • issue_template.md
  • issue_template.yaml
  • issue_template.yml
  • .gitea/ISSUE_TEMPLATE.md
  • .gitea/ISSUE_TEMPLATE.yaml
  • .gitea/ISSUE_TEMPLATE.yml
  • .gitea/issue_template.md
  • .gitea/issue_template.yaml
  • .gitea/issue_template.md
  • .github/ISSUE_TEMPLATE.md
  • .github/ISSUE_TEMPLATE.yaml
  • .github/ISSUE_TEMPLATE.yml
  • .github/issue_template.md
  • .github/issue_template.yaml
  • .github/issue_template.yml

Possible file names 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
  • .gitea/PULL_REQUEST_TEMPLATE.md
  • .gitea/PULL_REQUEST_TEMPLATE.yaml
  • .gitea/PULL_REQUEST_TEMPLATE.yml
  • .gitea/pull_request_template.md
  • .gitea/pull_request_template.yaml
  • .gitea/pull_request_template.yml
  • .github/PULL_REQUEST_TEMPLATE.md
  • .github/PULL_REQUEST_TEMPLATE.yaml
  • .github/PULL_REQUEST_TEMPLATE.yml
  • .github/pull_request_template.md
  • .github/pull_request_template.yaml
  • .github/pull_request_template.yml

Directory names

Alternatively, users can create multiple issue templates inside a special directory and allow users to choose one that more specifically addresses their problem.

Possible directory names for issue templates:

  • ISSUE_TEMPLATE
  • issue_template
  • .gitea/ISSUE_TEMPLATE
  • .gitea/issue_template
  • .github/ISSUE_TEMPLATE
  • .github/issue_template
  • .gitlab/ISSUE_TEMPLATE
  • .gitlab/issue_template

Inside the directory can be multiple markdown (.md) or yaml (.yaml/.yml) issue templates of the form.

Syntax for markdown template

---

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.

name: Bug Report
about: File a bug report
title: "[Bug]: "
body:
  - type: markdown
    attributes:
      value: |
        Thanks for taking the time to fill out this bug report!        
  - 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

Markdown

You can use a markdown element to display Markdown in your form that provides extra context to the user, but is not submitted.

Attributes:

Key Description Required Type Default Valid values
value The text that is rendered. Markdown formatting is supported. Required String - -

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 Gitea.

Validations:

Key Description Required Type Default Valid values
required Prevents form submission until element is completed. Optional Boolean false -

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

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 -

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 -