Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Support Issue forms and PR forms #20987

Merged
merged 44 commits into from
Sep 2, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
44 commits
Select commit Hold shift + click to select a range
0ed8a3d
feat: extend issue template for yaml
wolfogre Aug 27, 2022
4efe0b4
feat: support yaml template
wolfogre Aug 27, 2022
1539e79
feat: render form to markdown
wolfogre Aug 27, 2022
bf89e5a
feat: support yaml template for pr
wolfogre Aug 27, 2022
3337a6c
chore: rename to Fields
wolfogre Aug 28, 2022
d25217d
feat: template unmarshal
wolfogre Aug 28, 2022
c0a3727
feat: split template
wolfogre Aug 28, 2022
7de200b
feat: render to markdown
wolfogre Aug 28, 2022
a949489
feat: use full name as template file name
wolfogre Aug 28, 2022
64190cd
chore: remove useless file
wolfogre Aug 28, 2022
ad7e58c
feat: use dropdown of fomantic ui
wolfogre Aug 28, 2022
f2d38f1
feat: update input style
wolfogre Aug 28, 2022
03ab606
docs: more comments
wolfogre Aug 28, 2022
64b44e2
fix: render text without render
wolfogre Aug 29, 2022
b0f5472
chore: fix lint error
wolfogre Aug 29, 2022
5e9e60e
fix: support use description as about in markdown
wolfogre Aug 29, 2022
1d1d7dc
fix: add field class in form
wolfogre Aug 29, 2022
3d65d9a
chore: generate swagger
wolfogre Aug 29, 2022
69df477
feat: validate template
wolfogre Aug 29, 2022
fde937f
feat: support is_nummber and regex
wolfogre Aug 29, 2022
b413dce
test: fix broken unit tests
wolfogre Aug 29, 2022
d764ed8
fix: ignore empty body of md template
wolfogre Aug 30, 2022
793b86a
fix: make multiple easymde editors work in one page
wolfogre Aug 30, 2022
4ffde84
feat: better UI
wolfogre Aug 30, 2022
516ccb4
fix: js error in pr form
wolfogre Aug 30, 2022
de06c52
chore: generate swagger
wolfogre Aug 30, 2022
c698b4e
feat: support regex validation
wolfogre Aug 31, 2022
632b86a
chore: generate swagger
wolfogre Aug 31, 2022
d0d7b0d
fix: refresh each markdown editor
wolfogre Aug 31, 2022
645176f
chore: give up required validation
wolfogre Aug 31, 2022
fdd39f4
fix: correct issue template candidates
wolfogre Aug 31, 2022
a0101e8
fix: correct checkboxes style
wolfogre Aug 31, 2022
23da624
chore: ignore .hugo_build.lock in docs
wolfogre Aug 31, 2022
f0ceaf6
docs: separate out a new doc for merge templates
wolfogre Aug 31, 2022
be266dd
docs: introduce syntax of yaml template
wolfogre Aug 31, 2022
59ce6b9
feat: show a alert for invalid templates
wolfogre Sep 1, 2022
a0f3c8e
test: add case for a valid template
wolfogre Sep 1, 2022
ebfbb85
fix: correct attributes of required checkbox
wolfogre Sep 2, 2022
fd14fbe
fix: add class not-under-easymde for dropzone
wolfogre Sep 2, 2022
e2529ee
fix: use more back-quotes
wolfogre Sep 2, 2022
1f3943c
chore: remove translation in zh-CN
wolfogre Sep 2, 2022
233337d
fix EasyMDE statusbar margin
wxiaoguang Sep 2, 2022
1c3b2e4
fix: remove repeated blocks
wolfogre Sep 2, 2022
7018c82
fix: reuse regex for quotes
wolfogre Sep 2, 2022
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions docs/.gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -2,3 +2,6 @@ public/
templates/swagger/v1_json.tmpl
themes/
resources/

