Issue templates #4278

jgonggrijp · 2023-07-27T15:20:59Z

I decided to try my hand at GitHub's issue template functionality. The changes can be previewed at my fork, where I temporarily enabled issues. This is probably a better way to review this PR than by reading the YAML files. The top three categories have forms that you can view by clicking "get started".

I had two main goals:

Steer people away from reporting security vulnerabilities through public issue tickets. Those should be communicated privately to me and Jeremy instead.
Guide inexperienced users to document their issues as clearly as possible.

For expert users, there is still the option to skip the forms and create a blank issue.

I may have gone a bit overboard with the forms. I'm open to all suggestions.

jgonggrijp · 2023-08-08T23:32:49Z

Bump: I would prefer to see opinions from at least two different people (excluding myself), before taking a decision. To anyone considering to do a review: you can skip the code, the preview link in the opening post will show you what it will actually look like in the GitHub web interface.

CC @paulfalgout @Rayraz @GammaGames

GammaGames · 2023-08-09T02:16:10Z

I figured out how to preview them, they look good! The bug one might be a little long though, entering all that information would take a while. I left a few comments where I thought they could be combined without missing anything

paulfalgout

Fancy

Rayraz · 2023-08-09T17:54:47Z

The bug form is quite long. I suppose things like logs, research, prior discussions, related tickets, etc. could all be wrapped into simply a remarks field?

Steps to reproduce and example code could possibly be merged into one field as well.

jgonggrijp · 2023-08-09T21:42:05Z

I figured out how to preview them, they look good! The bug one might be a little long though, entering all that information would take a while. I left a few comments where I thought they could be combined without missing anything

@GammaGames where can I see your comments?

GammaGames · 2023-08-10T15:23:40Z

The comments should be in a review, I think? I see it in the feed:

jgonggrijp · 2023-08-10T18:05:11Z

@GammaGames Ah, it says "pending" in that screenshot, which means they are probably only visible to you. GitHub queues your comments and then publishes them all at once when you submit your "overall" review (i.e., the "verdict"). You can make that final step by going to the "Files changed" tab and pressing the green button in the top right.

GammaGames · 2023-08-09T00:14:21Z

.github/ISSUE_TEMPLATE/Bugs.yml

+    attributes:
+      label: Affected engine(s)
+      description: >
+        In which browser(s) or other JavaScript environment(s) did you encounter


Do we have a Backbone.getDebugInfo() function? Would make this step way easier (for both client and server)

I don't think we do, but that is an excellent idea. I'll see whether it is easy to add, and otherwise create a ticket for it.

@GammaGames please have a look at 8fe1bbb while I continue to work on the other review comments. Maybe it is a bit bulky for what it is; I put it all in one commit so it will be easy to revert.

I think putting it all in one commit makes sense and at a glance it looked good! I'll try to take a closer look and respond to the rest of your comments sometime this weekend

.github/ISSUE_TEMPLATE/Bugs.yml

GammaGames · 2023-08-09T00:22:20Z

.github/ISSUE_TEMPLATE/Bugs.yml

+    attributes:
+      label: Code permalinks
+      description: >
+        If possible, provide permalinks to the JavaScript code, configuration,


I think this is useful, but if we have to cut something this is where we should do it. 99% of users aren't going to do this (especially if they've already got a line and version, that's enough to find the location)

Just to make sure we are talking about the same thing: did you interpret this question as asking for a permalink to Backbone code, or for a permalink to someone's project code in which the bug manifested?

I interpreted it as a link to the documentation, I may have misread it. Most repos have a jsfiddle template set up and just ask for a reproducable example

.github/ISSUE_TEMPLATE/Bugs.yml

GammaGames · 2023-08-09T00:35:41Z

.github/ISSUE_TEMPLATE/Documentation.yml

+    id: problem
+    attributes:
+      label: Problem statement
+      description: >-


I know this is technically something to collect, but it's really just the cause of the problem. They're both asking similar questions.

I somewhat disagree here, it's asking for the effects rather than the cause. I know people generally find it more intuitive to discuss the cause before the effect, but it is the effect that actually motivates changes to the documentation. I find it important to start with the "why".

That said, your comment made me realize the naming of the field was a bit vague, so I renamed it to "effect".

I agree with the name change

.github/ISSUE_TEMPLATE/Features.yml

.github/ISSUE_TEMPLATE/Bugs.yml

GammaGames · 2023-08-10T19:30:17Z

@jgonggrijp Thank you, posted! Guess I've accidentally done it correctly the few times I've posted a review

jgonggrijp · 2023-08-11T16:18:30Z

@GammaGames and @Rayraz, I think I followed up on your review comments (maybe not to the letter but hopefully still in spirit). I merged a bunch of questions, especially in the bug template. Please have another look at the live preview.

The new debugInfo method is up for debate; I kept all changes related to it on separate commits, so they can be easily reverted.

GammaGames · 2023-08-17T18:16:19Z

I think the shortened bug report mostly looks good! Is there any way to make the behavior question inputs larger? One of them has their placeholder text truncated:

jgonggrijp · 2023-08-18T01:37:39Z

