Skip to content

Commit

Permalink
Extend issue template yaml engine (go-gitea#29274)
Browse files Browse the repository at this point in the history 
Add new option:

`visible`: witch can hide a specific field of the form or the created
content afterwards

It is a string array witch can contain `form` and `content`. If only
`form` is present, it wont show up in the created issue afterwards and
the other way around. By default it sets both except for markdown

As they are optional and github don't have any similar thing, it is non
breaking and also do not conflict with it.

With this you can:
- define "post issue creation" elements like a TODO list to track an
issue state
- make sure to have a checkbox that reminds the user to check for a
thing but dont have it in the created issue afterwards
- define markdown for the created issue (was the downside of using yaml
instead of md in the past)
 - ...

## Demo

```yaml
name: New Contribution
description: External Contributor creating a pull

body:
- type: checkboxes
  id: extern-todo
  visible: [form]
  attributes:
    label: Contribution Guidelines
    options:
      - label: I checked there exist no similar feature to be extended
        required: true
      - label: I did read the CONTRIBUTION.MD 
        required: true
- type: checkboxes
  id: intern-todo
  visible: [content]
  attributes:
    label: Maintainer Check-List
    options:
      - label: Does this pull follow the KISS principe
      - label: Checked if internal bord was notifyed  
# ....
```
[Demo
Video](https://cloud.obermui.de/s/tm34fSAbJp9qw9z/download/vid-20240220-152751.mkv)


---
*Sponsored by Kithara Software GmbH*

---------

Co-authored-by: John Olheiser <john.olheiser@gmail.com>
Co-authored-by: delvh <dev.lh@web.de>
  • Loading branch information
@6543 @jolheiser @delvh
3 people authored Mar 4, 2024
1 parent 2fb917f commit 77e29e0
Show file tree
Hide file tree
Showing 11 changed files with 247 additions and 50 deletions.
52 changes: 37 additions & 15 deletions docs/content/usage/issue-pull-request-templates.en-us.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -136,6 +136,12 @@ body:
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:
Expand Down Expand Up @@ -187,18 +193,25 @@ body:
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.
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.
Expand All @@ -219,6 +232,8 @@ Validations:
|----------|------------------------------------------------------|----------|---------|---------|--------------|
| 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.
Expand All @@ -240,6 +255,8 @@ Validations:
| 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.
Expand All @@ -259,24 +276,29 @@ Validations:
|----------|------------------------------------------------------|----------|---------|---------|--------------|
| 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 | - |
| 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

Expand All @@ -292,15 +314,15 @@ contact_links:

### 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 |
| 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 |
| 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 |
69 changes: 62 additions & 7 deletions modules/issue/template/template.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -122,7 +122,13 @@ func validateRequired(field *api.IssueFormField, idx int) error {
// The label is not required for a markdown or checkboxes field
return nil
}
return validateBoolItem(newErrorPosition(idx, field.Type), field.Validations, "required")
if err := validateBoolItem(newErrorPosition(idx, field.Type), field.Validations, "required"); err != nil {
return err
}
if required, _ := field.Validations["required"].(bool); required && !field.VisibleOnForm() {
return newErrorPosition(idx, field.Type).Errorf("can not require a hidden field")
}
return nil
}

func validateID(field *api.IssueFormField, idx int, ids container.Set[string]) error {
Expand Down Expand Up @@ -172,10 +178,38 @@ func validateOptions(field *api.IssueFormField, idx int) error {
return position.Errorf("'label' is required and should be a string")
}

if visibility, ok := opt["visible"]; ok {
visibilityList, ok := visibility.([]any)
if !ok {
return position.Errorf("'visible' should be list")
}
for _, visibleType := range visibilityList {
visibleType, ok := visibleType.(string)
if !ok || !(visibleType == "form" || visibleType == "content") {
return position.Errorf("'visible' list can only contain strings of 'form' and 'content'")
}
}
}

if required, ok := opt["required"]; ok {
if _, ok := required.(bool); !ok {
return position.Errorf("'required' should be a bool")
}

// validate if hidden field is required
if visibility, ok := opt["visible"]; ok {
visibilityList, _ := visibility.([]any)
isVisible := false
for _, v := range visibilityList {
if vv, _ := v.(string); vv == "form" {
isVisible = true
break
}
}
if !isVisible {
return position.Errorf("can not require a hidden checkbox")
}
}
}
}
}
Expand Down Expand Up @@ -238,7 +272,7 @@ func RenderToMarkdown(template *api.IssueTemplate, values url.Values) string {
IssueFormField: field,
Values: values,
}
if f.ID == "" {
if f.ID == "" || !f.VisibleInContent() {
continue
}
f.WriteTo(builder)
Expand All @@ -253,11 +287,6 @@ type valuedField struct {
}

func (f *valuedField) WriteTo(builder *strings.Builder) {
if f.Type == api.IssueFormFieldTypeMarkdown {
// markdown blocks do not appear in output
return
}

// write label
if !f.HideLabel() {
_, _ = fmt.Fprintf(builder, "### %s\n\n", f.Label())
Expand All @@ -269,6 +298,9 @@ func (f *valuedField) WriteTo(builder *strings.Builder) {
switch f.Type {
case api.IssueFormFieldTypeCheckboxes:
for _, option := range f.Options() {
if !option.VisibleInContent() {
continue
}
checked := " "
if option.IsChecked() {
checked = "x"
Expand Down Expand Up @@ -302,6 +334,10 @@ func (f *valuedField) WriteTo(builder *strings.Builder) {
} else {
_, _ = fmt.Fprintf(builder, "%s\n", value)
}
case api.IssueFormFieldTypeMarkdown:
if value, ok := f.Attributes["value"].(string); ok {
_, _ = fmt.Fprintf(builder, "%s\n", value)
}
}
_, _ = fmt.Fprintln(builder)
}
Expand All @@ -314,6 +350,9 @@ func (f *valuedField) Label() string {
}

func (f *valuedField) HideLabel() bool {
if f.Type == api.IssueFormFieldTypeMarkdown {
return true
}
if label, ok := f.Attributes["hide_label"].(bool); ok {
return label
}
Expand Down Expand Up @@ -385,6 +424,22 @@ func (o *valuedOption) IsChecked() bool {
return false
}

func (o *valuedOption) VisibleInContent() bool {
if o.field.Type == api.IssueFormFieldTypeCheckboxes {
if vs, ok := o.data.(map[string]any); ok {
if vl, ok := vs["visible"].([]any); ok {
for _, v := range vl {
if vv, _ := v.(string); vv == "content" {
return true
}
}
return false
}
}
}
return true
}

var minQuotesRegex = regexp.MustCompilePOSIX("^`{3,}")

// minQuotes return 3 or more back-quotes.
Expand Down
Loading

0 comments on commit 77e29e0

Please sign in to comment.