Submitting effective issue reports

 

Step 1: "Plug-in" to the Community

 

So you think you've found a bug with in the RichFaces codebase?  Or perhaps you've got a feature you'd like to see implemented.  The best place to start is to bring up your issue in the user forums, or on IRC.  Often times, others have will have come across a similar issue, and can confirm or reslve your issue.

 

The next step in getting your bug fixed or your feature implemented, is to create an issue in our issue tracker.

 

Step 2: File an issue

 

Bugs and feature reauests are tracked Issues in the "RF" project of the JIRA issue tracker for JBoss projects:

 

https://issues.jboss.org/browse/RF

 

Below are some guide-lines for filing a bug-report against the RichFaces project.  Feature requests should similarly follow these guide-lines as appropriate.

 

When filing your bug-report, the most important consideration is to provide a description that clearly identifies:

1. Description: What do you observe?  What do you expect to observe?

 

Secondly, in order to re-produce and diagnose your problem, you need to provide the code relevant to the issue.  Code provided for this purpose should be a:

2. Short, Self Contained, Correct (Runnable), Example (http://sscce.org/)

 

Such a SSCCE example is important, as it will accelerate re-production of your issue, and better enable RichFaces developers to come to a resolution of the problem you are facing. Consider the task of isolating the problem to be your contribution to the open-source porcess, with of course the isolation task culminating in the form of a pull request (see the Contributor Getting Started Guide for more details).  We're not requiring every issue submitted to be accompanied by a pull request, as this isn't always achievable, but the more work you put into isolating an issue, the farther along the project is to finding a fix.

 

Some tips for providing such an SCCEE code sample include:

  • Remove any irrelevant facelet markup
  • Provide the simplest possible backing-bean(s) required to run the facelet sample
    • Remove all external dependencies not related to the problem
  • Provide a maven build that results in an archive deployable to an out-of-the-box container
    • If any container configuration is *required* to reproduce the bug, then provide clear, straight-forward instructions on how to do so

 

An Arquillian-based test is by far the best, unfortunately the JSF-based Arquillian tests are not the easiest thing to write at the moment.  The RichFaces team is actively working on overcoming this hurdle with the Arquillian team, so stay tuned as we develop/refine the tooling steps required to simply create/submit such a test

 

Other Important Considerations

 

Some other important fields to set when filing issues are:

  • issue type:
    • typically use "Bug", "Feature Request"
  • Components:
    • set the components affected by the bug/feature-request
  • Affects version:
    • what version of RichFaces we're you using when you found this bug?
  • Environment:
    • What container are you running in?
    • What JSF impl are you using when you observe this bug?
    • What significant 3rd party libraries are required to reproduce this bug?
  • Description:
    • What do you observe?  What do you expect to observe?
  • Forum reference:
    • Did you discuss this issue in a forum thread?  If so, link it here
  • Worakround description:
    • (Bug only) - were you able to work-around the bug?  Describe how you did so here
  • Steps to reproduce
    • (Bug only) - a simple enumeration of the step required to reproduce the bug

 

More Resources

For further details on: