Contributing Patches

Well-described, easy-to-apply patches are a pleasure for a developer to receive and go a long way towards making the IDE more stable and powerful, so thank you in advance for contributing them! Here's how to do it.

Tip for NetBeans 5.0 Users

• Switch to Files explorer view.
• Find folder with your local changes.
• From CVS menu select Export Diff Patch....

Making and applying a patch

First, make sure you are making changes in the most recent version of the sources - for this, it is best to use CVS to check out the source (usually on the CVS trunk; sometimes the most active release branch - ask if unsure), make your modifications (but do not check them in), and then run (example for Unix, other operating systems similar):

$ cd /sources/netbeans/nb_all
$ ls
shows ant, apisupport, applet, ....
$ cvs update beans ...or wherever your changes are; may be >1 module
make sure you are working against current sources
$ cvs diff beans
sanity-check the change
$ cvs -f diff -u -N beans > /tmp/my-patch.diff
sanity-check the patch

If you are adding or modifying binary files, it is best to attach the new or modified binary files separately and exclude them from the textual patch.

Common patch mistakes include:

1. Forgetting -u. Default-format diffs show no context and will be hard to read and apply, especially if they were made against somewhat out-of-date sources. -c is also OK but -u is most common.

2. Forgetting about new (added) files. Run cvs add (but do not commit!) to make sure CVS thinks of them as added as part of the patch, and remember -N which includes them in the patch. Also run cvs remove (but do not commit) when a patch should delete some files.

3. Using other switches such as -t which can make the patch difficult to apply.

4. Starting from the wrong directory. Always make patches from the root of the source tree to avoid confusion.

5. Manually editing patches. You may be tempted to concatenate patches, or manually edit them to exclude things you do not really want to submit. Do not do this. The patch may be corrupted as a result. Fix your sources to reflect what you want the result to be, and run a fresh diff. Include all affected files in the diff command, even if they are in different modules.

6. Including extraneous changes. Look over your patch to make sure every change relates to the fix you are making, and is necessary. Remember other people will read your patch before applying it! Do not make gratuitous whitespace changes. Do not reformat existing code you are not modifying.

7. Using the plain diff command. Use cvs diff to ensure that exact information about repository path and original version of the patched files is retained.

8. Using old sources. Patches made against obsolete sources may be hard to use. Make sure you are using recent versions of all source file (cvs update first). If you must submit several patches against the same files, be sure to indicate if they must be applied in some particular order.

A properly made patch is easy to apply by someone with commit access who has reviewed it. Use of the Unix patch tool is recommended; Windows users should be able to get it from the Cygwin tools distribution.

save patch to disk, say /tmp/suggested-patch.diff
$ cd /sources/netbeans/nb_all
$ patch -p0 --dry-run < /tmp/suggested-patch.diff
make sure no errors are reported - this just tests the patch format
$ patch -p0 < /tmp/suggested-patch.diff
$ cvs diff beans/ or whatever part of sources are affected
sanity-check diff, compare to patch (should be same or similar)
test, do a build, commit as usual

If the "dry run" fails, you may need to use additional options to patch, or at worst just apply the patch manually. Do not forget to sanity-check file additions and removals! You probably need to use cvs add and cvs remove to complete these.

Making a patch available and accepting it

The best way to submit a patch is through IssueZilla. In some cases you could send it as a MIME attachment to the proper mailing list if it is a short patch and you are more expecting it to looked at for comments than applied as is. But usually patches ought to be put in IssueZilla.

First, if an issue describing the problem (or feature) you are trying to solve already exists, use it. If it does not, create an issue, and mark it to be of type PATCH. The issue should include at least the following:

• The patch file itself, of course - as an IssueZilla attachment, not pasted into the Description field. (Line-wrapped or reformatted patches are not usable. They must be exactly as produced by cvs diff.)

• A description of what problem you are trying to fix, if possible with steps to reproduce it.

• A description of what the behavior should be with the patch in place. Ideally also steps to demonstrate that the patch fixes the described problem.

• If reasonable, a description of how the patch works.

• If a significant amount of code is involved, it is safest to mention in the issue comments that you agree to let the patch be used under the Common Development and Distribution License (CDDL) as part of the IDE's code. If you are adding new source files, they must be marked with the SPL notice or the patch cannot be accepted.

• If this is your first code submission to netbeans , you must fill in a Contributor Agreement - see the CA Policy page for more info.

• The patch submitter should be either the submitter of the issue, or add him or herself to the CC list of the issue. This ensures that the submitter will see any comments or changes made to the issue and be able to respond if needed.

The developer responsible for the section of code affected should either apply the patch and mark the issue FIXED; or add a comment with an objection if the patch does not seem safe, does not appear to fix the problem, or there is not really a problem to begin with. Developers must remember to record the authors of patches they apply for purposes of generating credits lists. Use the file core/release/CREDITS.html for this. Developers must also confirm that the contributor has filled in and submitted a CA before commiting their patch - see the CA Policy page for more info.

Notifications of any changes to IssueZilla, as well as CVS checkins, are automatically sent to the appropriate bug and CVS mailing lists, so you can monitor if the patch has really been applied. Make sure you subscribe to at least the CVS and bug mailing lists for the module you are working on - see the mailing lists page for details.

Of course, if you do not know exactly how to fix a problem, but have an idea that it is being caused by a certain section of code somehow, you can just mention what you know on the developer list and maybe someone else will know how to fix it. And please report a bug about it so it does not get lost.