As you’ve hopefully seen from my last blog post, the Drupal issue queue is quite a powerful system and provides lots of options to help find an existing issue. That said, there’s the obvious situation when the particular task at hand has not been discussed before and a new issue needs to be created. So, lets look at some ways to make sure a new issue covers both the important points and includes useful details to help others find it.
Before proceeding it’s important to decide whether the issue to be opened is for a security problem. Drupal’s dedicated security team makes it one of the best open source projects around. When a security problem is found there’s a specific procedure to follow that allows time to resolve the problem prior to disclosure, which helps avoid the situation of other sites being hacked. So, for our example we’ll deal with slightly more average issues.
Creating an Issue on Drupal.org
At the top of every project’s issue queue list is a link that simply says “Create a new issue”. It’s noteworthy that this link is purposefully not on the main project page, this way it forces visitors to search through the existing issues rather than immediately creating new ones; this greatly helps to reduce the amount of duplicate issues that are opened and keeps issue queues more focused.
Once the “Create issue” page has opened, it’s worth noting that the page provides a link to the procedures page for filing a security report, should it be needed. There are also links provided to pages explaining best practices for filing issues and even a template that can be copied/pasted into the new issue form to be tailored for each specific need. Additionally, each project can add an extra message at the top of this page, for example the Panels issue form has links to the Panels issue submission guidelines and an article from Eric S. Raymond that explains “how to ask questions the smart way,” and is worth reading.
Moving on from there, every issue belongs to a project. When the “Create issue” link is followed the project value will be automatically selected, so that doesn’t need any further thought.
Select your way to a better issue
The two most basic selectors on the form that need answering are the Version and Category fields. The former should be set to the specific version being used on the site, e.g. 7.x-2.5, 6.x-3.2-beta4, etc, or maybe 6.x-3.x-dev if the site is using a development snapshot. Meanwhile, the latter simply indicates whether the item being reported is a bug report, a feature request, or a support request (i.e. “can someone please help me?”); the “task” category tends to be used for issues internal to the module, e.g. planning for the next stable release. These are also two of the most basic filters used when a visitor is searching for an issue, and thankfully they’re pretty straight forward.
One of the options that can be a little confusing is the Component. Projects start with a default list of “Code,” “Documentation,” “Miscellaneous” and “User interface.” Each project can customize the list and add others, so some, like Panels or Views, will have a plethora of options. What can occasionally be confusing is that the specific issue at hand may cover multiple items in the list, or it may not fit any of them overly well. I’ve found that it’s best to just pick something that’s at least partly appropriate, other contributors will help fine tune the selection later if needed.
The final selector that needs some small consideration is the Priority field. The general rule of thumb is that “Critical” should only be selected if there’s a bug which causes data loss, “Major” is appropriate for large bugs or code changes that could have extensive repercussions for the project, and relatively insignificant or unimportant changes (spelling mistakes in help messages, color scheme adjustments, etc) should be marked as “Minor”. Everything else, which tends to be the vast majority of issues, should be simply marked as “Normal”, and the community & maintainer(s) will collaborate to decide if this should be bumped to another priority.
It’s worth pointing out that, as a matter of courtesy, unless the issue is a bug of significant importance, all issues should start at “Normal” and be adjusted as necessary. Furthermore all support requests should always be “Normal,” regardless of your need for an answer. While you may be on a deadline to finish a project and need an answer quickly, the module’s maintainer may be at home dealing with a sick child, tending to a new baby, on a much deserved vacation with their family, or just dealing with their own urgent project. So, be patient and you’ll eventually receive a response.
The meat of the issue, the Title and Description, should be relatively straightforward. When reporting a bug make sure to describe the steps to recreate the issue, the result that was expected and what really happened. Similarly, support requests should explain the scenario and the point in using the module where help is needed. On the other hand, when describing a feature request make sure to give a good rationale for the change - there may be a solid reason for why the module currently works the way it does, so there might need to be a really good reason to change it. The last thing to note is that uploading screenshots can really help at times; just remember to click the Upload button after each one before another one can be uploaded.
Make it better
One suggestion from a co-worker is to pause for a moment before submitting the issue. Often times one of the hardest parts of life is to work out how to phrase a question correctly –sometimes the simple process of writing down a question might be enough to help work out a solution. Furthermore, writing down the issue might help identify the best words to describe a problem; this effort might then help doing another quick search through the issue queue, so it’s worth taking a quick moment to double-check before saving the issue.
For more detailed requests or bug reports, and especially if you have the time to do it, there is an official recommendation on the format to use. Don’t let that put you off, though, remember that issues can be updated after the initial submission, so if further detail is required it can be added later.
As with my suggestion for searching issues, it’s important to remember that the words used to describe the issue can help or hinder someone else’s efforts to find an issue. Because of this it’s worth using different words and phrases to describe the issue, e.g. instead of just saying “CSS” repeatedly add the words “theming”, “display”, etc, that may help others in the future.
An important thing to remember is to be polite and helpful with requests rather than demanding or impatient. A large portion, if not the majority, of issue queue work is done during personal downtime – people are collaborating out of their own sense of compassion or interest in helping the project when they could otherwise be spending time with family or reading a book. With this in mind, requests politely asking questions or making suggestions will receive a much better response than complaints or demands.
Lastly, don’t be afraid to make mistakes – the vast majority of Drupal contributors are really nice people who are happy to help others learn and improve their skills. And remember, further detail can always be added in follow-on comments as needed.
Go forth and create new issues, when appropriate :)
Additonal Resources
Webinar: Building Drupal Features