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
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
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
$ hg diff -g > /tmp/123456.diff
$ hg up -C
Common patch mistakes include:
Neglecting to use the
--git flag as above so that renames,
binary files, etc. are correctly handled.
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.
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.
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.
Using old sources. Patches made against obsolete sources may be
hard to use. Make sure you are using recent versions of all source
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
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
prechangegroup.mq-no-pull = ! hg qtop >/dev/null 2>&1
Now to work:
$ cd /sources/netbeans/main
$ hg init --mq
$ hg qnew 123456.diff
$ hg qrefresh -g
$ hg export -g qtip > /tmp/123456.diff
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
$ cd /sources/netbeans/main
$ hg qpop -a
$ hg pull -u
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:
$ cd /sources/netbeans/nb_all
$ hg import /tmp/123456.diff
Note: Mercurial 0.9.5 will record the commit as having been made by you, in
case the patch itself contains no authorship information. (
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
firstname.lastname@example.org where submitter is the login
ID of the person submitting the patch, i.e. the actual author. You can do so by
hg ci -u email@example.com to record the commit
(after applying the patch to working sources); a future version of Mercurial may
-u/--user option to be passed to
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
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
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.
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.