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.

These instructions assume you are working on recent versions of NetBeans source code, starting with 6.1, which are kept in a Mercurial repository. If for some reason you need to submit a patch made against 6.0 sources or older (which is discouraged), the ideas are similar, but you will need to use CVS commands (generally cvs diff -u -N).

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 Mercurial to obtain out the source (usually from the main or main-golden repositories, unless you want to work on a release branch - ask if unsure), make your modifications, and then run (example for Unix, other operating systems similar):

$ cd /sources/netbeans/main
make your edits to fix bug #123456...
$ hg diff -g > /tmp/123456.diff
sanity-check the patch
$ hg up -C
revert local modifications to get clean sources again

Common patch mistakes include:

1. Neglecting to use the --git flag as above so that renames, binary files, etc. are correctly handled.

2. 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.

3. 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.

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

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

You might prefer to commit your change locally (hg ci), in which case hg export -g can be used to save the patch to a file. In this case the change will remain permanently in your local copy of the repository; if you pull in updates from the server, you will need to merge. This approach has the disadvantage that if the patch is accepted and committed to the official repository, you will nevertheless need to do no-op merges indefinitely.

If you plan to submit various patches and keep some of them active in your local copy of NetBeans sources unless and until they are accepted, a better approach is to use Mercurial Queues. First some setup in your ~/.hgrc:

[extensions]
mq =
[hooks]
# For safety; would be different on non-Cygwin Windows:
prechangegroup.mq-no-pull = ! hg qtop >/dev/null 2>&1

Now to work:

$ cd /sources/netbeans/main
$ hg qinit
$ hg qnew 123456.diff
make your edits to fix bug #123456...
$ hg qrefresh -g
$ hg export -g qtip > /tmp/123456.diff
sanity-check the patch

Later you can run hg qnew to start work on a new patch, or use hg qgoto to jump to an earlier patch, etc. When you want to update NB sources:

$ cd /sources/netbeans/main
$ hg qpop -a
$ hg pull -u
use hg qdel to remove any patches which have been accepted

and see if you can apply your patches again. The Mercurial electronic book also describes how to use merging facilities to make it easier to apply patches which conflict with other changes, as well as many more details on using MQ.

A properly made patch is easy to apply by someone with repository push access who has reviewed it:

save patch to disk, say /tmp/123456.diff
$ cd /sources/netbeans/nb_all
$ hg import /tmp/123456.diff
test, do a build, use hg rollback if patch is bad

Note: Mercurial 0.9.5 will record the commit as having been made by you, in case the patch itself contains no authorship information. (hg diff produces a bare patch, whereas hg export records authorship, date, and log message.) It is preferable to record the commit as having been made by submitter@netbeans.org where submitter is the login ID of the person submitting the patch, i.e. the actual author. You can do so by using hg ci -u submitter@netbeans.org to record the commit (after applying the patch to working sources); a future version of Mercurial may allow the -u/--user option to be passed to hg import too.

Making a patch available and accepting it

The best way to submit a patch is through 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 now. 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 Mercurial.)

• 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) v1.0 and the GNU General Public License (GPL) v2 as part of the IDE's code. If you are adding new source files, they must be marked with the license notice or the patch cannot be accepted.

• If this is your first code submission to netbeans.org, 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 his or her login ID 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 ide.branding/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 pushed Mercurial changesets, are automatically sent to the appropriate bug and source control mailing lists, so you can monitor if the patch has really been applied. Make sure you subscribe to the appropriate mailing lists for the module(s) 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.