Bug and RFE Fix Guide

This document describes how to submit patches for the freebXML Registry project.

What is a Bug and an RFE

A bug is a defect that has been identified in the code base. An RFE is short for "Request For Enhancement" and is a request for a new feature or other improvemnt in the code the absence of which is not considered a bug.

We use the term Fix to refer to a Bug Fix or an RFE Fix.

When to Submit a Fix

A fix may be submitted at any time unless there is a Soft or Hard Code Freeze.

Soft Code Freeze

The Project Lead may declare a "soft code freeze" at certain times, typically when code has become unstable or in later parts of a release. During a soft code freeze all fixes deemed potententially risky must be reviewed by the team using the Fix Review Process. It is up to the developer to decide which fix they consider risky and worthy of team review.

Hard Code Freeze

The Project Lead may declare a "hard code freeze" at certain times, typically when code has become unstable or in later parts of a release. During a hard code freeze all fixes must be withheld. If you feel you have an exceptional case then the fix must be approved by the Project Lead.

Who Can Submit a Fix

Only members of the project team can submit a fix. It requires commit privileges in the CVS repository.

Others may submit patches using the Patch Submission Process.

How to Submit a Fix

  • Check if there is an existing Bug or RFE for the problem. If not create one and assign it to yourself.

  • Send an email to ebxmlrr-team mailing list listing the URL to the Bug or RFE and stating that you are working on a fix for it. This prevents duplicated efforts.
  • Run the JUnit regression tests before you make any code changes and save the output in a file for later comparison. This gives you a baseline for which tests pass and which tests fail before your changes.
  • Create a new JUnit test or update an appropriate existing JUnit test to duplicate the bug or test the RFE. Make sure the new test(s) fails prior to your code changes.

  • Make your code changes
  • Run the JUnit regression tests after you make your code changes and compare with the saved output. Make sure your changes have not made any new tests fail. Make sure that your new test(s), if any, now pass instead of fail.
  • If your changes are significant, rebuild your test data base your createDemoDB target
  • Rerun the JUnit regression tests after createDemoDB (requires user registration and adding new user to jaxr-ebxml.properties)
  • If the fix is complex or if the project is in a soft code freeze then the fix should be reviewed using the Fix Review Process.

  • Commit the fix
    • First make sure you are synced with the latest CVS code by doing:

      cvs update -RAd

    • Fix any merge conflicts if needed manually

    • If there are many files involved then write commit message in a text file and use the "commit -F <commit msg file> <files>" command. See an example here.
    • Make sure that all newly added files have been committed

  • If the Fix is major then you should checkout the repository in a fresh workspace and make sure the build is not broken and the regression tests stil work.

  • Update Bug or RFE page.

Fix Review Process

  • Use the techniques defined in the Patch Submission Process to create a patch file for your fix
  • Send an email describing your proposed fix to the ebxmlrr-team alias:

    • The subject should formatted like:
[Proposed Bug Fix] Bug 885459: Access Control design not intercepting all Actions

[Proposed RFE Fix] Bug 885460: Access Control design needs to be faster

  • The body should give a detailed overview of the fix. Here is an example. It should have the following sections:
    • Primary Reviewer: <Name of team member whom you have identified as best to review this fix>
    • Problem, RFE or New Feature (use only one as appropriate)

    • JUnit Test: Give fully package qualified JUnit test name
    • To Reproduce: Required only for Bugs and not for RFEs. Include clear and minimal steps to reproduce the bug. May refernce unit test.

    • Design / Solution Overview: Describe, clearly the solution and design used by the Fix.
    • Files Added: Give a brief description of each new file

    • File Modified: Give a brief description of changes for each file

    • Files Deleted: Give a brief description of each deleted file

  • The message should have the patch file as a mime attachment
  • Contact your primary reviewer and review the code changes.
  • If the Fix is major then wait 24 hours is possible (specially during a code freeze) to let other team members comment on the Fix

  • Commit the changes using the text in Proposed Fix email within the commit message file.

What Happens When You Submit a Fix

  • Other team members will get your Fix whenever they do a

    cvs update -RAd

  • Hopefully the bug is fixed.
  • You feel good and your team mates and user community showers you with affection :-)