Recipe 87: Creating an issue Page Bookmark

Ingredients
Web Browser

The issue queue is the central place of progress for Drupal modules. It serves as a place to find answers, patches, new ideas, and work on common concerns. Issues are referenced by number. On occasion, a web page will contain an issue queue number in text form rather than a full link to the issue. This recipe, once set up, simply saves the trouble of having to type drupal.org/node/ into the browser address bar. Just select the number and the bookmark will take you there.

1. In Firefox add a new Bookmark onto the toolbar. Select Bookmarks | Organize Bookmarks | Bookmarks Toolbar | Organize | New Bookmark
2. Set the Name to Drupal Issue and set the Location to the following: javascript:inum=escape(getSelection());location.href=’http://www.drupal.org/node/’+inum.



3. Visit a web page that contains an issue number and select the issue number text. For instance, try http://cvs.drupal.org/viewvc.py/drupal/contributions/modules/views/modules/views_taxonomy.inc.

   (Be sure to exclude the surrounding space and pound sign when selecting the number.)



4. Click the Drupal Issue button in the bookmark toolbar.

Recipe notes

This bookmark approach may be replicated to visit a URL containing any selectable text. For instance, below is a variation to display all of your delicious bookmarks tagged with the selected text. (Delicious.com—also found at http://del.icio.us, is a wonderful online bookmark service.) Replace <ACCOUNTNAME> with your delicious.com account.

Name: Delicious
Location: javascript_tag=escape(getSelection());location.href=’http://delicious.com/<ACCOUNTNAME>/’+tag

Recipe 88: Searching the Views issue queue

Ingredients
Web Browser

In this recipe we look closely at how to search the Views issue queue. The lessons apply to all other Drupal projects as well. It is always a good idea to search the issue queue for related content before posting.

1. Log on to drupal.org (if you are not already a member of the Drupal site, become a member).

Basic Search

2. Visit http://drupal.org/project/issues/views. At this main issue queue page you may search for text or filter by Status, Priority, Category, Version, or Component. These options are discussed in further detail below.
3. You may also sort the table of issues by clicking on the table header. By default, the table is sorted by date.

Advanced Search

4. Go to the Views issue queue Advanced Search page.
   • Visit the URL directly, at http://drupal.org/project/issues/search/views.
   • From the project page (drupal.org/project/views), find the Issues block on the left, and click on the Advanced Search link.
   • From the issue queue (drupal.org/project/issues/views), the Advanced Search Link appears under the title.

There are a variety of routes to get there:

5. Get to know the search options.

Although there are ten form elements to choose, most users will routinely use just a few, leaving the other options blank.

• Search For (Routinely used): Enter search text. Use quotation marks to create a phrase.
• Assigned: This field is generally used by issue maintainers.
• Submitted by: This is most often used to find your own issues, though it could be used to see what other Drupal users are posting as well.
• Participant: This is also used to find your own posts. Note that Submitted by finds only the initial post by a user in the issue queue. Participant additionally includes responses to initial posts.
• Status: Leave blank to get all statuses. You may also select multiple options. For instance, you could select all issues designated as needs work, needs review, and reviewed & tested by the community. Scroll down the list and note Status filters such as closed issues, duplicates, issues that the maintainer won’t fix, and features noted as by design. These are the statuses that are excluded if you select -Open Issues-.
• Priority: Leave blank to get all priorities.
• Category: Leave blank to get all categories.
• Version (Routinely used): A relative new option, 5.x issues saves you the trouble of having to Shift+click on each Drupal 5 release name.
• Component: The views module issue queue offers more component options than most modules. As a result, users may not always be familiar with properly assigning a component when they create an issue. A search of exposed filters components, for instance, may not find as many results as a text search of “exposed filters.” Component can occasionally be a helpful selection, but is most often left blank.
• Issue Tags: These may be a challenge to search since few people add tag issues. This may become a more popular option in the future.

Recipe notes

• Search ideas:
  • Find all your posts by filling in your drupal.org user name under participant.
  • Find patches by selecting all of the four patch statuses.
  • Find all documentation issues connected to Views for Drupal 5.x.
  • Go to another issue queue http://drupal.org/project/issues/search/<MODULENAME> and search for the word Views.
• From the module issue pages http://drupal.org/project/issues/<MODULENAME> you may also review module Statistics, and Subscribe to issues. Subscribe to your Own Issues (the default), None, or All Issues. I don’t recommend the latter for the Views module as you will be setting yourself up for a deluge of email.
• Search across all projects at http://drupal.org/search/issues.

Recipe 89: Posting an issue

Posting a New issue

1. If you are new to posting Drupal issues, consider just reading the issue queue for at least several days before posting. This will help you to get a sense of the culture of issue queue interaction.
2. If you don’t already have an account on drupal.org get one. Look for the User login block on the home page, and click on Create new account.
3. Complete the steps to login.
4. Search the issue queue before you post! (Recipe 88). If your topic already has an associated active issue, reply rather than posting a new issue.
   Also, before posting to the issue queue in a panic read the Drupal Troubleshooting FAQ http://drupal.org/Troubleshooting-FAQ. For instance, standard fare is to increase memory in the face of the White Screen of Death (WSOD) or to disable buggy modules by setting the status = 0 in the system table.
5. Be sure to know which version of the module you’re using. Is it the dev (development) version? Is it the latest recommended release? The version number can generally be found at http://YOURSITE.com/admin/build/modules.
6. To start a new issue, go to http://drupal.org/project/issues/<MODULENAME> and click on Create a new issue. This directs the browser to: http://drupal.org/node/add/project-issue/<MODULENAME>.

For the Views module, the link at http://drupal.org/node/add/project-issue/views offers guidance (in bold!) for posting. Read it! Much of it applies to Views 2 but it contains useful information for Views 1 users as well.

• Required fields for a new issue include Version, Component, Category, Title, and Description. Be thoughtful with these details. For instance, do not title your issue HELP??!! A much more useful description would be something like Missing taxonomy terms in filters.
• Priority should generally be left as normal. Critical is reserved for occasions then the module simply does not work.

Responding to an existing issue

You may also respond to an existing issue by selecting the Add New Comment link or one of the Reply links on an individual issue page. Another option is just to scroll down to the bottom of the issue page, and begin entering a response. Unlike some forum tools, in which replies are indented, all new comments are given a new comment number, and added to the bottom of the comments.

When responding to an issue you may take a variety of actions:

• Change the Issue Title. In general, don’t change this unless you have a very good reason (for instance, if the original title is misleading, or spelled wrong). Some people are used to forums where a response can have a different name as the original post. In the issue queue, changing the name when responding to an issue actually changes the name of the issue. This is generally best left untouched.
• Change the Project. A question that someone asks in the Views issue queue may be more appropriately managed in the issue queue for a different module. This is a rare change generally left to the maintainer of one of the two modules who will know in which issue queue a discussion belongs.
• Change the Version number, Component, Category, or Priority. These changes are rare (correcting the version number is probably the most common). When changes are made, they are noted in the post as shown below:



• Change Assign. Do not assign someone other than yourself to an issue. Assign yourself if you are sure that you will soon fix the issue. It is quite common to leave this as Unassigned.
• Change the Status. For instance:
  • Mark an issue as a duplicate (always provide a pointer to the issue it duplicates).
  • Note that a patch is reviewed and tested by the community.
• Post a question, patch, answer, or idea related to the issue in the Comment section. Open the Input format fieldset below the comment field to see what markup is available. Note the <code> tag, for instance (and remember to close it with a </code> tag).
• Attach a file.

Recipe notes

• Remember that respondents and maintainers are volunteers. They are generally very busy people who want to help, but they do not have time to do free consulting.
• See the following pages for spirited discussions about issue queue etiquette:

http://acko.net/blog/whats-wrong-with-drupal

http://paul.leafish.co.uk/articles/drupal/on_subscribing_to_module_portingupdating_issues

• One discussion theme is the merit of simply sending the word subscribe to the issue queue. People sometimes do this so that they can track an issue—receiving an email alert each time something new is posted. On drupal.org it is possible to subscribe to a node only if you leave a comment, but most people prefer comments with substance.

You may create functionality similar to the Drupal issue queue on your own site by installing the project, project_issue, and comment_upload modules.