If you've run into a problem, opening an issue is an easy way to let us know and keep track of progress. But not all issues are created equal, and I have issues with that (oh good pun Ad!).
Before even opening an issue, make sure it doesn't already exist. Nothing makes Adarnof more MADarnof than duplicate issues (another excellent pun, Ad!)
The title is the first thing people see when looking for issues. So it should be the simplest, most descriptive part of the issue. Try to sum up your idea / problem in one short sentence.
For instance, if it's a feature request, describe the feature in a brief statement.
Add blues without standings API key is a good feature title.
Feature Request: TS3 is a bad title. People should get the gist of the feature from the title.
If it's an error, include the most relevant part of the error message. This will usually be a portion of the last line of the traceback.
openfire-restapi install ImportError: No module named requests is a good issue title.
Requirements.txt errors is a bad title.
ERROR [handle_uncaught_exception:124] is a worse title.
Server Error (500) will get you
shot added to the Red Pen List. Developers should have a general idea what they're getting into before opening the issue.
Don't prefix your title with a category. That's what labels are for. If it's a feature request, I'll add a
Feature label once I read it. Adding
Feature Request: to the title doesn't help anyone.
If I don't like your title, I will rename it. This makes it easier for others to find.
This is the meat of the issue. Here you get to describe exactly what's going on.
If it's a feature, talk about it. What is it? What does it do? What does it accomplish? How should it work? What permissions does it need? On and on. The more thought-out, the better.
If it's a problem, I need to be able to re-create it. Lay out the scenario - what were you doing when it occurred? What did you expect to happen? What did happen? If you got a traceback, include it.
To nicely format a traceback, wrap with three backwards apostrophe character like so:
``` traceback goes here ```
Ensure the backwards apostrophes are on their own line for it to embed properly. For really long tracebacks, a link to pastebin is preferred.
Issues can only have on title. Therefore issues should only be about one thing. Too often people are combining issues together; all this does is ensures the next person searching for issues can't find it.
Use your best judgement here. If you have multiple feature ideas but they all revolve around the same thing, it's acceptable to open only one issue. But if you have an idea for CorpStats, and an idea for a new service, keep them separate.
At the same time, don't tack your problem onto someone else's issue unless it's exactly identical. If there's an open issue about TS3, and you're having problems with TS3, don't hijack the thread. Read the issue, and if you're having the same problem, pay attention to the issue. On the right side of the page there's a link to subscribe to email notifications, this will keep you updated of any developments.
I may have questions. I may need more information about your issue. Others may have feedback on your feature. Until it's resolved, please pay attention to your issue. Github sends email notifications when a comment is added to your issue.
I close issues from people who don't follow up. Don't be that guy.