I can only choose between single-line <input> and multi-line <textarea>. In the latter case, it is the same size as all other "large" boxes. Which of these options would you prefer?

Shorten the placeholder so it fits.
Turn the behavior fields into <textarea>s.

By they way, do you think that the code size of the debugInfo function is proportional to its usefulness?

paulfalgout · 2023-08-18T06:55:31Z

@jgonggrijp honestly I'd move that debugInfo into a separate directory/module such that people can

import Backbone from 'backbone';
import { debugInfo } from 'backbone/debug-info';

GammaGames · 2023-08-18T14:42:24Z

I like that they're <input>s, I think a shorter example would fit the space and help guide the user. And yes, the added code for debugInfo has a lot of value! Gathering all the versions as well as environment would be tedous without it

jgonggrijp · 2023-09-19T14:40:16Z

Alright, I shortened the placeholder for that <input>, moved debugInfo to a separate module and added documentation for it.

The updated bug report template can be previewed here and the documentation for debugInfo can be previewed here. I would appreciate a final thumbs-up before merging this!

(The linter currently chokes on the ESM syntax in modules/debug-info.js, I'll adress that before merging.)

GammaGames · 2023-09-19T14:48:32Z

👍️

I mean, not exactly to the letter of the comments, but hopefully to the spirit.

Old trick learned from Underscore: within this directory, Node.js and other tools that follow its awkward convention will be willing to interpret .js files with ES module syntax.

jgonggrijp added enhancement documentation labels Jul 27, 2023

paulfalgout approved these changes Aug 9, 2023

View reviewed changes

GammaGames reviewed Aug 10, 2023

View reviewed changes

jgonggrijp added 11 commits January 23, 2024 19:48

Add config for issue templates

9cc8553

Add a bug issue template

b176a06

Add a feature request template

ed13c52

Add a documentation issue template

0b86204

Add debugInfo method

a2bcf19

Merge bug issue template fields per review comments

01a027c

I mean, not exactly to the letter of the comments, but hopefully to the spirit.

Mention Backbone.debugInfo in bug issue template stack field

6e9d79e

Rename doc issue template "problem" field to "effect"

25d34a4

Rewrap doc issue template to 80 columns

f342b6c

Rewrap feature issue template to 80 columns

16e16c1

Merge limitation and options in feature issue template per review

32ba686

jgonggrijp added 5 commits January 23, 2024 19:48

Shorten actual behavior placeholder text in bug issue template

d47dc71

Add a modules directory with its own package.json

eb29ed8

Old trick learned from Underscore: within this directory, Node.js and other tools that follow its awkward convention will be willing to interpret .js files with ES module syntax.

Move debugInfo to a separate module

5ae5639

Document debugInfo

07cc274

Get new debugInfo module to pass linting

be26215

jgonggrijp force-pushed the issue-templates branch from 556d29b to be26215 Compare January 23, 2024 18:50

jgonggrijp merged commit 801db14 into jashkenas:master Jan 23, 2024
1 check passed

jgonggrijp deleted the issue-templates branch January 23, 2024 21:36

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Issue templates #4278

Issue templates #4278

jgonggrijp commented Jul 27, 2023

jgonggrijp commented Aug 8, 2023

GammaGames commented Aug 9, 2023

paulfalgout left a comment

Rayraz commented Aug 9, 2023

jgonggrijp commented Aug 9, 2023

GammaGames commented Aug 10, 2023

jgonggrijp commented Aug 10, 2023

GammaGames Aug 9, 2023

jgonggrijp Aug 10, 2023

jgonggrijp Aug 11, 2023

GammaGames Aug 11, 2023

GammaGames Aug 9, 2023

jgonggrijp Aug 10, 2023

GammaGames Aug 17, 2023

GammaGames Aug 9, 2023

jgonggrijp Aug 11, 2023

GammaGames Aug 17, 2023

GammaGames commented Aug 10, 2023

jgonggrijp commented Aug 11, 2023

GammaGames commented Aug 17, 2023

jgonggrijp commented Aug 18, 2023 •

edited

Loading

paulfalgout commented Aug 18, 2023

GammaGames commented Aug 18, 2023

jgonggrijp commented Sep 19, 2023

GammaGames commented Sep 19, 2023

Issue templates #4278

Issue templates #4278

Conversation

jgonggrijp commented Jul 27, 2023

jgonggrijp commented Aug 8, 2023

GammaGames commented Aug 9, 2023

paulfalgout left a comment

Choose a reason for hiding this comment

Rayraz commented Aug 9, 2023

jgonggrijp commented Aug 9, 2023

GammaGames commented Aug 10, 2023

jgonggrijp commented Aug 10, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

GammaGames commented Aug 10, 2023

jgonggrijp commented Aug 11, 2023

GammaGames commented Aug 17, 2023

jgonggrijp commented Aug 18, 2023 • edited Loading

paulfalgout commented Aug 18, 2023

GammaGames commented Aug 18, 2023

jgonggrijp commented Sep 19, 2023

GammaGames commented Sep 19, 2023

jgonggrijp commented Aug 18, 2023 •

edited

Loading