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).
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 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:
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
[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 init --mq $ 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
$ 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. (
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
email@example.com 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 firstname.lastname@example.org to record the commit
(after applying the patch to working sources); a future version of Mercurial may
-u/--user option to be passed to
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
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.