[Db-derby Wiki] Update of "PatchAdvice" by DanDebrunner

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Db-derby Wiki" for change notification.

The following page has been changed by DanDebrunner:
http://wiki.apache.org/db-derby/PatchAdvice

New page:
= Advice on developing and submitting patches =

Some advice on what makes a good patch submission, thus more likely to be committed quickly.

A summary would be: communicate, communicate, communicate!

  * Share your ideas early with the list, maybe a better way exists, maybe someone will provide some information that cuts your development time in half. If you don't share then you are guaranteed no help.

  * Ask questions to derby-dev while you are working on the patch. Unsure how to throw an exception, ask the list, need to know if a method to do X already exists, ask the list. All questions are welcome.

  * Address a single issue in the patch.

  * Consider multiple patches to address an issue. Incremental development is good, smaller self-contained patches are easier to review, easier to describe, easier to spot bugs in. If your description of a patch starts to list more than two or three things you needed to change to address the overall issue, then step back and consider if breaking the fix into multiple discrete steps would be better.

  * Don't mix code cleanup with real code changes.

  * Describe your change. A patch by itself gives no help on where to start looking at how the problem was solved. Provide an overview or instructions on where the overview is in the patch. E.g. "please start at the javadoc for the SQLPSM class".

  * Describe the problem and how you are addressing it. It may not be obvious to reviewers what you are trying to do, even if you think it is. You may have been working and thinking about the issue twenty four hours a day, the reviewers are detached, they don't have the context you do and probably don't have the in-depth knowledge you do.

  * Tell the list if you think this completely solves the issue or is an incremental fix. We can't read minds!
    
  * Say what tests were run and if they passed.

  * Comment your code - code needs to be understood by itself five, ten years from now when all context is lost to time.

  * Ensure code comments add value, saying why the code is doing something is more important than how it is doing something.

  * Encourage reviews, don't aim your submission an a single person, the more eyes on the code the better.