Reporting Bugs and Making Feature Requests for YUI Components

By Eric Miraglia
Yahoo! Inc.
December 1, 2006

One of the most important and valuable contributions you can make to the YUI Library is by filing clear, detailed problem reports when YUI components do not behave as expected. Another crucial contribution involves providing rich feedback to YUI's developers about what features you'd like to see added to the library. Please follow the guidelines below in filing such reports to ensure that they are as complete and productive as possible.

Reporting Bugs

Bug reports are useful documents when they are accurate, unique, specific, and complete. To ensure that your bug reports meet these criteria, please take the following measures in preparing your bug submission:

1. Seek the simplest use case in which the bug can be reproduced: Unexpected behaviors frequently arise when complex implementations are built around existing components. Before filing a bug, try to reproduce the bug in the simplest possible use case, removing as much implementation code as you can. If the unexpected behavior disappears when the implementation is simplified, try to discern the precise implementation characteristic that triggers the behavior. Verify that the bug stems from a problem in the library rather than a problem in the implementation.
2. Verify that the bug has not already been filed: Review the current bug list on Sourceforge to determine whether someone has already reported the issue you're experiencing. If the bug has already been reported, you may wish to add a note to the existing report to help clarify the issue. Don't file a new bug if the issue has already been reported.
3. Test the bug in as many browsers as you can: At Yahoo!, we use a Graded Browser Support scheme to determine which browsers we will actively test against (A-Grade). While you may not have access to all A-Grade browsers in your test environment, test your bug in as many A-Grade browsers as you can and include your findings in your writeup.
4. Include source code for reproducing the bug: If possible, post the use case for the bug to a server so that a YUI developer can quickly evaluate the bug you're reporting. If you don't have access to an externally available server, include the use case as an attachment to the bug report or inline in the bug's "Detailed Description" field.
5. File a bug report on Sourceforge, filling out all applicable fields: Use the Sourceforge bug tracker to file your bug. Fill out each field in the bug report carefully:
• Log in to Sourceforge: Filing reports while logged in allows the system to update you automatically as the YUI team investigates your issue.
• Category: The specific YUI component to which the bug applies (e.g. "Container - Dialog").
• Group: The version of the YUI library in which the bug appears. Refer to the README file for the component you are using to determine the version number.
• Summary: A short but specific description of the issue (e.g., "TreeView Control 0.12.0 expand() method fails in Opera 9.01").
• Detailed description: Provide as much detail here as you can about the issue and the implementation characteristics that trigger the bug. (If you're not able to provide a URL for a reproduction case or a file attachment, be sure to paste in your reproduction code in this space.)
• File upload:In the event that you're not able to post a reproduction case to a server, please use the file attachment feature to provide a self-contained zip archive containing all necessary files (including your YUI build files) for reproducing the bug. In your detailed description, explain which file to load and what steps to follow in reproducing the issue.

Making Feature Requests

Feature requests are an important avenue for the YUI community to provide feedback to the development team about what to prioritize for future releases. Many useful enhancements to YUI have already been made as a direct result of community feedback. Please follow the following guidelines in preparing and submitting feature requests for YUI:

1. Verify that this feature has not already been requested: Review current feature requests on the Sourceforge list to see if someone has already made the request you're contemplating. If so, feel free to amplify the existing request with additional ideas or details, but refrain from filing a duplicate request.
2. Decide whether this is something that belongs in the core library: Remember that any feature added to the core library adds weight and complexity every time that component is used. Ask yourself the following question: Is this feature, on balance, so important that it's worth adding that weight and complexity to the core package? (If the answer is no, probably the feature belongs in an implementation or extension rather than as part of YUI itself. Creating an implementation/extension and sharing it with the community via YDN-JavaScript might be the best solution in that case.)
3. Describe the feature fully: Be complete, specific, and reflective in describing the feature you'd like to see added. Try to frame it in such a way that it will be as simple, useful, and powerful as possible.
4. File a feature request on Sourceforge, filling out all applicable fields: Use the Sourceforge feature-request tracker to file your feature request. Fill out each field in the bug report carefully:
• Log in to Sourceforge: Making feature requests while logged in will allow the system to update you automatically as the YUI team evaluates and responds to your request.
• Category: The specific YUI component to which the request most directly applies.
• Group: Not applicable; you can ignore this field.
• Summary: A short but specific description of the suggestion (e.g., "Add built-in XHR sourcing of content for Panel Control").
• Detailed description: Try to make the argument as clearly as possible that this feature belongs in the core library and that it will be of interest and use to a broad cross-section of implementers.
• File upload: Use the file attachment feature to provide any assets that might be of use in evaluating your request — visual mockups, working prototypes, etc. (Such assets are strictly optional; a feature request can be full and complete without them.)

Acting on Bug Reports and Feature Requests

The YUI development team works hard to ensure that all complete bug reports and feature requests are addressed appropriately. Bugs identified as valid are usually addressed within a single release cycle, and issues deemed extremely critical may warrant an interim release or patch. Feature requests are factored into the YUI roadmap planning process. While it is the job of library developers to be parsimonious in adding weight and comlexity to the library, features that have demonstrable support from the community are more likely to earn a place on the YUI development roadmap.

You can track all your issues on Sourceforge to monitor their progress.

Support & Community

The YUI Library and related topics are discussed on the on the ydn-javascript mailing list.

In addition, please visit the YUIBlog for updates and articles about the YUI Library written by the library's developers.