Recipe 87: Creating an issue Page Bookmark
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/
- In Firefox add a new Bookmark onto the toolbar. Select Bookmarks | Organize Bookmarks | Bookmarks Toolbar | Organize | New Bookmark
- 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.)
- Click the Drupal Issue button in the bookmark toolbar.
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.
Recipe 88: Searching the Views issue queue
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.
- Log on to drupal.org (if you are not already a member of the Drupal site, become a member).
- 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.
- You may also sort the table of issues by clicking on the table header. By default, the table is sorted by date.
- 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.
- Get to know the search options.
There are a variety of routes to get there:
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.
- 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
- 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.
- 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.
- Complete the steps to login.
- 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.
- 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.
- 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.
- 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:
- 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.
Recipe 90: Applying a Patch
Patch utility, or Eclipse IDE
A Drupal patch is a text file containing an update to Drupal code. Patches may include bug fixes or additional features. One great thing about Drupal patches is that the special text format makes code changes easy to read. Another is that patches are easy to install—far less time-consuming or error-prone than having to manually update code.
The following is a screenshot of a simple patch to correct spelling. Minus signs signal the original file (either a backed-up file or the original file located on CVS). Plus signs signal the edits made to the new file. Surrounding code is also provided for context.
The steps below are generic, but each step is followed by a specific detailed example. We will find and apply a patch that enables email field sorting and filtering.
- Identify the patch in the issue queue and copy its URL to the clipboard. There is a bit of an art to this. Use the issue queue Search (Recipe 88) wisely and pay attention to feedback on the patch from others in the issue queue. Usually the most recent patch in the queue is the best one to try.
- Visit the issue search for the email module at http://drupal.org/project/issues/search/email.
- Search for the word Views. Select - 5.x issues and the four patch statuses needs work, needs review, reviewed and tested by the community, and patch (to be ported) and press Search.
- Click on the title Email not available as filter in Views.
- Click on the Most recent attachment link at the top of the issue page (this link is not present if the patch is in the initial post and no new patches have been uploaded).
- Click on the email.module.patch link.
- Copy the URL for the patch to the clipboard. In this case, this URL will be http://drupal.org/files/issues/email.module_5.patch
- Open a window to the host account, and navigate to the module directory.
- Backup the file that you intend to patch.
cp email.module email.module.backup
- Get the patch file.
- Patch the file.
patch < email.module_5.patch
- If you have enabled the email module and created an email field, the email field now appears in the filter and sort fieldsets at admin/build/views/add.
(This step is not entirely necessary, since the –b switch on the patch command will also do this. The author's preference is to make a manual backup.
(There is no need to type the URL. Just use the paste function, which on a unix terminal is often the right mouse button.)
- Congratulations for trying this recipe! You are greatly enriching your Drupal experience by being able to apply patches to contributed modules. The recipe may look more daunting than it really is. We spent most of the recipe tracking down the patch, and placing it in the appropriate subdirectory. The actual patching part is a simple one-line command shown in Step 5.
- The steps for applying patches to Drupal core code (as opposed to contributed modules) are slightly different. Contributed modules use a command like this and run from the module subdirectory:
patch < file.patch
patch -p0 < path/file.patch
Drupal core patches, however, are applied from the Drupal root directory as follows:
history | grep -i "patch"
patch -R <file.patch
Recipe 91: Creating a Patch
Regardless of your Drupal programming skill level, you may submit patches to the Drupal issue queue. Module maintainers and users will appreciate patches ranging from spelling corrections, to more complex bug fixes and new features. Patches may be created with the diff command or the CVS diff command. The example below uses diff.
- Backup the file intended for editing.
cp views_ui.module views_ui.module.backup
- Edit the file with the editor of your choice.
- Run the diff command to create a patch. Notice that the command uses the -u and -p switches and compares the original file (first) to the edited file (second). The diff is then redirected to an output file, usually named with a .patch extension.
diff -up views_ui.module.backup views_ui.module > views_ui.module.patch
- Post the patch to the issue queue (Recipe 89). Be sure to set the patch status to patch (code needs review). Other users, and/or the module maintainer will test the patch to determine if the patch is reviewed and tested by the community—often abbreviated in online conversation as RTBC. (In other open source communities, this acronym stands for Ready to Be Committed but the two meanings are nearly equivalent.)
Patch command switches
The -u switch in the patch command stands for unified context diff, which is the desired format for Drupal patches. In addition to using the plus and minus characters to signal file changes and including surrounding code for context, this format also features informative double at signs. These enclose information about where the changes were made. This line notes that beginning at line 858 in the original file, and at line 858 in the new file, a range of 7 lines is included.
@@ -858,7 +858,7 @@
The –p switch stands for prefix. One practical and little-documented effect of using this switch is to include the name of the function in which the code appears. This provides additional context to help Drupal users to understand the patch.
- Per the maintainer's discretion, many patches will be incorporated into new module releases, while others simply remain available as options.
- More information about creating patches can be found at http://drupal.org/patch/create
- Windows users may use the diff utilities in the cygwin package (http://www.cygwin.com/) or in stand-alone utilities found at http://unxutils.sourceforge.net/. Windows users need to ensure that the patch file ends with a Unix line ending. Otherwise, patches generated in windows are likely to cause errors for people who attempt to apply them (test your windows patches to make sure they work).
Recipe 92: Installing a Search plugin for the Contributions API
This recipe enables search of selected Drupal web sites from the web browser search form. It's a quick alternative to maintaining bookmarks to these sites. In our example we install a search plugin for the Contributed module API website at http://api.freestylesystems.co.uk/api/5.
The search results include files and functions found in more than two-hundred Drupal 5 modules including Views and the Views Bonus Pack. The same technique can also be used to search api.drupal.org.
- Visit http://mycroft.mozdev.org/search-engines.html?name=drupal.
- Click on the Drupal Contributions API 5 link and select the Add button.
- Go to the search bar in the upper-right hand corner of the browser, click on the down arrow, and select Drupal Contributions API 5.
- Enter a function name, or part of a Drupal module function name, in the search box, such as views_style_plugins.
- Be sure to remember to set the default search back to your favorite general search engine.
This performs a search of browser search plugins containing the word drupal.
This pulls up the search results at the following URL: http://api.freestylesystems.co.uk/api/search/5/views_style_plugins&sourceid=Mozilla-search
- An even quicker way of using the search plugin (in lieu of changing the default search engine for each use) is to create a plugin keyword. In Firefox, click on the down arrow next to the search form, choose Manage Search Engines… and select Drupal Contributions API 5, and click Edit Keyword. For the contributions API search, we've entered the keyword capi.
- OpenSearch plugins work in Firefox, Chrome, and Internet Explorer (Internet Explorer calls them Search Providers). If you are a Chrome browser user, click on Options | Basics | Manage to move the Search plugin into the Default list.
- The Mycroft site offers additional Drupal search plugins both for the standard Drupal Core API site, and for searching Drupal modules.
- Additional search plugins are available at https://addons.mozilla.org/en-US/firefox/browse/type:4/cat:all?sort=name.
- If you become a fan of using OpenSearch plugins, try the Add to Search Bar add-on for Firefox, at https://addons.mozilla.org/en-US/firefox/addon/3682.
Now you may enter a search phrase such as capi views_style_plugins or capi views_tables in the Address Bar. (Note the difference between the Address Bar and Search Bar, below.)
Recipe 93: Using IRC—real-time technical support
Web Browser, or IRC Client
IRC is a powerful resource for Drupal users. The letters stands for Internet Relay Chat, but almost no one says those words in conversation. Most prefer to say IRC or Chat. The word chatroom is generally not used in the Drupal community. Each conversation area is called a channel.
The quickest and easiest way to participate in the IRC Drupal support channel is to follow these steps:
- Visit http://www.drupalchat.net, and enter a nickname. Most people use their drupal.org account name (this is not required, but it does help people better know with whom they are speaking).
- Channels load in alphabetical order. Press the > symbol until you see the #drupal-support tab (it may be a bit hard to see as it's on a dark background).
- Click on the #drupal-support tab.
- Place the cursor in the non-descript grey edit box below the conversation. Type and press enter to post a question or comment.
- Be sure to read the drupal.org handbook page on chat, http://drupal.org/irc.
- The most common newbie mistake is to post questions about the Drupal administrative interface on the #drupal channel. The handbook page clearly notes that, "Help for anything you can do with Drupal inside the web-based admin screens is best found" in #drupal-support.
- If you desire a more customizable experience than DrupalChat.net, there are many IRC clients available, including both stand-alone and browser-based clients. The ChatZilla firefox add-on is a helpful resource. A helpful ChatZilla FAQ is at http://chatzilla.hacksrus.com/faq/, while the add-on may be downloaded at https://addons.mozilla.org/en-US/firefox/addon/16. Also worth exploring in browser-based clients is Mibbet.com.
- Addison Berry created a terrific video guide to web-based IRC at http://www.lullabot.com/videocast/using-irc-your-browser.
- There are a few basic commands that you will need when using any other tool besides DrupalChat.net. First join the freenode network (either by clicking on a link, or setting it up as a default in your client). Use the /join command to load a channel as follows: /join #drupal-support.
- Consider registering your "nick" (Nickname) with the freenode network. Information on how to do that is available at http://freenode.net/faq.shtml#nicksetup.
- Several of the Drupal channels have an interesting participant, a robot ("bot") actually, named Druplicon. Druplicon seems like just another user, but this user answers certain questions instantaneously!
- There is a #drupal-views channel. It is not to be used for support questions, but rather for the development of Views and Panels in Drupal versions 6 and 7.
- Posts on Drupal channels are logged, and may be searched at http://www.disobey.com/bot/log/drupal-support, or searchirc.com.
Recipe 94: Exploring Resources
Examine the following helpful web sites and bookmark (or memorize) your favorites.
URL and Comments
Local groups connect you with other users, the best Drupal resources of all. If you search for your state or region and don't find it a group, consider starting one.
Views 1.x Module Snippets
Project usage overview
Search for drupal.org users by name
Views 1.7 Issue
Just for Fun: Views T-shirt
"I don't know the question. But the answer is Views."
The first five recipes in this article are related to the Drupal issue queue found at http://drupal.org/project/issues/, or http://drupal.org/project/issues/<MODULENAME>
We created a quick way to go from a lone issue number on a web page to the actual issue page. We looked at essential skills for searching and posting to the issue queue, and then covered critical Drupal skills: how to apply an existing patch, and how to create a new one.
We looked at a nice plugin to add web site searches directly to the browser address bar. We applied this to search the Contributions API site. (It could be used just as well to api.drupal.org, and many other sites that contain search.)
We covered some key IRC concepts and saw a super-quick way to access the Drupal support channel. Finally, we provided a short survey of some useful web pages and sites.
Although the article focuses on online resources, groups.drupal.org will put you directly in touch with other Drupal users—close enough to shake hands and share a beer (or for the teetotalers among us, some coffee or tea). Show off your website views. Invite others to share the passions reflected in your projects. Share your knowledge. Ask questions. Above all, Enjoy.