How to create a more findable Drupal issue

Damien McKenna — Mon, 08 Apr 2013 14:17:21 +0000

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

The Power of Giving

What's new in Drupal 8?

Webinar: Building Drupal Features

Damien McKenna Mon, 04/08/2013 - 10:17

5 Tips for Drupal Newbies

Adam Waid — Thu, 12 Apr 2012 14:26:15 +0000

5 Tips for Drupal Newbies

The attendee list at this week’s Atlanta Drupal Meetup group ran a wide gauntlet. There was a mix of business owners, newbies, marketers, and even someone with a Drupal.org ID under 1000. We broke up our normal presentation format and had informal talks about Drupalcon Denver, the job market, and trends. As usual, we went around the room and allowed for introductions and announcements. When one of the attendees, we’ll call him “Jack”, was in the hot seat, he gave a typical hello, but then broke the introduction format and asked a question back to the crowd. He asked, “I’ve only been working with Drupal for a few weeks, what tips do you have for those that are just starting out?”

You should have seen the room light up with excitement. I saw the same look on my wife’s face when she converted a friend into a Hunger Games fanatic–the look of “let me tell you how wonderful this is.”

Below is a summary of the tips the group provided to this new Drupal’er:

Read Planet Drupal – A great aggregator site for all things Drupal. They have a content upload policy, so you know all the material you will be reading is “the real deal.”
Dig through Drupal.org – Where all Drupalers go to gather information, review modules, themes, groups, etc. Also, when looking through modules on Drupal.org, one tip provided by Kent Lester, was look at the number of downloads. The larger number of downloads usually correlates with a better quality module.
Start with Drupal 7 – This answer came when Jack asked if he should start a new site with Drupal 6, or just begin with 7. The resounding answer was start with Drupal 7.
Read Pro Drupal Development – According to the group, immerse yourself in the book. It teaches you how to create modules, develop themes, and produce filters. It also covers the inner workings of each key part of Drupal, including user management, sessions, the node system, caching, and the various APIs available to you.
Watch DrupalCon/DrupalCamp Session videos – There are videos all over the web from previous DrupalCon’s and DrupalCamps. You can watch all of the 2012 DrupalCon Denver’s videos online. In addition, many of the past Atlanta DrupalCamp videos are hosted on the Mediacurrent site.

Lastly, here’s a personal tip I offer to all of you that are new. Get involved in the Drupal community. There are hundreds of Meetup groups, Co-working days, Camps, Cons, (I even heard someone through out a Drupal Paintball day) that you can participate in. Absorbing what others say and listening to experts in the community will grant you a great knowledge of this powerful open source platform.

What other tips do you have for those that are new to Drupal? Leave a comment and help us compile a comprehensive list.

Adam Waid Thu, 04/12/2012 - 10:26