# Temporary lock file while building
/.hugo_build.lock
215 changes: 187 additions & 28 deletions docs/content/doc/usage/issue-pull-request-templates.en-us.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,51 +25,53 @@ main branch of the repository so that they can autopopulate the form when users
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`

Possible file names for PR default merge message templates:

- `.gitea/default_merge_message/MERGE_TEMPLATE.md`
- `.gitea/default_merge_message/REBASE_TEMPLATE.md`
- `.gitea/default_merge_message/REBASE-MERGE_TEMPLATE.md`
- `.gitea/default_merge_message/SQUASH_TEMPLATE.md`
- `.gitea/default_merge_message/MANUALLY-MERGED_TEMPLATE.md`
- `.gitea/default_merge_message/REBASE-UPDATE-ONLY_TEMPLATE.md`

You can use the following variables enclosed in `${}` inside these templates which follow [os.Expand](https://pkg.go.dev/os#Expand) syntax:

- BaseRepoOwnerName: Base repository owner name of this pull request
- BaseRepoName: Base repository name of this pull request
- BaseBranch: Base repository target branch name of this pull request
- HeadRepoOwnerName: Head repository owner name of this pull request
- HeadRepoName: Head repository name of this pull request
- HeadBranch: Head repository branch name of this pull request
- PullRequestTitle: Pull request's title
- PullRequestDescription: Pull request's description
- PullRequestPosterName: Pull request's poster name
- PullRequestIndex: Pull request's index number
- PullRequestReference: Pull request's reference char with index number. i.e. #1, !2
- ClosingIssues: return a string contains all issues which will be closed by this pull request i.e. `close #1, close #2`

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.

## Issue Template Directory
## 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.
Expand All @@ -85,7 +87,9 @@ Possible directory names for issue templates:
- `.gitlab/ISSUE_TEMPLATE`
- `.gitlab/issue_template`

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

## Syntax for markdown template

```md
---
Expand All @@ -108,3 +112,158 @@ In the above example, when a user is presented with the list of issues they can
`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]: "
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](https://en.wikipedia.org/wiki/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 | - |
48 changes: 48 additions & 0 deletions docs/content/doc/usage/merge-message-templates.en-us.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
---
date: "2022-08-31T17:35:40+08:00"
title: "Usage: Merge Message templates"
slug: "merge-message-templates"
weight: 15
toc: false
draft: false
menu:
sidebar:
parent: "usage"
name: "Merge Message templates"
weight: 15
identifier: "merge-message-templates"
---

# Merge Message templates

**Table of Contents**

{{< toc >}}

## File names

Possible file names for PR default merge message templates:

- `.gitea/default_merge_message/MERGE_TEMPLATE.md`
- `.gitea/default_merge_message/REBASE_TEMPLATE.md`
- `.gitea/default_merge_message/REBASE-MERGE_TEMPLATE.md`
- `.gitea/default_merge_message/SQUASH_TEMPLATE.md`
- `.gitea/default_merge_message/MANUALLY-MERGED_TEMPLATE.md`
- `.gitea/default_merge_message/REBASE-UPDATE-ONLY_TEMPLATE.md`

## Variables

You can use the following variables enclosed in `${}` inside these templates which follow [os.Expand](https://pkg.go.dev/os#Expand) syntax:

- BaseRepoOwnerName: Base repository owner name of this pull request
- BaseRepoName: Base repository name of this pull request
- BaseBranch: Base repository target branch name of this pull request
- HeadRepoOwnerName: Head repository owner name of this pull request
- HeadRepoName: Head repository name of this pull request
- HeadBranch: Head repository branch name of this pull request
- PullRequestTitle: Pull request's title
- PullRequestDescription: Pull request's description
- PullRequestPosterName: Pull request's poster name
- PullRequestIndex: Pull request's index number
- PullRequestReference: Pull request's reference char with index number. i.e. #1, !2
- ClosingIssues: return a string contains all issues which will be closed by this pull request i.e. `close #1, close #2`
Loading