Reporting Defects and Making Enhancement Requests for YUI Components

By Eric Miraglia, georgiann puckett
Yahoo! Inc.
January 16, 2009

Discovering, isolating, and documenting errors is one of the most valuable things you can do for a software project. Suggesting compelling additions to the API or feature set is also a generous and useful thing to do. YUI welcomes this kind of support from everyone in the community.

If you wish to file a defect report or a feature request, we ask that you follow the guidelines below.

Defect Reports

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

1. Seek the simplest use case in which the defect can be reproduced: Bug reports should include as little code as possible while still illustrating the unexpected behavior. Taking the time to reproduce the bug in the simplest possible use case will also help confirm if the issue is specific to the YUI library or the implementation.
2. Verify that the defect has not already been filed: Expanding an existing report is always better than filing a new report for the same issue.
3. Test the bug in as many browsers as you can: Test your bug in as many A-Grade browsers as you can and include your findings in your report.
4. Include source code for reproducing the defect: If possible, post the use case for the defect to a server so that a YUI developer can quickly evaluate the issue you're reporting. If you don't have access to an externally available server, include the use case as an attachment to the defect report or inline in the defect's Description field.
5. File a bug report on YUILibrary.com, filling out all applicable fields: Use the YUILibrary.com tracker to file your bug. You must be a registered user on YUILibrary.com to file a defect report. If you are not already registered, please sign up for an account. Otherwise, simply log into YUILibrary.com, select New Ticket from the Project Page, then complete each field in the defect report carefully:
• Summary: A short but specific description of the issue (e.g., "TreeView Control 2.6.0 expand() method fails in Opera 9.01").
• 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.)
• Type: You can specify that this is a bug report by selecting defect from the popup in the Type field.
• Component: The specific YUI component to which the bug applies (e.g. "Editor").
• Observed in Version: The version of the YUI library in which the defect appears. Refer to the README file for the component you are using to determine the version number.
• Browser: Please indicate a browser can you can readily reproduce the defect with in this field. If the issue occurs in multiple browsers, please include all browser names and versions, as well as the OS name and version information as part of the Description.
• 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.

Please be sure that you have provided all information above, including sample code to reproduce the problem, when filing your defect reports. If your issue cannot be immediately reproduced by the developer, it will be returned to you for more information.

Making Enhancement Requests

Enhancement requests are an important means for the YUI community to propose additions to the library as well as influence the task prioritization for future releases. Follow these guidelines in filing enhancement requests for YUI:

1. Check to see if the enhancement request has already been filed: If something similar is already in the system, augment the existing ticket rather than add your own.
2. Decide if this is something that belongs in the core library: Ask yourself the following question: Is this enhancement, on balance, so important that it's worth adding weight and complexity to the core package? (If the answer is no, probably the enhancement belongs in an implementation or extension rather than as part of YUI itself. Creating an implementation/extension and sharing it with the community via the forums or your blog might be the best solution in that case.)
3. Describe the enhancement fully: Focus on creating a simple, powerful, elegant enhancement. Suggest core use cases.
4. File an enhancement request on YUILibrary.com: Use the YUILibrary.com tracker to file your enhancement request. You must be a registered user on YUILibrary.com to file an enhancement request. If you are not already registered, please sign up for an account. Otherwise, simply log into YUILibrary.com, select New Ticket from the Project Page, then complete all of the following fields with the details of your request.
• Summary: Enter a short but specific description of the suggestion (e.g., "Add built-in XHR sourcing of content for Panel Control")
• Description: Enter a detailed description of the enhancement as text within this field or as a document attachment to the ticket. You should also summarize as clearly as possible why you feel this feature belongs in the core library and describe why you feel it would be of interest and useful to a broad cross-section of implementers.
• Type: You can specify that this is an enhancement request by selecting enhancement from the popup in the Type field.
• Component: Select the name of the component to which your enhancement request applies. In the case where your request is a proposal for a new component to be added to the library, leave this field with the default setting of None.
• 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 Defect Reports and Enhancement Requests

The YUI development team works hard to ensure that all complete bug reports and enhancement 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. Enhancement requests are factored into the YUI roadmap planning process. While it is the job of library developers to be parsimonious in adding weight and complexity 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 YUILibrary.com 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.