I often hear from people that they are nervous about using the issue queue on drupal.org. This is understandable, the issue queue can be a scary place! Say the wrong thing in the wrong way, and your favorite drupal developers turn into grumpy curmudgeons and mark your issue as 'won't fix'.

Today, I walked to through the process of creating an issue with a friend over lunch, and thought it might be useful to post it here as well. Below you'll find the basic ingredients for creating an issue in the queue.

1) thank you
2) this is what I have
3) this is what I want
4) this is what I know already
5) how can I help you to help me
(sprinkle on sugar liberally)

1) Start by saying thank you. Most module maintainers are doing it for free, because they love Drupal, their project, or the community. If you are about to ask them for help, advice, or favors, it's nice to thank them for all they have already given to you and your own cause.

2) Start at the beginning. Explain what you have on your Drupal site already, this can include a list of modules (with version numbers please) which version of Drupal, and your underlying site architecture (For example: "I have added a geofield to my users and I have set up a view of nodes with a geofield as well").

3) Explain what you are trying to do. Don't focus on the user interface that may be broken or the code that won't import, instead start with the big picture and state your use case. If the maintainer knows what you want to do with their handy tool, they'll have an easier time helping you troubleshoot where you've gone wrong, or identifying a bug that needs to be addressed.

4) Do some homework first. Search the issue queue for your problematic module or theme (or use Google if you don't know which module to blame) and make sure someone hasn't opened exactly the same issue before. If they have, be sure to try the suggestions in the current issue and see if they work for you as well. If they don't work for you, of if there aren't any helpful replies yet, add a comment in the existing issue that follows this same formula. Be careful not to accidentally (or purposefully) take over a similar-but-unrelated issue. When in doubt create a new issue, but when you get to step 4 add links to the other similar (but not exactly the same) issues you've discovered, as well as the things you've tried already. Telling the maintainer what you know might save them some time while helping you. Be sure to include any error messages on the page, or in the logs (check your drupal log, and if possible your PHP or Apache logs too).

5) When you get around to asking your question, be sure to phrase it in a way that indicates that you are willing to do some work too. Don't expect maintainers to fix the bugs for you, instead ask where you should be looking to fix the bug yourself. Even if you are not a coder or don't feel comfortable making the change without help, you'll find that people will be more likely to help you (or even do it for you) if you are willing to contribute something too. Ask how you can help make progress on your issue if you don't know already. Offer to write up some useful documentation (with screenshots!) if you don't feel that you can contribute anything else.

If you are filing an issue against Drupal core, It's a good idea to follow the Issue Summary Standards set out by the core team. There's even an empty template for you to cut and paste. This format is less crucial when working in contrib.

And last but not least, be sure to be nice. I know most developers (myself included) can turn into gremlins in the queue, but a few smiley faces for punctuation, pleases and thank-yous can go a long way to eliminate the backlash. Open Source developers just want to feel appreciated, and with a little love you'll find we're actually quite eager to please you.