Github issue forms

[reinerh]

I just noticed on a different project that Github now has support for custom issue forms.
An example can be seen here: https://github.com/CleverRaven/Cataclysm-DDA/issues/new?assignees=&labels=&template=bug_report.yaml

Documentation for that feature is here: https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms

I think we could make our "new issue" page also more beautiful with these forms.

[rusty-snake]

As related note: I am in the process of revising our issue template and adding more templates. But the process has become somewhat stale so if anyone want to pick this up, here's my current state.

bug_report.md

--- a/.github/ISSUE_TEMPLATE/bug_report.md
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -12,9 +12,8 @@ Write clear, concise and in textual form.
 - Describe the bug.
 - What did you expect to happen?
 
-**No profile and disabling firejail**
-- What changed calling `firejail --noprofile /path/to/program` in a terminal?
-- What changed calling the program by path (e.g. `/usr/bin/vlc`)?
+**No profile**
+- What changes calling `firejail --noprofile /path/to/program` in a terminal?
 
 **Reproduce**
 Steps to reproduce the behavior:
@@ -31,13 +30,14 @@ Steps to reproduce the behavior:
 Other context about the problem like related errors to understand the problem.
 
 **Checklist**
+ - [ ] The issues is caused by firejail (i.e running the program by path (e.g. `/usr/bin/vlc`) "fixes" it).
  - [ ] The profile (and redirect profile if exists) hasn't already been fixed [upstream](https://github.com/netblue30/firejail/tree/master/etc).
  - [ ] The program has a profile. (If not, request one in `https://github.com/netblue30/firejail/issues/1139`)
  - [ ] I have performed a short search for similar issues (to avoid opening a duplicate).
  - [ ] If it is a AppImage, `--profile=PROFILENAME` is used to set the right profile.
  - [ ] Used `LC_ALL=en_US.UTF-8 LANG=en_US.UTF-8 PROGRAM` to get english error-messages.
  - [ ] I'm aware of `browser-allow-drm yes`/`browser-disable-u2f no` in `firejail.config` to allow DRM/U2F in browsers.
- - [ ] This is not a question. Questions should be asked in https://github.com/netblue30/firejail/discussions.
+ - [ ] I can reproduce the issue without custom modifications (e.g. globals.local)
 
 
 <details><summary> debug output </summary>

feature_request.md

---
name: Feature request
about: Suggest an idea for this project
title: ''
labels: ''
assignees: ''
---

**Is your feature request related to a problem? Please describe.**
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]

**Describe the solution you'd like**
A clear and concise description of what you want to happen.

**Describe alternatives you've considered**
A clear and concise description of any alternative solutions or features you've considered.

**Additional context**
Add any other context or screenshots about the feature request here.

config.yml

blank_issues_enabled: true
contact_links:
  - name: Question
    url: https://github.com/netblue30/firejail/discussions
    about: FIXME


https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository

https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms

[kmk3]

@reinerh 4 hours ago:

I just noticed on a different project that Github now has support for custom
issue forms. An example can be seen here:
https://github.com/CleverRaven/Cataclysm-DDA/issues/new?assignees=&labels=&template=bug_report.yaml

Documentation for that feature is here:
https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms

I think we could make our "new issue" page also more beautiful with these
forms.

Please don't. I find web browsers to be terrible at editing text compared to
proper text editors, especially when being used to (neo)vim's keybindings and
functionality.

I usually just copy the markdown template (if any) into a proper text editor
and edit it in there, just like any other text. This is especially helpful for
longer writings and it also allows having an offline markdown copy of every
comment made on GitHub.

https://github.com/CleverRaven/Cataclysm-DDA/issues/new?assignees=&labels=&template=bug_report.yaml

In your example, there are 6 different text fields. For equivalent
functionality, I would have to copy each pair of field description and
placeholder text into a text editor before being able to see all the relevant
information directly on the same buffer and to then start writing the report.
Other adjacent issues:

• Some of the form examples/hints are inside HTML placeholders, so they can't
  even be copied directly like the other elements
• There is no way to see the markdown source of the field descriptions, so they
  would be copied as plain text instead
• Each field would have to be manually copied back field by field, taking care
  not to copy the field description

Additionally, whenever you click in and out of the text fields, they magically
toggle between normal-looking HTML <textarea> elements and the GitHub custom
text fields, which have different dimensions. Not only that, but depending on
the scroll position, clicking on a text field also triggers an event that
causes the view to jump up or down. This makes for a rather clunky and jarring
experience.

And lastly, it requires writing the template in a completely different markup
language. Besides the additional complexity and reduced readability of YAML,
this also makes the process more dependent on GitHub itself and its web UI.
That is, currently I can simply copy e.g.: bug_report.md from a local repo
into a new file and start editing. This is not possible to do in the YAML
workflow (unless you write and use a GitHub YAML form to markdown converter).

Rant: It goes from being almost as simple as possible (i.e.: markdown on a
single text field) to something much more opaque (both in the source and on the
report page), involving two markup format conversions, multiple fields, fields
of different kinds and HTML validation. It's like jumping from Bugzilla to
JIRA, except that not even in JIRA I've seen multiple textarea fields being
used at once. Also, I think at least YAML could have been avoided by simply
adding a few custom markdown preprocessing commands instead, but I digress.

[reinerh]

