Contributing to NetBeans

NetBeans is my IDE of choice and I was recently accepted as an approved contributor on the back of the Java Completion Excluder:

Exclude classes from appearing in the code completer (such as sun.* and sunw.*) with method-level granularity. Example use case: java.lang.Object.{wait*, notify*, clone, finalize} have more appropriate alternatives so allow the user to disable the completer from acknowledging their existence.

In this post, I’ve documented my initial experience of contributing to NetBeans, in the hope that it will lesson the barrier of entry and inspire readers to consider doing the same!

Community

NetBeans Users and NetBeans Developers mailing lists exist on Nabble, there is also a (low volume) users IRC channel #netbeans on freenode.net, but none for developers. All issues are tracked by an issuezilla installation at netbeans.org/issues/, unfortunately no signs of a uservoice.com-like service for capturing user feedback.

The developer mailing list is particularly helpful. If you’re thinking about contributing, I recommend that you first create an account and then file a Request For Enhancement (RFE) (or follow an existing one). Do not expect any feedback on the RFE! Instead, direct your communication toward the developer mailing list about which files/projects are the ones relevant to your RFE. Do not be afraid to ask too many questions! You are contributing after all. Count on response times of “days” rather than “hours”.

Resources

NetBeans maintain a wiki for developers. It is more useful for understanding practicalities and writing plugins rather than the core codebase, but worth skimming:-

• NetBeans Developer FAQ - especially the Getting Started section
• Java Developer’s Guide - describes how to access java model
• Mercurial HowTo - describes how to use the version control system
• SUN Contributor Agreement - legal, you’ll need to sign and scan the agreement before your work can be integrated
• Patches - how to create and submit patches

The NetBeans source is really huge, but it is a modular system so it is not necessary to know everything.

Getting Started

Let’s get a copy of the source code! For this, you’ll need to install Mercurial. There are a multitude of different repositories that you can subscribe to. Start with main-golden, which is the branch used to build the nightly snaphots. It is the most stable of all the development branches and should usually build.

Mercurial is a massive pain and demands pulling a complete history of NetBeans development in order to allow you to start working… approaching 3 GB over a network! That essentially means you’ll have to wait until tomorrow before you can get started. Issue a command similar to the following to grab a copy:-

hg clone http://hg.netbeans.org/main-golden/

and to stay up to date, type

hg pull -u

which does a “pull” of the history from the server to your history repository, then an “update” to patch all your local files with the latest changesets. Once that’s done, go into the main-golden branch and install the latest version of the Netbeans javac API. This is necessary, otherwise your NetBeans editor will use the J2SE javac API and report errors where the API has changed.

cd main-golden
hg clone http://hg.netbeans.org/nb-javac/
cd nb-javac/make/netbeans/nb-javac/
ant jar

Optionally, clone the “contrib” repository

cd main-golden
hg clone http://hg.netbeans.org/main/contrib

NetBeans requires a significant amount of resource to build, ant will cry like a baby unless you set appropriate memory limits such as

export ANT_OPTS="-Xmx1024m -XX:MaxPermSize=256m"

Then you’ll need to do a first build by issuing

ant -Dcluster.config=basic

That will take a few hours and requires network access, so you’re probably another day down before you can get started.

Mercurial has a steeper learning curve than other version control systems, so my advice is to just not commit anything locally and issue an hg diff when you want to create a patch for your mentor and an hg revert when you want to get back to a fresh clone of the source. If you do accidentally commit anything, don’t panic… enable the MercurialQueues extension and issue an hg strip rev command after backing up your changes to a diff file.

You can open up individual modules as projects in NetBeans… don’t bother opening up dependency projects. You should be able to issue an F6 to run your build. If you don’t make structural changes to the codebase, consider running it in debug mode and “apply changes” to save you from starting it up after every edit.

You can get a good idea of where to start if you:-

• open up any of the NetBeans module projects
• go to the “Important Files” folder in the project layout
• Expand the “XML Layer” file
• wait for the indexing to finish
• click on “<this layer in context>”
• navigate to something that looks like what you’re wanting to modify (e.g. “Menu Bar” -> “Source”)
• right-click on the entry and select “Open Layer File(s)”
• take note of the class name associated to the action
• right-click in the editor window and go to “Select In -> “Projects”

You should then be able to work out which project (and class) to start with.

There are some formatting rules, and the first one is spaces not tabs! Be sure to check that your settings are appropriate, as the default NetBeans behaviour is tabs. To be cheeky, consider setting the per-project formatting settings to spaces and sending the resulting config change as your first patch to your assigned mentor

Final Word

Contributing to NetBeans is very rewarding. In two weeks I went from complete n00b to seeing my feature integrated into the Nightly Builds, soon to be part of a stable release for everybody to enjoy.

Don’t be afraid to bug the existing developers… they are either overworked or volunteers, but I found them all to be very friendly and offer constructive criticism. Nobody is going to offer to be your mentor, so grab the first few who show an interest in your work and keep them involved by responding to their feedback. Most importantly take their feedback onboard!