search

sharppy / SHARPpy

Sounding/Hodograph Analysis and Research Program in Python
https://sharppy.github.io/SHARPpy/index.html
Other
216 stars 112 forks source link

README: Issue Submission Guidelines #174

Open wblumberg opened 4 years ago

wblumberg commented 4 years ago

Are you submitting to Github Issues about SHARPpy problems or suggestions?

The best way is to include as much detail as you can about your issue so we don't have to ask you a ton of clarifying questions. Please include information such as versioning (both Python and SHARPpy), dates/times, sample files, etc. so we can address your issue in a speedy manner. Our development team is small, and doing so will help us use our time efficiently to address your issue.

Some questions you may want to provide answers to when submitting your issue:

  1. What kind of operating system are you using? What versions of the code, supporting packages, or Python are you using?
  2. Have you done any debugging of the problem(s)? If, so what steps did you take? Can you send screenshots showing your problem?
  3. Have you checked to see if others have reported a similar problem? If so, please help us manage the issues by keeping the number of reports we have to address small.

In the future, I will continue to populate this with recommendations and examples for how you can meet these requirements. Future versions of the code will also provide ways to make reporting this information easier.

CAM-Gerlach commented 4 years ago

Why not just make this part of your issue template, so that users see it when they create an issue and can use the questions as a template/form to fill out? Nowadays you can actually have multiple issue templates, e.g. one for bug reports and one for feature requests. Back when I was officially on the Spyder dev team, I got it down to a rather fine science, since we got thousands of issues every year. Happy to share tips if desired.

wblumberg commented 4 years ago

I did think about that, but from what I could tell I couldn't attach any images to the issue template to provide direct instructions for how to find the versioning and log files. If you can direct me to how to develop one, that would be good!

CAM-Gerlach commented 4 years ago

You could embed it just like you embed images in a normal issue, and it would appear just like a normal image when they previewed it (I don't see an image embedded here either, in fact). However, since they will be submitting the image with every issue if they don't delete it, a better strategy would be simply to link to your Readme, Contributing Guide, wiki, Sharppy website, Gist, etc. that contained the image and more detailed instructions. The issue template shouldn't be too extensive, perhaps a paragraph or two of instructions at most and then all the sections you want them to fill in. Its usually better to have more detailed section headings/questions vs. a full prose guide embedded there since users are more likely to read and not skip over the latter...I've known that from years of managing that for Spyder.

wblumberg commented 4 years ago

@CAM-Gerlach I've made some issue templates. Calling in a favor given your offer for tips. Would you mind looking them over to see if there's anything we can do to improve them? Thanks!

CAM-Gerlach commented 4 years ago

@wblumberg Sure thing, anytime! Yeah, looks like a great start I definitely have some, since I worked on this aspect a lot in my time with Spyder...if they had been made as a PR I could just review that, but as it stands the most efficient way is just for me to submit a PR of my own with the suggested tweaks and then you review that in turn, since Github reviews and suggestions are tied to PRs. I'll take care of it this weekend, right now I have a few deadlines this week I have to take care of first. Thanks!