On Mon, Aug 16, 2021 at 05:25:23PM -0700, Kelvin M. Klann wrote: @reinerh [4 hours ago](#4468 (comment)): > I think we could make our "new issue" page also more beautiful with these > forms. Please don't. I find web browsers to be terrible at editing text compared to proper text editors, especially when being used to (neo)vim's keybindings and functionality. I usually just copy the markdown template (if any) into a proper text editor and edit it in there, just like any other text. This is especially helpful for longer writings and it also allows having an offline markdown copy of every comment made on GitHub.

I also prefer vim for editing texts, but I'm too lazy to copy texts from/to the browser. As I think most people are editing texts inside browsers, the forms would be an improvement. What about a compromise, where we keep the old way of reporting bugs with the plaintext markdown template, and add a new one for more "casual" reporters? I think the issue form could lead to less confusing bug reports, because people often keep parts of the template in their report without filling it out completely. Even I found it more "comfortable" to submit a new bug via a custom form. Maybe because the topics and descriptions/comments were not part of the text I had to fill out.

And lastly, it requires writing the template in a completely different markup language. Besides the additional complexity and reduced readability of YAML, this also makes the process more dependent on GitHub itself and its web UI. That is, currently I can simply copy e.g.: `bug_report.md` from a local repo into a new file and start editing. This is not possible to do in the YAML workflow (unless you write and use a GitHub YAML form to markdown converter).

Getting more dependent on GitHub is a concern that I share, but I don't see us switching to anywhere else in the (near) future. Adding this form (in addition to the old report method) would probably be a one-time setup (and maybe some fine-tunings at a later point).

Rant: It goes from being almost as simple as possible (i.e.: markdown on a single text field) to something much more opaque (both in the source and on the report page), involving two markup format conversions, multiple fields, fields of different kinds and HTML validation. It's like jumping from Bugzilla to JIRA, except that not even in JIRA I've seen multiple textarea fields being used at once. Also, I think at least YAML could have been avoided by simply adding a few custom markdown preprocessing commands instead, but I digress.

They probably chose YAML as they use it in other places as well (e.g. Actions) and it gives greater flexibility. For browser-only editing I actually think the forms are simpler, as you are only adding your own content, and don't have this mix of provided template content with your own content.

[reinerh]

(the above post should have been a reply to @kmk3 's post (#4468 (comment), but Github decided to make it a new post when the reply is submitted by mail)

[rusty-snake]

My two (or more) cents on this.
We do not enforce using of templates and never should because 1. if a report is good without template, nothing is wrong and 2. we will never a templates for everything. Just look at but reporting there are bugs in firejail itself, with profile, with compiling, ... they all should have a own template as you need to ask different things. Having a form to report problems with profiles (the most common bug issues) is good IMHO to make it simpler for users who may even can not handle markdown (multiline codeblocks, ...).

[kmk3]

Sorry for the late reply; IRL things got in the way.

@reinerh on Aug 17:

On Mon, Aug 16, 2021 at 05:25:23PM -0700, Kelvin M. Klann wrote:

@reinerh [4 hours ago](#4468 (comment)):

I think we could make our "new issue" page also more beautiful with these
forms.

Please don't. I find web browsers to be terrible at editing text compared to
proper text editors, especially when being used to (neo)vim's keybindings and
functionality. I usually just copy the markdown template (if any) into a
proper text editor and edit it in there, just like any other text. This is
especially helpful for longer writings and it also allows having an offline
markdown copy of every comment made on GitHub.

I also prefer vim for editing texts, but I'm too lazy to copy texts from/to
the browser. As I think most people are editing texts inside browsers, the
forms would be an improvement.

What about a compromise, where we keep the old way of reporting bugs with the
plaintext markdown template, and add a new one for more "casual" reporters?

Sure, that seems workable. It would require a bit more maintenance to keep
both in sync, but at least the templates don't change too often.

Even I found it more "comfortable" to submit a new bug via a custom form.

By itself it does look a bit "neater", but personally I just find the
navigation too limiting when trying to use it, especially compared to being
able to easily move anywhere in a single buffer. Maybe the HTML inputs
wouldn't make too much of a difference if this was mostly about clicking
checkboxes and radio buttons, but the majority of it is writing (potentially
long texts).

Maybe because the topics and descriptions/comments were not part of the text
I had to fill out.

I also dislike having the description/"non-editable" part very close to the
"editable" part. I'll open a PR later to at least add a blank line between
each pair, which should help a bit with this and also make the markdown more
conformant.

They probably chose YAML as they use it in other places as well (e.g.
Actions) and it gives greater flexibility.

I also assume that this is likely the "path of least resistance" for whoever
decided to use YAML.

Here I originally had written a long (and unfinished) rant about the choice of
YAML. As we seem to be mostly in agreement about the actionable parts and
since the text probably wouldn't be very productive anyway, I'll just leave my
conclusion instead:

I think that instead of YAML, either extending markdown with custom markup or
using a subset of HTML directly would have made the usability much better for
whoever has to read/write/maintain the forms.

@rusty-snake on Aug 17:

My two (or more) cents on this.

We do not enforce using of templates and never should because 1. if a report
is good without template, nothing is wrong and 2. we will never a templates
for everything. Just look at but reporting there are bugs in firejail itself,
with profile, with compiling, ... they all should have a own template as you
need to ask different things. Having a form to report problems with profiles
(the most common bug issues) is good IMHO to make it simpler for users who
may even can not handle markdown (multiline codeblocks, ...).

That makes sense, thanks for replying.

[kmk3]

I'll open a PR later to at least add a blank line between each pair, which
should help a bit with this and also make the markdown more conformant.

Done: #4479.

[rusty-snake]

Hey guess what happens if you mess up one textarea filed of a form.

Answer

I inserted ``` in the actual behaviour field.

EDIT: An if you insert ``` into a input field, the same thing happens. 🤣