-
-
Notifications
You must be signed in to change notification settings - Fork 2.6k
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
First take at creating a GitHub issue template #5652
Conversation
That's really nice, i think there's a way to show this as a message for people sending issues for the first time, i'll take a look when i have a moment |
https://github.com/blog/2111-issue-and-pull-request-templates I think it would be automatically shown in the text box when clicking "new issue", for everyone. You can, as a user, delete the predefined text and type whatever you want. Is that what you meant? Or you mean there's a way to only show it once? |
It's also possible to create a template for pull requests, but I have no experience with what's a good template. Anything you want people to write in a pull request? Some kind of reminder? |
Hey there, I just took a first pass at some edits additions. The main goal of my additions was to differentiate between "questions" (which go to forum) and "issues" which are documented and (hopefully) reproducible. |
Hi @bakercp ! where are your edits visible? |
I just put them in the review comments ... |
I don't know where to click to see the comments. Are they only visible to members of the OF organization? |
.github/ISSUE_TEMPLATE.md
Outdated
@@ -0,0 +1,32 @@ | |||
Nice! You found an issue! :) Get help faster by providing the following details: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
A very quick definition of what an "issue" is vs. what a "how do i .. ?" is would be good here. The goal is to both get better issue reports and also to send people with "how to" questions to the forum for triage before filing official issues. So maybe a checklist for "is this an issue"?
### The issue tracker is for "issues", the openFrameworks forum is for questions.
What is the difference? A obvious question might be "How do I get openFrameworks to compile on Android?" An obvious issue might be "The function `ofRandom()` only returns the number 42 on Linux Ubuntu 16.04".
When you submit an issue, you are certain that the expected result and the actual result _are not the same_ and you must have some code to demonstrate it. If you aren't certain what the "expected" result is (due to poor documentation), then please first ask about it on the forum https://forum.openframeworks.cc. There's a good chance there's a real issue, but please post it on the forum if you are in doubt.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
About "code to demonstrate it", what if it's an improvement or new feature? Isn't it enough to have the block of code at the end to imply this?
.github/ISSUE_TEMPLATE.md
Outdated
void ofApp::draw() { | ||
cout << x << endl; | ||
} | ||
``` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
### Proposed Solution
(describe your proposed solution if you have one)
.github/ISSUE_TEMPLATE.md
Outdated
(explain here) | ||
|
||
### A minimal program showing the issue: | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
_Please make sure each section of your example code is code-fenced like below the example below._
.github/ISSUE_TEMPLATE.md
Outdated
* Graphics card drivers: [Linux: the output of `glxinfo -B`, in Mac ..., Windows: start > run > dxdiag ] | ||
|
||
### Expected result of my program | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
_Why do you expect this result?_
.github/ISSUE_TEMPLATE.md
Outdated
(explain here) | ||
|
||
### Actual result of my program | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
_Please include screen-shots or photos for issues that involve graphics._
Oh. Apparently you have to press "Submit Review" ... can you see it now? |
I see it now, thanks! I'll add my comments soon. |
Hey, what do you think of this check-box approach? Too much? https://github.com/pi-hole/pi-hole/blob/master/.github/ISSUE_TEMPLATE.md |
That one in particular reminds me a bit of government forms, a bit too serious :) But the checkboxes may be useful. I'll first push some changes following your comments, and lets continue from there. |
Another topic: should it be mention that it's not just issues vs questions, but issues in the openFrameworks code (or documentation) vs issues in your own code? |
Some template examples: https://github.com/stevemao/github-issue-templates |
This is looking great but isn't it a bit too long if it's what everyone is going to see when submitting an issue? i don't think the explanation of issue vs question belongs here so tbh i prefer your first version or something more concise even. @bakercp what do you think? |
Minimal is fine. I agree, it's a lot of text in its current form, so I'd say we should refactor some of the more instructive / pedagogical bits into a refined contributing document. My main goals are to get a good report the first time, rather than having long back-and-forth conversations trying extract information from people. So the basics would just include ...
|
I don't think the explanation of question/issue belongs in a template really, this is something that will appear for everyone when filling an issue so it should be really straightforward to just fill in. And it shouldn't get in the way, you shouldn't have to remove anything except perhaps to replace it i think. Having to delete that bit even if it's just one sentence every time you open an issue can get annoying i think Also if people see the rest of the template (hardware, description of the issue, minimal example...) i think most people will understand that it's referring to an issue and not a question I really prefer to point to the forum and close a couple of questions every year (i don't think the frequency right now is much higher than that) than having to delete parts of the template every time i open an issue |
I also feel it's too much information to read. We could add a simple "If this is your first issue, please read this before continuing" at the top (with a link to a separate document). This way we can keep it short, and put the details and explanations in the wiki. Would that work better? |
That sounds like the right approach.
…On Sat, Jul 8, 2017, 5:19 AM Abe Pazos ***@***.***> wrote:
I also feel it's too much information to read. We could add a simple "If
this is your first issue, please read this before continuing" at the top.
This way we can keep it short, and put the details and explanations in the
wiki. Would that work better?
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<#5652 (comment)>,
or mute the thread
<https://github.com/notifications/unsubscribe-auth/AASVxJJ4GOM5FbuOob7oxdNT0-99CiH7ks5sL1e9gaJpZM4Nz1ee>
.
|
Should I add Getting help with OpenFrameworks at the top of the wiki ? Alternatives names:
I'll move text out from At the top of the template I'll write:
How does that sound like? |
Now it's possible to create multiple templates for different kinds of issues: |
My favorite template is the blank one, but maybe a really basic template would have
|
No description provided.