Table of Contents

twodotcuddlyInternet and Web Development

Dec 4, 2013 (3 years and 11 months ago)

2,470 views

Table of Contents
.................1Developing for Drupal
..............2Contributing to Development
................2Types of Contributions
...................3Task list
..................3Bug reports
.............4How to report bugs effectively
.....10HOWTO: Help with QA - OR - What to do when you find a bug
.......10You want to give back to drupal without programming
.........10You’ve been bitten by a bug and want it fixed
...........10Ultimate Goal: Helping the Developers
.............11Getting a Bug Fixed Sooner
..............11Improving Bug Reports
............11Increase Visibility of the Issue
...............11Providing a Patch
...............11Improving a Patch
..........12Hire Someone or Providing a Bounty
.........12Ineffective Methods of Getting a Bug Fixed
...........12HOWTO: Make A GOOD issue report
...............12Project Information
...............12Issue Information
................13Issue Details
..............14HOWTO: Submit core issues
...........15Criteria for evaluating proposed changes
..15Effectively raising money to work on improvements to Drupal (reverse bounty)
...............16Post a reverse bounty
................16Show me the money!
................17Complete the work
................17Feature suggestions
...........17Priority levels of Issues (Bugs and Features)
................17The revision process
............18Maintaining a project on drupal.org
...............19Controlling CVS access
.......20HOWTO: Checkout a drupal module from Drupal CVS
................20Orphaned projects
.............21Tips for contributing to the core
.................21List of maintainers
...................23Mailing lists
...................23Support
..................23Development
...................23Themes
.................23Documentation
..................23Translations
...................23Consulting
..................24CVS commits
i
Drupal Handbook 3 Aug 2007
..................24CVS applications
....................24Webmasters
...................24Infrastructure
....................24DrupalCON
....................24Subscribe
.................25Mailing of project issues
...................26Coding standards
................26Drupal Coding Standards
....................26Indenting
..................26Control Structures
...................27Function Calls
.................27Function Declarations
.....................27Arrays
....................28Comments
...................28Including Code
...................28PHP Code Tags
................29Header Comment Blocks
....................29Using CVS
...................29Example URLs
.................29Naming Conventions
.................29Functions and Methods
....................30Constants
...................30Global Variables
....................30Filenames
...............30Doxygen formatting conventions
..................33Configuring Eclipse
...............33For PHPeclipse - PHP editing
.......33For Eclipse Web Tools - CSS, JS, XML and (X)HTML editing
..................34Configuring Emacs
..................34Configuring vim
...................34Indentation
.................34Syntax highlighting
.............34Using these settings only with Drupal
.............35Guidelines for better performing code
.................35String Comparison
....................35Indenting
...................35PHP Code tags
................36SQL naming conventions
...............37List of SQL Reserved Words
.................37Reserved Words
.................73String concatenations
....................73Use of icons
...............73Write E_ALL compliant code
.................73Introductory notice
................74E_ALL: a better practice
.........74Common coding mistakes and new coding practice
........741- Use of if isset$var or if !empty$var
ii
3 Aug 2007Drupal Handbook
................75Testing for error notices
....................76Functions
....................76Constants
..................76Control structures
.................77Header comment blocks
..................78Writing secure code
...............79HOWTO: Report a security issue
................79Contact the security team
...................79A good report
.....................79Credit
.................79Input, the root of all evil
........80The Drupal philosophy - Escape or filter when appropriate
...................81Database access
...........82Parametrized query prevents SQL injection
............83File uploads, downloads and management
...................83Directories
...............84Handle text in a secure fashion
...................86In practice
...................87Writing filters
....................87JavaScript
....................88Session IDs
................88When to use db_rewrite_sql
............89Contacted by the security team. Now what?
.................89What you need to do
...............89What the security team will do
............89Coordinated release and announcement
......................91CVS
..................91CVS Introduction
..................93CVS Usage Policy
....................93General
...................94File locations
.................95Sandbox Guidelines
.................95CVS GUIs and clients
................95Command-line CVS (Mac)
.................95Cervisa (Linux/Unix)
...................96CVL (Mac)
...............96Setting up/step by step CVS
................98Basic CVS with CVL
.................98Preparing a project
................99Committing a project
..............100Eclipse CVS plug-in (all platforms)
.........100Checkout Drupal CVS into the Eclipse Workspace
............100Installing Eclipse with PHP Support
..........100Checkout Drupal in your Eclipse Workspace
.101Eclipse team project set to checkout Drupal & contributions for 4.6, 4.7, 5.0 and CVS
............102How to: Install and configure Eclipse
...................102Overview
iii
Drupal Handbook 3 Aug 2007
..................102Install Eclipse
..................102Setting up
..................102Checking out
................104SmartCVS (all platforms)
................104TortoiseCVS (Windows)
.......105Retrieving an older version of Drupal or Drupal modules
................105WinCVS (Windows/Mac)
................105Adding a new project
............106Checking out a project using WinCVS
.................107Drupal CVS repositories
..................107Main repository
................108Contributions repository
..............109Annotated CVS checkout example
...............110Drupal CVS branches and tags
.............110Overview of core branches and tags
.....................110Branches
..................110Official release tags
................111Beta and release candidate tags
...........111Overview of contributions branches and tags
..................112Official release tags
...................113Stable branches
...............113Development and other branches
...............113List of core branches and tags
..................114Available branches
....................114Available tags
...............115List of contributions branches
...............116Maintaining projects with CVS
.............117Apply for contributions CVS access
.......118General guidelines for using Drupal’s CVS contrib repository
..........119Commit messages - providing history and credit
...................119Give details
...........119Reference the drupal.org issue, if available
...................119Give credit
...................119Example
.................120Managing releases
................120Introduction to releases
.................120Types of releases
...................120Official releases
...................120Snapshot releases
....................121Release types
.............121Release tags and version numbers
..................121Official Release Tags
...................122Version numbers
...................122Branches
............122Stable branches for a specific version of core
............123Development branches for new functionality
..............123Strategies for using HEAD effectively
iv
3 Aug 2007Drupal Handbook
......123Use it for the "new feature" branch for the current stable core
......124Keep up with the version of core currently under development
..................124Release nodes
...........124Creating a release node for your project
.................125Things to watch
..................126Fixing releases
...............126Sandbox maintenance rules
..............127Step-by-step: Create a CVS project
............129Troubleshooting common CVS problems
.....129CVS implications of moving core modules into their own directories
............130How do I delete a directory from CVS?
...........131Resolving a ’sticky tag is not a branch’ error
..............132Implications of the new release system
................132Steps to solving this problem
.........133Why drupal.org doesn’t host GPL-"compatible" code
..............133CVS maintainer quick-start guide
......................133Basics
...................133Logging in to CVS
................134Adding a new module to CVS
...............134Saving changes to your module
.................134Obtaining latest changes
..................134Branching and tagging
............135Branching for a specific Drupal core version
.................135Creating an official release
.........136Branching for new development versions of your module
.........136Creating a development snapshot release of your module
....................136Deleting a tag
..............137Saving changes to multiple branches
....................137Advanced usage
.......137Checking out a copy of each branch of the contributions repository
......138Quickstart guide for adding to Drupal CVS using a windows client
..............139Adding a theme to Drupal CVS
..........140Creating a project for your theme on Drupal.org
.............140Using CVS to maintain a Drupal website
..............140Why maintain a site from CVS?
..............141How to maintain a site from CVS
..............141Step 1: Check out code from CVS
...............141Step 2: Checking for updates
................141Step 3: Updating the site
............142Upgrading to a different version of Drupal
.....................142Tips
Apt-drup - Check out drupal and contribution modules yet perserving orignal CVS
....................142keywords
........143cvsdrupal - checkout and maintain a local CVS repository
.....144Advanced: Using a repository to track local changes to Drupal code
...................145Example
................146Managing contributions
v
Drupal Handbook 3 Aug 2007
...............148Updating the vendor branch
...................150Summary
................150Additional resources
..................150Other CVS resources
.....................151Patches
...........151Background: the basic concept of Diff and Patch
..................151diff creates patch
................151Why you would use diff
...............152The tools at your fingertips
..................152Applying patches
.................153Common problems
...............154Apply patches on MacOS X
............154FileMerge: Mac OS X Patching Utility
...............154Apply patches on Windows
....................154Cygwin
....................156Patch
...................156UnxUtils
..................156Reviewing patches
.................156General guidelines
.................157Reviewing process
................157Authoring a patch review
........157HOWTO: Set up a test environment to help review patches
..................160Creating patches
..................160CVS diff vs. diff
.................160Check your directory
...................161Readability
............161Separating your changes and whitespace
.............161Line endings and directory separators
...................161The command
.................162Adding/Deleting files
................162An example using cvs diff
.................163An example using diff
.........163Common issues with patch creation and application
...........163patch unexpectedly ends in middle of line
...............163Create patches on MacOS X
..............163TextMate + CVS or Diff bundle
..................164Diff Bundle
..................164CVS Bundle
...............165Create patches on Windows
....................165CVS
...............166Several win diff programs
...................168Subversion
..................168TortoiseCVS
............168Step 1: Checkout Drupal from CVS
...............169Step 2: Creating a patch
..................169TortoiseSVN
...................170UnxUtils
vi
3 Aug 2007Drupal Handbook
...................170WinCVS
...................171WinMerge
..................171Submitting patches
................171Coding style and security
.................171Describe your changes
..................171Verify your patch
.................172Submit your patch
............172Patch spotlight: Code Freeze Cram-a-thon
...................172Description
..................172Cool new features
.................172Internationalization
...................173Performance
................173Form API improvements
...............173Menu system improvements
................173File and Image handling
....................173Testing
..........174What do I do if I find a bug while testing a patch?
...............174General patch reviewing tips
...................174Tips and Tricks
..................175Patching shortcuts
..............175sed - replace text in multiple files
....................177Drupal’s APIs
...............177Cache API and caching tutorials
..............177General introduction and tutorials
...................177References
.................178Further information
...............178What value to use for $cid?
................178What cache table to use?
.................178Clearing obsolete data
...................178Development
....................179Forms API
...............180Forms API Quickstart Guide
...........180Form API Workflow - Updated to Drupal 5
.................182Forms API reference
..........183Dynamic and Multipage forms with Forms API
............183Dynamic Forms: Three Different Scenerios
...................183Form API 1.0
.............184The Problem With Dynamic Forms
...............184Form API 2.0: The Solution
.............185How to Handle the Three Scenerios
..................185The Long Form
...................187The Wizard
...............187The Form That Builds Itself
...................189The Wrapup
...........189Multipage forms with the Forms API (4.7)
......190Why can’t I make multipage forms with what I already know?
..............191A Fully Working Example
vii
Drupal Handbook 3 Aug 2007
.........192Redirecting Users After Submitting a Form in Drupal 5
............192In the beginning was the form function
...............192Theme, validate and submit
.................193Where to go now?
.........193How to override default form redirection in Drupal
.......194Bonus: got a headache with redirection after registration?
................194Upgrading to forms API
..........195Example module conversion: Project Module
...................195Overview
.................196Conversion Tips
.................196Form Updater
..............197Common legacy form errors
....198project_settings: Converting a hook_settings implementation (Easy)
...................198Overview
.................199Original function
.................200Form conversion
..............201hook_settings changes in 4.7
.................201Default values
................202Converted function
............203Core module before and after examples
..............203Standard example: Path Form
...................203Before
....................204After
........205Fieldsets and advanced fields: system_view_general
...................205Before
....................209After
.......218Validation and execution functions: contact_mail_page
...................218Before
....................221After
.............225Theming forms: system_themes
...................225Before
....................226After
.............230Advanced themeing: system_user
...................230Before
....................231After
..........233Drupal 4.6 vs. Drupal 4.7 Forms API Flowcharts
...............233Drupal Pre-4.7 Forms API
................235Drupal 4.7 Forms API
..................237Forms API FAQ
..................237Validation
..........238How do you use the #validation arguments?
......238How do you validate a URL, e-mail address or integer value?
is the nodeapi ’validate’ op to be used anymore given the validation features of the
................238new api? if so, when?
..................238Form logic
How do you handle multiple submit buttons in a form? Where do you put the
.................238’dispatch logic’?
viii
3 Aug 2007Drupal Handbook
..............238What does #after_build do?
.................239Miscellaneous
.........239How do I add a taxonomy selection to my form?
.........239Why was the #attribute_name convention chosen?
..................239Tips and Tricks
.................239#tree and #parents
........241Adding a custom element type & expanding elements
...................244#process
........244Adding and theming additional fields to a node form
.....245Adding your own extra _submit or function using hook_form_alter
....245An alternative approach to columns and other detailed layout control
........245An alternative approach to columns and related things
..................245Introduction
...................246More IDs
.............247How about an ID for the form?
.........247Now, how about getting some use out of all this?
................251changing title of a node
.............251Creating an array of form elements
.........252Creating fieldsets outside forms with minimal code
...............253Creating multi-part forms
............256Creating submit buttons with images
.........257Develop a simple block module with a simple form
..............258Easier debugging of forms code
............258Getting a form element without a form
................259Handling File Uploads
........259Modifying checkboxes to display in multiple columns
..............262Module dependency checker
..............264The form_set_value function
............266Using form builder for "normal" forms
................268Writing forms in tables
....................269Schema API
...............269A sample schema structure
........270Creating tables: hook_schema, .schema and .install files
..........271Updating tables #1: hook_update_N() functions
...........272Updating tables #2: Don’t use hook_schema!
.................274Schema API Reference
................274Schema data structure
................275Schema API functions
...................276XML-RPC API
..........276HOWTO: Connect Flash to Drupal via XML-RPC
...................276Flash Setup
....................277Flash
....................277Drupal
..............277Services and amfphp modules
...............277Your own api.drupal.org site
...............280HOWTO: Benchmark Drupal code
....................280Introduction
ix
Drupal Handbook 3 Aug 2007
..................280Tools of the Trade
...........280Setting up a performance testing environment
..................282Benchmarking code
..................284interpreting results
................284Drupal benchmark results
............285List of modules seeking help or maintainers
..............286Setting up a development environment
..................286Development tools
....................286Browsers
....................286Editors
.............287Integrated development environments
...................287Other Tools
...................287Using Cygwin
.................287Setting up Cygwin
...............288Getting to know Cygwin
..............288Checkout Drupal files from CVS
...................288Patch Files
...................289Usability research
.................289Administrators Survey
...................289Methodology
............289Start by Interviewing Administrators
................289Designing the Survey
..............289Collecting Results and Analysis
.................289Biases and Caveats
...............289Respondent self-selection
..................290Reponse rate
...............290Answer prompt ordering
...............290FIlling out multiple surveys
..................290Overall results
...................299Appendices
.............300Summary of Interview Responses
................307List of all respondents
.................326Survey Questions
.............329Portland UI-SIG cognitive walkthrough
................329Introduction to Drupal
...............330Review tasks and installation
................330Creating the first account
................331Customizing the theme
..................331Creating a page
..................332Ending comments
..................332Who uses Drupal?
..................333Interview script
..................335Join forces with others
.................336Module developer’s guide
...............336Introduction to Drupal modules
................336Creating modules - tutorials
............337Creating modules - a tutorial: Drupal 4.3.1
x
3 Aug 2007Drupal Handbook
..................337Getting Started
.............338Telling Drupal about your module
...........339Telling Drupal who can use your module
.............339Announce we have block content
...............340Generate content for a block
...........343Installing, enabling and testing the module
..........344Create a module configuration (settings) page
..........346Adding menu links and creating page content
..........348Letting Drupal know about the new function
...........349Adding a more link and showing all entries
...................349Conclusion
...........350Creating modules - a tutorial: Drupal 4.6/4.7
.................35001. Getting started
............35102. Telling Drupal about your module
...........35203. Telling Drupal who can use your module
.............35304. Declare we have block content
..............35405. Generate the block content
..........35706. Installing, enabling and testing the module
................358Test with large loads
.........36007. Create a module configuration (settings) page
...............36308. Generate a page content
..........36509. Letting Drupal know about the new function
..........36610. Adding a ’more’ link and showing all entries
...................366Conclusion
............367Creating modules - a tutorial: Drupal 5.x
.................36701. Getting started
............36802. Telling Drupal about your module
...........37003. Telling Drupal who can use your module
.............37104. Declare we have block content
..............37305. Generate the block content
..........37606. Installing, enabling and testing the module
.........37707. Create a module configuration (settings) page
.............377Create the configuration function
..............378Add the page to hook_menu
...............37908. Generate a page content
..........38109. Letting Drupal know about the new function
..........38210. Adding a ’more’ link and showing all entries
...................382Conclusion
.........383dummy template module with all hooks for drupal 5
..............427Creating new node types - a tutorial
..................42801. Getting started
...............42902. Name the new node type
................43003. Create an input form
..............43304. Validate the form submission
............43405. Create the node specific database table
..........43506. Save node-specific information to the database
............43607. Load the data for viewing and editing
xi
Drupal Handbook 3 Aug 2007
...............43708. Adjust forms for editing
..............43809. Different views of your data
................43910. Create an install file
...................440Conclusion
.................440Documenting your code
.................440Drupal Object Reference
.................440&$node - Node object
...............441Drupal’s caching mechanism
...........441How to create your own simple node type (5.x)
........452How to create your own simple node type (from story node)
.....461How to create your own simple node type (from story node) (Drupal 4.7)
.............472Find and replace template for node
.............474How to make a duplicate Book module
...................474Why Do It?
...................475How to Do it
.......475Preparing the Original Book Module to Work with a Duplicate
..........475Duplicating the book module into a new module
..............476Other things you may want to do
................476Javascript, jQuery and AJAX
................476Javascript in Drupal 4.7
...............476Drupal’s Javascript tools
.................477drupal.js functions
...........477Testing for appropriate Javascript support
................477AJAX data exchanges
.............478Working with CSS class names
.................478Element position
.................478Adding events
................478Collapsible Fieldsets
...................478What it is
..................478How to use it
.................479Example form
...................480Drupal 5
...........480Tutorial 1: Creating new Javascript widgets
.......483Tutorial 2: Using existing Javascript widgets: autocomplete
.............483Prebuilt autocomplete functions
...........484Building a custom autocomplete function
...........485Tutorial 3: Creating new widgets with AJAX
..............486AJAX solution components
.............486Example: click_info with AJAX
................4861. Marking up content
.................4872. The Javascript
................487Objects and methods
.................4893. The Handler
.................491More examples
............491Tutorial 4: Drupalizing external libraries
.................491Likely candidates
.............491Sample Drupalization: Jscalendar
xii
3 Aug 2007Drupal Handbook
...............492Step 1: analyze the library
.................492Step 2: PHP work
.................493Step 3: Javascript
.............494Step 4: Bugfixes and refinements
.............495Additional tools and approaches
................495Javascript in Drupal 5.0
................496Changes for 5.0 include
....................496F.A.Q.
................497Javascript page snippets
..................497Input Validator
.............497Make sidebar blocks collapseable.
...........498Two columns on pages with lists of nodes
...........499Valid XHTML Link Popups using jQuery
................499javascript utility modules
................500jQuery Hints and Snippets
............500HOWTO: Select Drupal Form Elements
............501HOWTO: Tell if a Checkbox is Checked
...................501Using jQuery
...............502History of jQuery in Drupal
...................502History
..........503HOWTO: Pass php variables to the javascript
..............504some simple jquery examples
.............507HOWTO: jQuery with Drupal 4.7
..............507HOWTO: Add a jQuery effect
.................508PostgreSQL for modules
............510Third party applications integration guide
.................510Session handler issues
.................511Sharing a user base
................513Theme engine integration
.........514Using the APIs available through contributed modules
.....................514Views
................514Actions and Workflows
...................514E-Commerce
....................514Location
..................515Organic Groups
..................515Writing .install files
.................515Install instructions
.................516Update instructions
...................516Simple usage
.................516Multi-part updates
................518UTF-8 update (4.6 to 4.7)
.................518Writing .schema files
..............518Drupal’s page serving mechanism
..............525Drupal’s node building mechanism
..............529Drupal menu system (Drupal 6.x)
................530Menu system overview
..............531Wildcard, ancestors and fitness
xiii
Drupal Handbook 3 Aug 2007
.....................531Fit
..................532Inheritance rules
...................533Access control
..............534Dynamic arguments replacement
.........537Menu item title and description callbacks, localization
............539How the system maintains menu order
................540Page handler include files
.............542Upgrading to the new menu system
...................542Cached part
.................543Non-cached part
..........545Drupal’s menu building mechanism (4.7x and 5.x)
...................548Hook menu
...................549menu.inc
....................549Reference
..............549Drupal database documentation
...............549Main content-related hooks
.............550Tables: layout and navigation (core)
................551Tables: localization (core)
.................552Tables: node (core)
................552Tables: node types (core)
.................553Tables: other (core)
...............554Tables: RSS aggregation (core)
.................555Tables: search (core)
.................555Tables: system (core)
................556Tables: taxonomy (core)
.................557Tables: tracking (core)
..................558Tables: user (core)
...........559’Status’ field values for nodes and comments
..................560Module how-to’s
.........560How to connect to multiple databases within Drupal
.....561How to make tablesorting work with multiple tables on the same page
............561How to rebuild node_comment_statistics
............562How to use watchdog() in your own code
...............563How to write a node module
...............563How to write automated tests
................563The basic class structure
..............564The DrupalTestCase features
..............566Implementing hook_simpletest
..................567Running tests
..............567Testing core modules and APIs
.............568Function testing vs. browser testing
................568Function-based tests
.................569Browser-based tests
....................572Tips
............572Viewing source during a browser test
............572How to write database independent code
.............573How to write efficient database JOINs
xiv
3 Aug 2007Drupal Handbook
..............574Howto: Update a module’s weight
................574Code to update weight
................574Module weights in use
..............575How to write themable modules
...............576Writing .info files (Drupal 5.x)
.................580Updating your modules
...............580Converting 5.x modules to 6.x
............580Overview of Drupal API changes in 6.x
..................581New menu system
...............581Major FormAPI improvements
..................581New Schema API
...............581New format for hook_install()
...............583New format for hook_uninstall()
..............584New format for hook_update_N()
.............586Arguments changed for url and l
...........587Variables can have names 128 characters long
..........587Taxonomy terms are associated with node revisions
............588format_plural accepts replacements
............588New drupal_alter() function for developers
............589hook_link_alter() parameters have changed
...........589hook_profile_alter() parameters have changed
............590hook_mail_alter() parameters have changed
................590$locale become $language
................590New hook_theme registry
..............591node/add is now menu generated
.............591New watchdog hook, logging and alerts
..............592Parameters of watchdog() changed
............593New hook_update_N naming convention
................594New syntax for .info files
...........595Core compatibility now specified in .info files
..............596New db_column_exists() method
.............596Changes to cache_set parameter order
.......596Cache set and get automatically (un)serialize complex data types
............597node_revision_list() now returns keyed array
.........597New image.inc function: image_scale_and_crop
...............597New user_mail_tokens() method
........597New ip_address() function when working behind proxies.
..................598{files} table changed
..........598file_check_upload() merged into file_save_upload()
.............599The {file_revisions} table is now {upload}
.........599drupal_add_css() supports automatic RTL CSS discovery
.........599Node previews and adding form fields to the node form
.............599Drupal 5.x to 6.x FormAPI changes
............600FormAPI now uses the $form_state variable.
.....601Parameters for form validation and submission functions have changed
..........602Parameters for hook_form_alter have changed
.....602hook_form_alter complimented by hook_form_$form-id_alter()
xv
Drupal Handbook 3 Aug 2007
.......603Submit handlers use $form_state rather than returning urls
$form['#submit'] and $form['#validate'] and $form['#process'] no longer
................604support custom parameters
...........605form_set_value parameters have changed
...........605#multistep is gone, use $form_state instead
...607Validation for specific form elements now uses the #element_validate property
................608$form['#base'] is gone
..............609$form['#pre_render'] is gone
.......609Form buttons can define custom #submit and #validate handlers
........610Validation handlers can pass information to submit handlers
................611AJAX with 6.x FormAPI
...............612Converting 4.7.x modules to 5.x
............612Overview of Drupal API changes in 5.x
....................613.info files
..............615Handling of links for hook_link
................617New hook_link_alter
617menu_primary_links, and menu_secondary_links now return structured links
.............618user_mail() is replaced by drupal_mail()
................618New hook_mail_alter
......619user_mail_wrapper changed to drupal_mail_wrapper
...............619Removed hook_settings
...............620New hook_profile_alter
................620message_na removed
................620New administration layout
..........622drupal_add_css - the proper way to add CSS
......622hook_view and hook_nodeapi$op = 'view' have changed
............623hook_nodeapi($op = ’alter’) has been added
........623Changes to hook_node_info and the node type system
................624New hook_node_type
..............625Changes to node type settings form
................626New db_table_exists
.......626New hook_node_operations, hook_user_operations
..........627Altered the behaviour of placeholders in t calls
........628drupal_get_form now takes a $form_id, not a $form
.........628Forms must be created in dedicated builder functions
.......629hook_forms optionally maps form_ids to builder functions
.630New drupal_execute function allows form data to be submitted programmatically
...........630module_exist is now module_exists
..............630format_plural @count change
..............631Vastly extended drupal_add_js
....................631Definition
...................631Description
...................631Parameters
...................632Return value
...............632Removed drupal_call_js
.632New drupal_add_feed and drupal_get_feeds replaces theme_add_link
............632theme'page' may omit standard blocks
xvi
3 Aug 2007Drupal Handbook
..............633New #disabled Form API property
..................633Changed cache API
...................633Uninstall hook
.................634Added jQuery to Drupal
..........634$_POST[op] deprecated in favor of $form_values[op]
..634Change menu item and node links to use Sentence capitalization instead of lowercase
.............634Major changes to node_access system
................635Changes to confirm_form()
.......636Changes to how #prefix and #suffix are rendered in form arrays
.......636Changes to how #options are represented in some form arrays
.............638$node->moderate no longer used by core
..............638Mixing old and new links styles
..............639Converting 4.7.x modules to 4.7.5
..............640Converting 4.7.x modules to 4.7.4
.............640Relying on specific, known form fields
......641Accessing $_POST and taking actions at the form definition stage
...............643What if I don’t want a token?
..............643Converting 4.6.x modules to 4.7.x
............643Overview of Drupal API changes in 4.7
...........644New handling of return values from callbacks
.................645node definition changes
..................646node_load() changes
..................647node_save() changes
..................647node_list() changes
............647Node titles now handled by node modules
.............648module_get_node_name deprecated
.................648format_name() renamed
.................649theme_table() change
.................649check_output() change
..................650XML-RPC changes
.................650Taxonomy API change
................651message_access() removed
..................651Unicode string API
...........651conf_url_rewrite() became custom_url_rewrite()
...............652node_delete(): moderately used
................652New order of node hooks
...........653hook_nodeapi(’settings’, ...) replaced by form api
...........653hook_nodeapi(’form x’, ...) replaced by form api
............654file_directory variables replaced by functions
..........654array2object replaced by native PHP type conversion
..........654user_load returns FALSE if a user cannot be loaded
...........654MySQL tables are now always UTF-8 encoded
.............655We no longer use the <base> element
............655hook_onload replaced by addLoadEvent()
..........656hook_search_item replaced by hook_search_page
..............656node_validate_title() was removed
...............656tablesort_pager() was removed
xvii
Drupal Handbook 3 Aug 2007
............656chx’s overview of menu system innards
.................658Revisions overhaul
........658Fields moved from node table to node_revisions table
............658Making your module revisions aware
......659How to get the revisions system work for custom node fields?
..............659Converting 4.6.x modules to 4.6.10
..................660Raw HTML forms
..661Converting legacy (4.5.4/4.6.2 and below) XML-RPC library to new implementation
..............662Converting 4.5.x modules to 4.6.x
...................662Block system
...................663Search system
...................663Module paths
..................663Database backend
...................663Theme system
.................664Watchdog messages
...................664Node markers
.........664Control over destination page after form processing
................664Confirmation messages
..................665Inter module calls
...................665Node queries
...................666Text output
..............666Converting 4.4.x modules to 4.5.x
...................666Menu system
...................668Path changes
...................668Node changes
..................669Filtering changes
................669Check_output() changes
...................670Filter hook
....................671Filter tips
...................671Other changes
..............672Converting 4.3.x modules to 4.4.x
...................672Menu system
...................673Theme system
...................674Node system
...................674Filter system
...................675Hook changes
...................676Emitting links
................677Status and error messages
..............677Converting 4.2.x modules to 4.3.x
...............678How to build up a _help hook
..............679How to convert a _system hook
.............680How to convert an _auth_help hook
..............682Converting 4.1.x modules to 4.2.x
..............683Converting 4.0.x modules to 4.1.x
..................683Required changes
..................684Optional changes
..............685Converting 3.0.x modules to 4.0.x
xviii
3 Aug 2007Drupal Handbook
..............686Drupal enhancement proposals (DEP)
..................686DEPS in progress
.............686Enabling story module on Drupal.org
.................687Events Improvement
..............687How this project is organized
..................687Who’s involved
................688Areas of improvement
.........688Improving And Simplifying Time Zone Support
................689Common Use Cases
.......690Design Considerations For Time Zone Libraries And UI
..............691Proposed Solutions For Core
...........691Timezones and Daylight Savings Time
....691Unified support for managing relationships between users and events
...............692The current state of affairs
..................692Our proposal
...............693Other work to consider
..........693IRC discussion between dww and hunmonk
................699Workflow Proposals
..........699Workflow for event creation, invite, and rsvp
....701CivicSpace: Workflow event creation, searching, invitation, and rsvp
.................703Can I party as well?
..703Next generation event management based on views and the content creation kit
...............703Use cases and motivation
..................703IRC Meetings
........7033/6/06 IRC Meeting: Re-Thinking Events in Drupal
.................704Meeting Notes
.................705Events DEP Stub
.................705Everything is a node
..................707hook_roles($user)
..............708Links exchange checking module
...............708Mapping API Generalization
..........709Multilanguage support in Drupal core: i18n2core
..................7101. Introduction
..................7102. Motivation
..................7103. Approach
..................7115. Excluding
...................711Patch list
................711Use cases: site set ups
..................712Relationship API
................713CiviCRM Relationships
...............713Hierachical Relationships
................713Network Relationships
..................713Relationship UI
...................714Finished DEPs
...................715Translator’s guide
.................715Translation processes
.................716Drupal core translations
xix
Drupal Handbook 3 Aug 2007
...........717Contributed Drupal module/theme translations
.............717Translation templates for Drupal core
...............718Programs to use for translation
.................718Issues using poEdit
.................718Plurals Solution #1
.................719Plurals Solution #2
.................719Plurals Solution #3
...........722Setting up XEmacs with po-mode on Windows
...............723Translated Drupal information
....................723Afrikaans
.........723Vir diegene wat betrokke wil raak by die vertaling:
...........723Om ’n fout met die vertaling te rapporteer:
........723Vir enige ander verwante redes waaroor jy wil kontak:
....................723Russian
....................724Spanish
.................724Translation guidelines
..............724Translation of contributed modules
..............724Distributing the translation effort
.................725Status of the translations
..............725Checking your translation status
..........725Make a single file from the loose .po files from CVS
................725Recycling old translations
...................727Troubleshooting
...............727Some strings do not translate
.............727Weird characters or question marks
....................729Bazaar-NG
....................729Installation
..........729Installation on Ubuntu & Debian based systems
................729Installation on Cygwin
.................730Installation on OS X
.................731Setting up Bazaar-NG
................731Hacking your local Drupal
.................732Database revisions
...................732WARNING
...........733Updating your Branch with Official Drupal Dev
...................733Getting Merged
...............734Getting a diff against core/head
..............734Getting Drupal Head via Bazaar-NG
...................735Drupal test suite
........736HOWTO: Write an installation profile for the Drupal installer
..............736Anatomy of an installation profile
...........7361. profilename_profile_modules() - REQUIRED
............7372. profilename_profile_details() - REQUIRED
.............7373. profilename_profile_final() - optional
.....739General strategy for setting options in your profile’s hook_profile_final()
.........739Common stuff you need to do: store settings/variables
............740Common tasks you need to do: enable blocks
xx
3 Aug 2007Drupal Handbook
........740Common stuff you need to do: configure roles/permissions
..............740Sample .profile file - gojoingo.profile
...............746E-Commerce Installation Profile
..........747HOWTO: Configure settings using drupal_execute
....................747Blocks
....................748Forums
....................748Menus
...................748Menu items
................748Taxonomy vocabularies
..................748Taxonomy terms
..................749Users and Roles
...................750Access control
...........750HOWTO: Create content using drupal_execute
..................751Add node type
.................751Configure node type
..................751Create content
................752Migrating from other software
..............752Migrating from Back-End.org CMS
..............753Migrating from CPG Dragonfly CMS
.................753Migrating the forums
................754Migrating everything else
................760Migrating from DCForum+
...............761dcforumintegration.module
...............768dcprofilesmigration.module
...........771user.module - hacked for password migration
..............773Migrating from ExpressionEngine
...................773Advantages:
..................773Disadvantages:
................773Migrating from ezPublish
...........774Move ezp database content to drupal database
...........778Parse ezxml (in perl, with LWP::UserAgent)
........780Get ezpublish user real names for drupal profile.module
.................781Migrating from Geeklog
...........781Migrating from Geeklog 1.4.1 to Durpal 5.x
.............783Migrating from Invision Power Board
..............784Step One: Export Invision Tables
........784Step Two: Import Invision Tables into Drupal Database
..........784Step Three: Moving the Data You Need To Drupal
....................785Finished
...............785Migrating from Joomla/Mambo
..................785Joomla! vs Drupal
..............785Joomla vs Drupal Terminology
..............786Migrating Joomla Content/Items
...............786Migrating Joomla Introtext
................786Migrating Joomla Forum
.....................786Editor
.....................787Tips
xxi
Drupal Handbook 3 Aug 2007
................787Migrating from LiveJournal
......787Import your LJ through an IFRAME held in a book page or similar
..............788Using provided Import Module
...............788Migrating from Movable Type
...................791mt2drupal
.............791Extract Movable Type content as xml
.............792Moving your MT styles and templates
......793Template for MT entry and comment export and Drupal import
.............796Parse xml into sql insert statements
..............800Insert content into Drupal nodes
..............800Setting terms for inserted nodes
................800Migrating from phpBB 2.0.*
...............801phpBB2 integration solution
...............801phpBB2 migration solution
..................801Data Migration
...................801Drupal 4.7.*
...................801Drupal 4.6.*
................801Post migration setup
.............801Questions? Problems? Comments?
..........802Drupal modules equivalent to phpBB2 features
.................802Thread splitting
.................802Private Forums
.................802Email notification
..................803Editing posts
................803Migrating from PHPNuke
..................803Migrating themes
..................803Migrating users
................803Migrating from PHPweblog
................805Migrating from PostNuke
.......805Configuring mod_rewrite in .htaccess for PN legacy URLs in
...................806To Drupal 4.5
.................806For moving users
.................806For moving stories
................807For moving comments
..............808For moving topics & categories
.............808Converting from Unicode to UTF-8
................808Reseting the database
...................808To Drupal 4.6
...................820To Drupal 4.7
...................822To Drupal 5
................823Migrating from Wordpress
.......824Using XML-RPC to combine Drupal and Wordpress on a site
...................824The Idea
..................824Starting Out
.................824Cautious Success
.................825Regroup and RPC
...................826It’s Alive!
xxii
3 Aug 2007Drupal Handbook
.................827Migrating from Xoops
.....................827Users
.................827Stories from News 1.4
.............828Forum posts from NewBB | CBB 2.x
...................829Cleaning up
....................829Statistics
....................829Sequences
....................829BBcode
...................829URL Aliases
...................830Search Index
...................830Annoyances
...................830Character Sets
..............830Search engine-friendly migration
..............832Migrating from Phorum to Drupal
xxiii
Drupal Handbook 3 Aug 2007
Developing for Drupal
The Drupal engine is open source. It is possible for each and every user to become a contributor.
The fact remains that most Drupal users, even those skilled in programming arts, have never
contributed to Drupal even though most of us had days where we thought to ourselves: "I wish
Drupal could do this or that ...". Through this section, we hope to make Drupal more accessible
to them.
The guide pages found here are collaborative, but not linked to particular Drupal versions.
Because of this, documentation can become out of date. To combat this, we are moving most
developer documentation into the Doxygen documentation that is versioned by CVS and
generated from the source code. Look there for up-to-date and version-specific information.
CVS log messages
Browse CVS repository
What about upgrading and backwards compatability? For more details read this overview of
the Drupal’s philosophy on backwards compatibility
1
Drupal Handbook 3 Aug 2007
Contributing to Development
Drupal is a collaborative, community-driven project. This means that the software and its
supporting features (documentation, the drupal.org website) are collaboratively produced by
users and developers all over the world.
There are several ways to contribute to Drupal:
Improve or enhance the software
Provide support and documentation for other users (e.g., by posting additions or updates to
the Drupal Handbook or answering requests on user forums or issues).
Provide financial support to Drupal development.
This section focuses on the first of these three.
Types of Contributions
There are two basic types of contributions you can make to Drupal’s code base: (a) "contributed"
modules or themes and (b) contributions to the drupal "core".
The easiest way to help is simply to find a bug or feature request that you want to fix,
modify a local copy of the code to fix that problem, create a patch file of your changes, and
then attach the patch to an issue for that bug or feature request
"Contributed modules" are the community-produced modules and themes available on the
Drupal site. To make a contribution, you need
to produce your contribution.
to apply for contributor privileges
As long as contributions meet some minimal criteria - they do what they claim to and have
some demonstrable benefit without unduly replicating already-available functionality, and
are coded with an eye towards secure code - they should be ok.
You should also read about maintaining a project on Drupal.org and consider joining forces
with others to avoid duplication of effort and share the load of your module.
If you have major enhancements you wish to contribute, doing so via a contributed module
is in many ways the easiest way to begin. Contributed code has a relatively low set of
requirements to meet. It also helps to trial the feature with the community, gain feedback
and help the code mature.
Your code contribution is welcome. Consider also being a responsible maintainer and
helping build a community around your module as it grows in use and popularity. This will
help reduce your load as well.
In contrast, changes to the Drupal core are made through a thorough consultative process to
ensure the overall integrity of the software.
2
3 Aug 2007Drupal Handbook
Changes to the Drupal core are generally of three types:
Bug fixes. These changes respond to identified problems in
the existing code.
New features. These changes are enhancements on what is already available.
Code maintenance. These changes are to improve the quality of the code or bring it up to
date with changes elsewhere in Drupal. This can include bringing code in line with
coding standards, improving efficiency (e.g., eliminating unneeded database queries),
introducing or improving in-line comments, and doing upgrades for compliance with a
new release version.
While you can create your own issues, you can also begin by simply taking on existing tasks
on the task list. See the page "Tips for contributing to the core" for advice on how to get
started as a core contributor.
Task list
The Drupal bug database contains many issues classified as "bite-sized" tasks -- tasks that are
well-defined and self-contained, and thus suitable for a volunteer looking to get involved with
the project. You don’t need broad or detailed knowledge of Drupal’s design to take on one of
these, just a pretty good idea of how things generally work, and familiarity with the coding
guidelines. Each task is something a volunteer could pick off in a spare evening or two.
If you start one of these, please update the task and assign it to yourself, so no one else
duplicates your effort. Once the task is complete, you can attach a patch that includes your
changes into the issue, and set the status to "patch (code needs review)".
Bug reports
Your bug reports play an essential role in making Drupal reliable. If you find a bug, please
follow the submission guidelines in this handbook. If you can, it is also helpful to provide a
patch that fixes your bug. If you can’t provide a patch, hopefully someone else will be able to fix
the bug.
Bug reports can be posted in connection with any project hosted on drupal.org. You can submit
a new bug via the submit issue form. Provide a sensible title for the bug, and choose the project
you think you have found the bug in. After previewing the submission, you will need to choose
a related component and you will be able to provide more details about the bug, including the
description of the problem itself. Please include any error messages you received and a detailed
description of what you were doing at the time.
Note that you DO have to be a logged in member of drupal.org to submit bugs.
Bugs are fixed in Drupal almost every day, often many bugs are fixed in a day. Therfore it is
important that you are using the latest version of Drupal and that your bug still hapens in that
version.
3
Drupal Handbook 3 Aug 2007
It is frequently helpful to include the PHP, database and webserver version information.
More detailed advice on submitting high quality bugs and getting them fixed quickly is
available in this handbook. Read the next pages for more details.
How to report bugs effectively
Summary
The first aim of a bug report is to let the programmer see the failure with their own eyes. If
you can’t be with them to make it fail in front of them, give them detailed instructions so
that they can make it fail for themselves.
In case the first aim doesn’t succeed, and the programmer can’t see it failing themselves, the
second aim of a bug report is to describe what went wrong. Describe everything in detail.
State what you saw, and also state what you expected to see. Write down the error
messages, especially if they have numbers in.
When your computer does something unexpected, freeze. Do nothing until you’re calm, and
don’t do anything that you think might be dangerous.
By all means try to diagnose the fault yourself if you think you can, but if you do, you
should still report the symptoms as well.
Be ready to provide extra information if the programmer needs it. If they didn’t need it,
they wouldn’t be asking for it. They aren’t being deliberately awkward. Have version
numbers at your fingertips, because they will probably be needed.
Write clearly. Say what you mean, and make sure it can’t be misinterpreted.
Above all, be precise. Programmers like precision.
Introduction
Anybody who has written software for public use will probably have received at least one bad
bug report. Reports that say nothing ("It doesn’t work!"); reports that make no sense; reports that
don’t give enough information; reports that give wrong information. Reports of problems that
turn out to be user error; reports of problems that turn out to be the fault of somebody else’s
program; reports of problems that turn out to be network failures.
There’s a reason why technical support is seen as a horrible job to be in, and that reason is bad
bug reports. However, not all bug reports are unpleasant: I maintain free software, when I’m not
earning my living, and sometimes I receive wonderfully clear, helpful, informative bug reports.
In this essay I’ll try to state clearly what makes a good bug report. Ideally I would like
everybody in the world to read this essay before reporting any bugs to anybody. Certainly I
would like everybody who reports bugs to me to have read it.
In a nutshell, the aim of a bug report is to enable the programmer to see the program failing in
front of them. You can either show them in person, or give them careful and detailed
instructions on how to make it fail. If they can make it fail, they will try to gather extra
information until they know the cause. If they can’t make it fail, they will have to ask you to
gather that information for them.
4
3 Aug 2007Drupal Handbook
In bug reports, try to make very clear what are actual facts ("I was at the computer and this
happened") and what are speculations ("I think the problem might be this"). Leave out
speculations if you want to, but don’t leave out facts.
When you report a bug, you are doing so because you want the bug fixed. There is no point in
swearing at the programmer or being deliberately unhelpful: it may be their fault and your
problem, and you might be right to be angry with them, but the bug will get fixed faster if you
help them by supplying all the information they need. Remember also that if the program is free,
then the author is providing it out of kindness, so if too many people are rude to them then they
may stop feeling kind.
"It doesn’t work."
Give the programmer some credit for basic intelligence: if the program really didn’t work at all,
they would probably have noticed. Since they haven’t noticed, it must be working for them.
Therefore, either you are doing something differently from them, or your environment is
different from theirs. They need information; providing this information is the purpose of a bug
report. More information is almost always better than less.
Many programs, particularly free ones, publish their list of known bugs. If you can find a list of
known bugs, it’s worth reading it to see if the bug you’ve just found is already known or not. If
it’s already known, it probably isn’t worth reporting again, but if you think you have more
information than the report in the bug list, you might want to contact the programmer anyway.
They might be able to fix the bug more easily if you can give them information they didn’t
already have.
This essay is full of guidelines. None of them is an absolute rule. Particular programmers have
particular ways they like bugs to be reported. If the program comes with its own set of
bug-reporting guidelines, read them. If the guidelines that come with the program contradict the
guidelines in this essay, follow the ones that come with the program!
If you are not reporting a bug but just asking for help using the program, you should state
where you have already looked for the answer to your question. ("I looked in chapter 4 and
section 5.2 but couldn’t find anything that told me if this is possible.") This will let the
programmer know where people will expect to find the answer, so they can make the
documentation easier to use.
"Show me"
One of the very best ways you can report a bug is by showing it to the programmer. Stand them
in front of your computer, fire up their software, and demonstrate the thing that goes wrong. Let
them watch you start the machine, watch you run the software, watch how you interact with the
software, and watch what the software does in response to your inputs.
They know that software like the back of their hand. They know which parts they trust, and they
know which parts are likely to have faults. They know intuitively what to watch for. By the time
the software does something obviously wrong, they may well have already noticed something
subtly wrong earlier which might give them a clue. They can observe everything the computer
does during the test run, and they can pick out the important bits for themselves.
5
Drupal Handbook 3 Aug 2007
This may not be enough. They may decide they need more information, and ask you to show
them the same thing again. They may ask you to talk them through the procedure, so that they
can reproduce the bug for themselves as many times as they want. They might try varying the
procedure a few times, to see whether the problem occurs in only one case or in a family of
related cases. If you’re unlucky, they may need to sit down for a couple of hours with a set of
development tools and really start investigating. But the most important thing is to have the
programmer looking at the computer when it goes wrong. Once they can see the problem
happening, they can usually take it from there and start trying to fix it.
"Show me how to show myself"
This is the era of the Internet. This is the era of worldwide communication. This is the era in
which I can send my software to somebody in Russia at the touch of a button, and he can send
me comments about it just as easily. But if he has a problem with my program, he can’t have me
standing in front of it while it fails. "Show me" is good when you can, but often you can’t.
If you have to report a bug to a programmer who can’t be present in person, the aim of the
exercise is to enable them to reproduce the problem. You want the programmer to run their own
copy of the program, do the same things to it, and make it fail in the same way. When they can
see the problem happening in front of their eyes, then they can deal with it.
So tell them exactly what you did. If it’s a graphical program, tell them which buttons you
pressed and what order you pressed them in. If it’s a program you run by typing a command,
show them precisely what command you typed. Wherever possible, you should provide a
verbatim transcript of the session, showing what commands you typed and what the computer
output in response.
Give the programmer all the input you can think of. If the program reads from a file, you will
probably need to send a copy of the file. If the program talks to another computer over a
network, you probably can’t send a copy of that computer, but you can at least say what kind of
computer it is, and (if you can) what software is running on it.
"Works for me, so what goes wrong?"
If you give the programmer a long list of inputs and actions, and they fire up their own copy of
the program and nothing goes wrong, then you haven’t given them enough information.
Possibly the fault doesn’t show up on every computer; your system and theirs may differ in
some way. Possibly you have misunderstood what the program is supposed to do, and you are
both looking at exactly the same display but you think it’s wrong and they know it’s right.
So also describe what happened. Tell them exactly what you saw. Tell them why you think what
you saw is wrong; better still, tell them exactly what you expected to see. If you say "and then it
went wrong", you have left out some very important information.
If you saw error messages then tell the programmer, carefully and precisely, what they were.
They are important! At this stage, the programmer is not trying to fix the problem: they’re just
trying to find it. They need to know what has gone wrong, and those error messages are the
computer’s best effort to tell you that. Write the errors down if you have no other easy way to
remember them, but it’s not worth reporting that the program generated an error unless you can
also report what the error message was.
6
3 Aug 2007Drupal Handbook
In particular, if the error message has numbers in it, do let the programmer have those numbers.
Just because you can’t see any meaning in them doesn’t mean there isn’t any. Numbers contain
all kinds of information that can be read by programmers, and they are likely to contain vital
clues. Numbers in error messages are there because the computer is too confused to report the
error in words, but is doing the best it can to get the important information to you somehow.
At this stage, the programmer is effectively doing detective work. They don’t know what’s
happened, and they can’t get close enough to watch it happening for themselves, so they are
searching for clues that might give it away. Error messages, incomprehensible strings of
numbers, and even unexplained delays are all just as important as fingerprints at the scene of a
crime. Keep them!
If you are using Unix, the program may have produced a core dump. Core dumps are a
particularly good source of clues, so don’t throw them away. On the other hand, most
programmers don’t like to receive huge core files by e-mail without warning, so ask before
mailing one to anybody. Also, be aware that the core file contains a record of the complete state
of the program: any "secrets" involved (maybe the program was handling a personal message, or
dealing with confidential data) may be contained in the core file.
"So then, I tried..."
There are a lot of things you might do when an error or bug comes up. Many of them make the
problem worse. A friend of mine at school deleted all her Word documents by mistake, and
before calling in any expert help, she tried reinstalling Word, and then she tried running Defrag.
Neither of these helped recover her files, and between them they scrambled her disk to the
extent that no Undelete program in the world would have been able to recover anything. If she’d
only left it alone, she might have had a chance.
Users like this are like a mongoose backed into a corner: with its back to the wall and seeing
certain death staring it in the face, it attacks frantically, because doing something has to be better
than doing nothing. This is not well adapted to the type of problems computers produce.
Instead of being a mongoose, be an antelope. When an antelope is confronted with something
unexpected or frightening, it freezes. It stays absolutely still and tries not to attract any attention,
while it stops and thinks and works out the best thing to do. (If antelopes had a technical
support line, it would be telephoning it at this point.) Then, once it has decided what the safest
thing to do is, it does it.
When something goes wrong, immediately stop doing anything. Don’t touch any buttons at all.
Look at the screen and notice everything out of the ordinary, and remember it or write it down.
Then perhaps start cautiously pressing "OK" or "Cancel", whichever seems safest. Try to develop
a reflex reaction - if a computer does anything unexpected, freeze.
If you manage to get out of the problem, whether by closing down the affected program or by
rebooting the computer, a good thing to do is to try to make it happen again. Programmers like
problems that they can reproduce more than once. Happy programmers fix bugs faster and
more efficiently.
7
Drupal Handbook 3 Aug 2007
"I think the tachyon modulation must be wrongly polarised."
It isn’t only non-programmers who produce bad bug reports. Some of the worst bug reports I’ve
ever seen come from programmers, and even from good programmers.
I worked with another programmer once, who kept finding bugs in his own code and trying to
fix them. Every so often he’d hit a bug he couldn’t solve, and he’d call me over to help. "What’s
gone wrong?" I’d ask. He would reply by telling me his current opinion of what needed to be
fixed.
This worked fine when his current opinion was right. It meant he’d already done half the work
and we were able to finish the job together. It was efficient and useful.
But quite often he was wrong. We would work for some time trying to figure out why some
particular part of the program was producing incorrect data, and eventually we would discover
that it wasn’t, that we’d been investigating a perfectly good piece of code for half an hour, and
that the actual problem was somewhere else.
I’m sure he wouldn’t do that to a doctor. "Doctor, I need a prescription for Hydroyoyodyne."
People know not to say that to a doctor: you describe the symptoms, the actual discomforts and
aches and pains and rashes and fevers, and you let the doctor do the diagnosis of what the
problem is and what to do about it. Otherwise the doctor dismisses you as a hypochondriac or
crackpot, and quite rightly so.
It’s the same with programmers. Providing your own diagnosis might be helpful sometimes, but
always state the symptoms. The diagnosis is an optional extra, and not an alternative to giving
the symptoms. Equally, sending a modification to the code to fix the problem is a useful addition
to a bug report but not an adequate substitute for one.
If a programmer asks you for extra information, don’t make it up! Somebody reported a bug to
me once, and I asked him to try a command that I knew wouldn’t work. The reason I asked him
to try it was that I wanted to know which of two different error messages it would give.
Knowing which error message came back would give a vital clue. But he didn’t actually try it -
he just mailed me back and said "No, that won’t work". It took me some time to persuade him to
try it for real.
Using your intelligence to help the programmer is fine. Even if your deductions are wrong, the
programmer should be grateful that you at least tried to make their life easier. But report the
symptoms as well, or you may well make their life much more difficult instead.
"That’s funny, it did it a moment ago."
Say "intermittent fault" to any programmer and watch their face fall. The easy problems are the
ones where performing a simple sequence of actions will cause the failure to occur. The
programmer can then repeat those actions under closely observed test conditions and watch
what happens in great detail. Too many problems simply don’t work that way: there will be
programs that fail once a week, or fail once in a blue moon, or never fail when you try them in
front of the programmer but always fail when you have a deadline coming up.
8
3 Aug 2007Drupal Handbook
Most intermittent faults are not truly intermittent. Most of them have some logic somewhere.
Some might occur when the machine is running out of memory, some might occur when another
program tries to modify a critical file at the wrong moment, and some might occur only in the
first half of every hour! (I’ve actually seen one of these.)
Also, if you can reproduce the bug but the programmer can’t, it could very well be that their
computer and your computer are different in some way and this difference is causing the
problem. I had a program once whose window curled up into a little ball in the top left corner of
the screen, and sat there and sulked. But it only did it on 800x600 screens; it was fine on my
1024x768 monitor.
The programmer will want to know anything you can find out about the problem. Try it on
another machine, perhaps. Try it twice or three times and see how often it fails. If it goes wrong
when you’re doing serious work but not when you’re trying to demonstrate it, it might be long
running times or large files that make it fall over. Try to remember as much detail as you can
about what you were doing to it when it did fall over, and if you see any patterns, mention
them. Anything you can provide has to be some help. Even if it’s only probabilistic (such as "it
tends to crash more often when Emacs is running"), it might not provide direct clues to the cause
of the problem, but it might help the programmer reproduce it.
Most importantly, the programmer will want to be sure of whether they’re dealing with a true
intermittent fault or a machine-specific fault. They will want to know lots of details about your
computer, so they can work out how it differs from theirs. A lot of these details will depend on
the particular program, but one thing you should definitely be ready to provide is version
numbers. The version number of the program itself, and the version number of the operating
system, and probably the version numbers of any other programs that are involved in the
problem.
"So I loaded the disk on to my Windows . . ."
Writing clearly is essential in a bug report. If the programmer can’t tell what you meant, you
might as well not have said anything.
I get bug reports from all around the world. Many of them are from non-native English
speakers, and a lot of those apologise for their poor English. In general, the bug reports with
apologies for their poor English are actually very clear and useful. All the most unclear reports
come from native English speakers who assume that I will understand them even if they don’t
make any effort to be clear or precise.
Be specific. If you can do the same thing two different ways, state which one you used. "I
selected Load" might mean "I clicked on Load" or "I pressed Alt-L". Say which you did.
Sometimes it matters.
Be verbose. Give more information rather than less. If you say too much, the programmer
can ignore some of it. If you say too little, they have to come back and ask more questions.
One bug report I received was a single sentence; every time I asked for more information,
the reporter would reply with another single sentence. It took me several weeks to get a
useful amount of information, because it turned up one short sentence at a time.
Be careful of pronouns. Don’t use words like "it", or references like "the window", when it’s
9
Drupal Handbook 3 Aug 2007
unclear what they mean. Consider this: "I started FooApp. It put up a warning window. I
tried to close it and it crashed." It isn’t clear what the user tried to close. Did they try to close the
warning window, or the whole of FooApp? It makes a difference. Instead, you could say "I
started FooApp, which put up a warning window. I tried to close the warning window, and
FooApp crashed." This is longer and more repetitive, but also clearer and less easy to
misunderstand.
Read what you wrote. Read the report back to yourself, and see if you think it’s clear. If you
have listed a sequence of actions which should produce the failure, try following them yourself,
to see if you missed a step.
HOWTO: Help with QA - OR - What to do when you find a bug
This set of pages is intented for two different types of users who need to get an issue resolved. It
helps users understand the Drupal issue (bug) tracking system.
You want to give back to drupal without programming
The first is the situation where you are not a programmer, but you want to help with Drupal in
some way. That’s great! Ideally every user of Drupal would provide some assistance, though not
all are able to write PHP. This guide can help you to give back to the community and help
others. While there are many ways to help Drupal, this is one very important and often
neglected way.
In this case, the set of "Contributor Links" available in your profile page are very handy in
providing the bug bingo system which will take you to a random bug in the issue queue. If you
have 10 extra minutes, spend some time clicking on "bug bingo" and see if you can improve the
issue reports that you find so they are more clear.
You’ve been bitten by a bug and want it fixed
Eventually it happens to everyone - a bug "bites" you. That is to say, you find a problem with the
way that Drupal works. This can be very frustrating. You want your bug fixed and fast, but
either you aren’t a programmer or you aren’t savvy enough to write the code to fix this
particular bug. You need help from someone else to get your bug fixed. How can you do that?
Ultimate Goal: Helping the Developers
Whichever reason you have for writing bugs or working on the issue queue your goal is simple:
help the developers. Realistically there is a relative scarcity of people who can write good code.
If you help make good issue reports and improve the current issues by following the advice laid
out in this set of pages, you will not only make the developer’s job easier you will also learn a lot
about how Drupal works and will grow in your knowledge of development and coding
practices. Working on issues is a great way to work your way into becoming a Drupal
developer. After you have improved a few issues and started to provide minor patches you can
then move onto more major changes. Proper use of the issue queue brings you respect from
other users and developers who will then go out of their way to help you.
10
3 Aug 2007Drupal Handbook
Getting a Bug Fixed Sooner
Let’s say that you found a bug that affects you, you searched for it and found that it’s already
submitted. Now you want to ensure that it gets fixed. Here are a couple things you can do to
improve the likelihood of the bug getting attention from a developer.
Improving Bug Reports
Many bug reports don’t get attention simply because the quality of the report is low making it
harder to understand and work on the bug. It will help the developer tremendously if you can
take these bugs and improve them so that they have enough information. If necessary, ask
questions of the original reporter. Try to repeat the problem yourself and note and differences or
similarities in the results and the system configurations. If a developer sees a bug with a clear
report that has been repeated then it is much easier for them to fix it.
In addition validating the description, make sure that the status, version, priority, and other
values are set correctly.
Increase Visibility of the Issue
Once you have already ensured that the issue is well documented, repeatable, and properly
categorized, it’s important to make sure that people are aware of the issue. Many times an issue
only affects a subset of the population so a developer who might be able to fix your bug might
not be aware of it. Several easy ways to help increase the visibility of a particular bug is the write
about it in your blog, join #drupal-support on IRC and ask around about the bug, add the bug to
your email signature on the account that you use for the mailing lists or to your Drupal.org
signature and then be sure to provide lots of help in the forum and the mailing lists so your
signature is visible.
How not to increase visibility: send private emails to the module owner. If they are the owner
they’ve probably already seen the bug via email from the issue tracker so another email is just a
waste of time to them.
Providing a Patch
Many times the bug report will contain a description of what to change or will have the text of a
patch pasted into the bug. While it may seem trivial, a patch makes the maintainer’s job easier
than just describing the change or pasting the patch into the comments of the bug.
If you can write the necessary code - by all means, create a patch. Again, it makes the
maintainer’s life simpler if someone creates a patch and all
Improving a Patch
Many times a patch exists but does not conform to Drupal’s coding standards or lacks in some
other ways. You can help to review the patch and ensure that it conforms to the coding
standards. This is relatively advanced for someone who doesn’t know how to program PHP, but
it isn’t terribly difficult and helps you understand how Drupal works.
11
Drupal Handbook 3 Aug 2007
Hire Someone or Providing a Bounty
Many times a bug just needs a bounty. Putting out some money on a bug (or getting others to
join together to create a big bounty) can result in the quick resolution. Sometimes you just need a
solution now. In that case, take a look at the Support and Professional Services page in the
handbook to try and find someone who might be interested. You can also read the HOWTO:
Hire a Drupal site developer to help you in finding the right person.
Ineffective Methods of Getting a Bug Fixed
Marking a "closed" or "won’t fix" bug as active again without providing a convincing
argument as to why it should be opened again. It’s better off to provide the convincing
argument and let someone else reopen the bug
HOWTO: Make A GOOD issue report
Drupal makes use of the Drupal Project Module to keep track of issues that are found in Drupal
Core software, Modules, Themes, Theme Engines, and Translations. This system tracks several
pieces of information about each issue but also leaves a large empty box for you to enter your
own bug report. If you want your bug to get fixed, it is extremely important that you take the
time to enter the proper information into these fields.
You should also see How to troubleshoot Drupal for self-help steps to do BEFORE raising an
issue.
Project Information
Make sure you choose the correct version and make a decent guess as to the right Project and
Component. Sometimes the correct value can be unclear, but if you make an effort to get it right
that helps.
Issue Information
Try to determine the Category, Priority, Assigned, and Status values.
Category: Bug Reports are for situations where the software does not work as was intended by
the programmer. Feature Requests are for situations where the software works as designed, but
the design can be improved. Tasks are for something that just needs to get done [frankly their
use seems a little unclear]. Support Requests are for situations where you wish to ask about a
specific component. Support Requests can seem redundant with the forums, IRC, and mailing
lists, but these are a good way to ask a question at a targeted audience (the module maintainer).
Note that new features are generally only accepted for the CVS version of code unless they are
very important. Even if it seems important to you, it has to be important for a large number of
sites to be worth creating a fix for a currently released version of Drupal. You cannot get around
this rule by simply labeling a feature request as a bug request. If you want to get a feature
applied to a released version of Drupal you need to make the case that it is important, affects a
large number of sites, and ensure that the code changed is stable.
12
3 Aug 2007Drupal Handbook
Priority: the priority field is an easy one to abuse. Generally, Critical should be reserved for the
most problematic and important issues. Abuse of the Critical field will likely get your issue
ignored by a developer and that’s the last thing you want. Normal and Minor priorities are both
fine to use. More detail in Priority Levels of Issues.
Assigned: the Assigned field helps keep track of the person working on a particular issue. If you
are working on the issue - e.g. you are writing a patch to fix it - then you should set the issue as
assigned to you.
Status: Status is one of the most often overlooked fields. Many developers have filters set to look
for issues in certain statuses, so changing this field inappropriately can lead to your issue getting
ignored.
Issue Details
Title: you want your title to be descriptive and concise. Compare these two titles:
SITE BROKEN YOU MUST FIX NOW!!!111!!
and
Admin-Modules Page Blank After Installing Module Foo
The first title doesn’t explain the problem and tries to impart a sense of priority. The priority
should stay in the priority field. The title is for describing your problem, and while "SITE
BROKEN" may be what you think of your site it doesn’t help a developer when they see three
bug reports with different problems all with the title "SITE BROKEN". The second title succinctly
describes the specific problem with the site and a possible cause. This makes it easy for the
developer to keep track of the bugs in their queue. If you look at many of the issue queues you
will see dozens or hundreds of issues. Having unique titles that are descriptive makes a specific
issue stand out as easier to work on among the rest of the issues.
Also note that the project issue titles do not behave like a forum thread. Changing the title will
change the title of the whole issue, not just your followup. This is useful for renaming a vague issue
into a more descriptive one but it makes things worse if it is used to title issues like "I’m getting
this too".
Description: The Description field is wide open which leaves you a lot of space to say a lot or a
little. The Description takes the title one step further. Generally speaking, the majority of the
time spent fixing an issue is spent on understanding the problem and finding the cause of that
issue. The goal of the description is to state the exact set of conditions that cause a problem and
the resultant undesirable state of the system so that the developer spends as little time as
possible understanding your situation. Your issue should reflect the
repeatability of the problem - whether it is easy to repeat or happens randomly
steps to repeat - what you think caused the problem, ideally these steps should be repeated
until they are as simple as possible and still cause the problem
desired outcome of the steps - that is, what you WANT to have happen
actual outcome of your steps - this is the essence of your problem
13
Drupal Handbook 3 Aug 2007
Compare these two bug reports:
MY PAGES ARE BLANK!!! I AM ABOUT TO DELETE DRUPAL FROM MY SYSTEM!!!
and
Repeatable: Always
Steps to repeat:
1. Download Module Foo
2. Uncompress foo-4.7.0-tar.gz into modules folder
3. Visit admin/modules page in site
Expected Results:
User sees the modules page and can enable the module Foo
Actual Results:
Page is completely blank.  Checking in the Apache Error Log showed this
error:
Fatal error: Allowed memory size of 8388608 bytes exhausted tried to
allocate 418591 bytes in /path/to/drupal/modules/foo/foo.module on
line 42
The first bug report is relatively useless because it forces the developer to waste their time
asking questions and guessing at the possible problem. The second one communicates the
problem precisely and concisely. The user has described a specific set of steps that they took, the
have stated that it is repeatable in their tests, and in addition to the desired and actual results
they provided an exact error message from their system. This makes the developer’s job
relatively easy to try and find the problem.
HOWTO: Submit core issues
Thanks, saw your message, however I could not find where to submit an issue for the core
’Drupal’ Project There is no Project in the global navigation, under Downloads, the Tile of
the page is Projects, but the core project is not there, nor the core themes.
I had difficulty with it too, in the beginning. Here are the instructions:
1. In the right menu, select ’Create Content’. Then Select ’Issue. You get the ’Submit issue’
screen.
2. Fill the project field. Examples - If you are trying to submit usability issues for the garland
theme, select ’Drupal’ (the second item under the ’Drupal Project’ category) and click ’Next’.