Many interesting texts are available on the value, philosophy, and practices of open source software development, so we’ll stick to some practical advice and tips for working effectively in the NetBeans project.
Any community functions according to stated or unstated contracts between its participants. In the case of NetBeans, these “contracts” are relatively lightweight. To participate effectively in a community, it is helpful to know what the typical behavior patterns are. Read on to learn how NetBeans works as an open source project.
The NetBeans project has a “governance board” that can vote and make decisions if there is some irreconcilable problem. It is composed of two members chosen by the user and developer community on the mailing lists and one member appointed by Sun Microsystems, which donated the initial source code and sponsors the project. The governance board is the choice of last resort. As of this writing, it has never had to decide an issue. It exists to ensure that no party can hijack the project or cause NetBeans to evolve specifically in its private interest at the expense of others or the health of the project and code.
Heavyweight governance, with committees, hierarchies, and chairpeople is notably absent from the NetBeans project. The authors of this book were two of the individuals who set up the initial site and governance process, and we strongly believe that it is far better to evolve the structures you need as you need them than to create formal processes that may or may not prove useful. Think of the filibuster—Robert’s Rules of Order were never created with that in mind. The point is that creating any structured social system inevitably creates perverse incentives you never realized were there until they are exploited, and to anticipate all possible loopholes and close them is both a never-ending process and an anticipation of antisocial behavior. What you anticipate, you communicate that you anticipate, and that just increases the likelihood that you’ll get exactly what you don’t want. So, when setting up the governance of netbeans.org, we concluded that less is more.
Decision making happens by consensus, arrived at on the mailing
lists. Generally, somebody proposes something, and others weigh in
with concurring or differing opinions. The person making the proposal
has the responsibility, after some time, to summarize and post what
she finds to be the consensus. There is a convention that such emails
will include [wrap up] or FINAL CALL in the subject line to indicate that this is
happening.
The underlying notion is that consensus is an efficient means of getting things done. For many parts of NetBeans, only a handful of people will care passionately about a given change. But it is impossible, in an open community, to know who those people will be. Therefore, it’s important to make sure those who are interested in a change have a voice and the ability to discuss the change. To create formal membership procedures would waste people’s time and mean that the project could not benefit from the contribution of those who do not have formal membership.
This is not to say that everyone is always happy with the results of a decision—there may be consensus with some amount of dissent. At that point, those who dissent are welcome to reopen the issue at a later time.
A truism of open source (and life) is that the only way to be sure you’ll get something done in open source is to do it yourself. If the idea is compelling, it will probably attract other developers. At the same time, a significant percentage of the developers of NetBeans are being paid to work on it because they work for a company that has specific goals. Many of these people contribute some of their off-work time to working on projects within NetBeans that they’re particularly passionate about. You will find plenty of help, answers, and encouragement on the NetBeans mailing lists. But a suggestion without the willingness to implement the suggestion is just that.
In talking about consensus, a concrete example is probably more illustrative than philosophy. The following conversation thread took place on the [email protected] mailing list in the spring of 2001, starting with one of Sun’s human interface engineers suggesting a change in the way basic and expert options were divided in NetBeans’ wizards. For the sake of saving trees, it is not reproduced here in its entirety—you can browse the entire thread on the web at http://www.netbeans.org/servlets/ReadMsg?msgId=83575&listName=nbui.
Date: Wed, 21 Mar 2001 15:58:00 -0800 From: Dirk Ruiz To: [email protected] Subject: [nbui] Erecting a novice/expert wall in wizards. Folks, Maya and I would like to propose a small wizard change. The problem is that some wizards need to present options for both the novice and expert user. The two best examples are the Setup Wizard and the New Wizard (aka the New From Template wizard). The Setup Wizard uses a checkbox at the bottom of the page to give users access to expert options. The New Wizard just enables the Finish button after the user has set the object name and package. Neither of these solutions is really adequate. Jim Dibble pointed out, in a private conversation, that making the user check a box for expert options is a bit silly. And, enabling the Finish button is too subtle. It's easy to blunder on, pressing Next, and find yourself in a bunch of screens you don't want to be in. (To my embarrassment, I find I do this frequently in the New Wizard.) What's worse is that these two solutions are inconsistent: we should settle on one solution as soon as possible. We need an obvious way to tell the user when she has specified enough, and when she is about to stray into expert territory. To this end, we would like to propose the following. Upon reaching a state where enough information has been specified, the Next and Finish buttons are both enabled (as is done now). If the user clicks Finish, then the wizard is dismissed and the object created. BUT, if the user clicks Next, a page like that shown in the two attached GIF files (SetupWizardPage.gif and NewWizardPage.gif) is shown. This page tells the user she has entered enough information to get a sensible default, and to stop here or to click Finish for expert options. In addition, we would like to propose that the left panel explicitly show this distinction between novice and expert steps with the "-- Expert --" separator. What do you think? The left panel modification seems nice, but is not absolutely essential; it could be saved for later. And, I suppose some could debate the usefulness of this for the New Wizard, since it would force the user to do an extra click in order to fill in fields and methods. But, at a very minimum, I would like to use this kind of scheme for the Setup Wizard. Not only would it be an unobtrusive way to put up a wall between novice and expert options, but it would allow us to take out the "expert options" checkbox (and replace it with something truly useful). Eventually, we would like to add this back into the NetBeans Wizard Guidelines as the standard way to erect an unobtrusive novice/expert wall for wizards. Thanks! Dirk
Terry Roberts replies to this by voting a “resounding YES,” and Dirk mentions that he meant click Next for expert options, not Finish. Jan Benway responds that the expert/novice distinction may not be the right one and that users usually treat “expert” as meaning “other.” Dirk responds:
Good point. The problem is that, in the Setup pane, it very clearly is an expert/novice type distinction. The first pane of the wizard should be comprehensible by everyone; the later panes require knowledge of the IDE and how it works. But I'm open to any label that clearly tells the user, "don't go here unless you know what you're doing", particularly in the Setup wizard.
Maya Venkatraman responds to this, pointing out that perhaps a solution is some kind of status area that indicates when there is or is not enough information to complete the wizard. She adds:
I think that the panel does introduce an irritating additional click - but users will know to expect it - and click out of it right away . What we loose by introducing the panel is outweighed by what we gain (my opinion).
At this point, Rochelle Raccah suggests:
2 possible ideas: 1) Have the "expertness" of the wizard be customizable in options. Users who want the short/long version can set it there. I'm not sure what the default would be. 2) Rename the Next button on the page which transitions between basic and expert screens. "Further customization" or something like that?
After all of this, Dirk summarizes and comes up with a modified proposal based on the feedback on the mailing list:
Date: Wed, 28 Mar 2001 16:04:49 -0800 From: Dirk Ruiz Subject: Re: [nbui] Erecting a novice/expert wall in wizards. (FINAL CALL) Folks, The discussion on erecting a novice/expert wall in wizards seems to have yielded some good conclusions. 1. "Novice/Expert" itself is the wrong distinction to be making. A better distinction would be "do now/do later" or maybe "basic/advanced". In essence, we should use categories that emphasize the characteristics of the wizard contents, rather than the qualities of the user herself. 2. For the Setup Wizard, the wall page (the one that says, "You have specified enough information to properly set up NetBeans") was seen as a reasonable way to make the distinction. 3. For the New Wizard, the wall page page was seen as a possible irritant and hindrance. Several ways were considered to deal with this, including setting an "Expertness" option for wizards, putting a "Don't show this again" checkbox on the wall page, or putting a textual/graphical indication in the Steps pane. 4. The modifications to the Steps pane received little comment. However, a private conversation with one of the UI Team developers revealed that it would not be possible to implement within the 3.2 timeframe, since the Steps pane is not directly under the wizard developer's control. With all this in mind, I would like to make the following amended proposal. We should have two types of walls between options: a high wall and a low wall. The high wall consists of a (mostly blank) wizard page that says, "You have specified enough information...". It is for things like the Setup Wizard, or other wizards that have a strong distinction between easy options and difficult options. The low wall consists of adding a textual notification to a regular, working wizard page; the text tells the user that she has specified enough information to get something sensible. It is for things like the New Wizard, where there is not as strong a distinction between easy and hard options. In the New Wizard case, it would consist of a piece of text at the bottom of the second page saying, "Ready to generate your <object>." In neither of these cases will the Steps panel change. After 3.2, we should explore other options, e.g., adding graphics or text to the Steps panel. If this is OK with everyone, I will ask the UI Team developers to make the changes to the Setup Wizard and New Wizard. Many thanks! Dirk
If you read the preceding thread, you can see a process happening here: Dirk introduces the idea. There are some objections and suggested modifications. At the end of the process, the idea has changed, but still retains its basic character. And what you see in NetBeans 3.2 and later is the functionality discussed here.
Too much is sometimes made of contributions of code to an open source project. There are many ways to participate—filing bugs and participation on mailing lists are just as valuable to the community as contributions of code! For details of the major mailing lists and resources on netbeans.org, see Chapter 13.
Contributing to NetBeans codebase is rewarding and a valuable contribution to the NetBeans community and the Java community at large. It even looks good on a resume! There are three basic ways to contribute code to NetBeans:
Create a module project and contribute it to netbeans.org.
Submit patches or bug fixes to the NetBeans core or modules—once you’ve submitted several that were accepted by the project maintainer, ask for CVS write access to the code you’re interested in working with.
Take over maintenance of an abandoned or unmaintained project—at present there are not many such projects on netbeans.org (nor should there be), but there are a few, such as the JUnit (http://junit.netbeans.org/) or ANTLR (http://antlr.netbeans.org/) modules, which are not receiving full-time attention from anyone.
The following is an example of that process in action, as it happens on the NetBeans mailing lists. This is also an abridged version of the original conversation—for the full version, see http://www.netbeans.org/servlets/ReadMsg?msgId=188265&listName=nbui.
From: "Michael Beauregard" Date: Thu, 8 Nov 2001 21:52:49 -0700 To: [email protected] Subject: [nbui] code completion enhancements I have started making my first contribution to Netbeans tonight. I want to add the following two features to the code completion popup window: 1) When using code completion for methods with many parameters, it is difficult to visually determine which parameter you must enter next. It would be convenient to highlight/bold the current method parameter in the completion view so that the user can quickly see what the next parameter is. For example, "Hashtable h = new Hashtable( 10, " should have a corresponding completion hint such as: "Hashtable( int initialCapacity, <B>float loadFactor</B>)" I have implemented this feature with minimal changes to the existing source code and I have one issue remaining. Since I am using a 'bold' font to highlight the current method parameter, it has different font metrics that are not accounted for when the ScrollCompletionPane scroll ranges are set (wherever that is??). The result is that if the method with bold chars is the longest cell in the list, then the last few pixels of the method text may be cut off in the scroll pane). 2) The next feature and issue are related to #1. Currently if you are coding a method with many parameters, you have to manually scroll the code completion scroll bar to view that last few parameters. I want the completion scroll pane to scroll automatically as needed as method parameters are being entered. I am not sure how to manipulate the scroll pane in either case so any help you can offer will probably assist both of these tasks. Thanks in advance, Michael.
Lea Anthony responds with an additional suggestion that the parameter
type, rather than the name appear when you press the comma in code
completion. Martin Roskanin jumps in to suggest that Michael look at
org.netbeans.editor.ext.java.JCCellRenderer for
font metrics information and suggest other places in the NetBeans
source base to look to for examples. Michael then responds to
Lea’s suggestion:
Adding the first change is *very* easy, but I could see how some people might not like having the type entered there. Maybe a better solution is to have the code completion window stay open as you enter method parameters. Personally, I find it a little annoying that it closes in between each method parameter. I would like some people to comment on this before I make any changes. Meanwhile, I'll look into differentiating between local/inherited methods.
Riyad Kalla responds that Microsoft Visual Studio’s code completion window stays open and that this is probably the better solution. Michael writes that he has implemented the initial feature (boldfacing the current parameter in code completion) and Lea’s suggestion. John Richardson chimes in that he doesn’t really like having the type show up, because often the suggested value is actually correct. Michael responds that he agrees, and Lea also mentions that keeping the window open is probably a better idea. Michael submits the patch as an attachment to the enhancement request he filed, and mentions this on the list. One bug is found and fixed, and the final messages in the thread are:
From: "Michael Beauregard" Date: Tue, 20 Nov 2001 13:46:04 -0700 I have provided a fix for this problem. http://openide.netbeans.org/issues/show_bug.cgi?id=17569 From: Martin Roskanin Date: Thu, 22 Nov 2001 09:45:35 +0100 Thank you Michael, I will commit your contribution during next week. If there will be any problems, we can communicate via Issuezilla's http://openide.netbeans.org/issues/show_bug.cgi?id=17569 Thank you, Martin
Doing what Michael did is a good way to get a start in programming for NetBeans—there are always small improvements or enhancements that can be made, and one of the best ways to learn a language, a codebase, or a programming paradigm is to modify someone else’s existing code.
If you want to write a module and contribute it to NetBeans, here are the steps to take:
Post to [email protected] about it. If you’re working on a module, probably you are already at least reading, if not participating in, this mailing list. You will probably want to include the following information:
- What you are creating or want to create
So you can find out if anyone is already working in this area or if anyone else would be interested in contributing.
- Info on how far along the project is
If you’ve already written some code.
Create a prototype or some working code. The netbeans.org approach to new projects is a little different than that of sites like SourceForge (http://sourceforge.net/). Generally, a module should exist in the form of at least a skeleton of code before a formal project is created—this is more interesting to the rest of the community and guarantees that netbeans.org does not become littered with projects that were good ideas with no implementation.
Make sure the source code’s licensing is correct. All code hosted on netbeans.org must, for legal reasons, be licensed under the Sun Public License (SPL), the same open and unrestricted license NetBeans’ source code is licensed under. All source and text files in your code should contain the SPL license notice, as can be found in any of NetBeans source files or the examples for this book.
Make sure your packaging and coding conventions are correct. The convention for organizing sources in NetBeans is that the base directory of a module should contain src/ and www/. The src/ directory should contain the first level package directory for your module. The source code should obey NetBeans’ packaging convention—for example,
org.netbeans.modules.somemodule. Since CVS does not handle renaming terribly well, it is best to have code packaged correctly before it is put in CVS. The www/ directory is the root directory of your project’s web site. There should also be an Ant build file for the module in the base directory of the project.The coding standards are Sun Microsystems’ recommended standards for Java, along with some NetBeans-specific items. These are detailed on the NetBeans web site (http://www.netbeans.org/devhome/docs/code_conventions.html). Coding conventions are a somewhat religious topic, but there is value in consistency—this being open source, other people will be reading and working with your code as well. Reading code that is formatted in ways you are not used to is more difficult than reading code that is formatted in a familiar way. Using consistent coding conventions ensures that everybody working on NetBeans will be accustomed to what they see on the screen and able to read it easily.
Contribute the source code. The contrib.netbeans.org project (at http://contrib.netbeans.org/), is designed to host your source code temporarily. Follow the instructions you see there. When your module becomes complete enough to need its own project, request creation of CVS space for it and a web site, including what you want it to be called.
Set up your module’s web site. Modules have their own web sites, using virtual hostnames—if you are working on the
humdingerproject, your site would be humdinger.netbeans.org. Your module web site is managed through CVS. Once you’ve gotten notification that the code you’ve contributed is in CVS and the site is set up, perform a checkout of the sources from NetBeans’ CVS server. You will find a www/ folder is present in the top level folder of your checkout. In this folder you can create your module’s web site, checking the images and HTML files into CVS just as you would source code. You can optionally set up mailing lists for users or developers of your module.Release your alpha/beta module. When your module is mature enough to be feature-complete and functional but not necessarily bug-free, make a request on [email protected] to add the module to the alpha update center on netbeans.org. This will make your module available to all users of NetBeans. Announce the release on the [email protected] mailing list and be available on the [email protected] mailing list to answer questions and encourage users of your module to test it and others to try it out. You can also submit a news item to appear on the main pages of the NetBeans web site.
Code, bug fix, test, and release. Use Issuezilla to track bug reports and requests for enhancement of your module. As you fix bugs and implement enhancements, update their entries in Issuezilla, so the people who reported them will know you’re working on them. From time to time (every few weeks to month or two), update the version of your module that’s in the update center so that users will be testing the latest bits. Announce the updates on [email protected] so people will find out about them even if they don’t habitually check for updates.
Request that your module be included in the standard NetBeans build or listed on the standard update center. When your module is stable and mature, you can request that it either be included in the standard NetBeans distribution (this is a community decision that should take place on [email protected]). Including something in the standard distribution means that it is stable and generally useful enough to belong there. The decision is up to the entire community.
Write unit tests. Unit tests are a way of guaranteeing that functionality remains stable over time. The NetBeans source base is continually built and tested. Available from the NetBeans web site are tools for testing functionality, API/SPI backward compatibility, and performance. If you add your unit tests to the suite of standard tests, it will be easier to find out about problems as soon as they happen. See Chapter 27 for more information on unit tests.
The sources are stored in a CVS repository (http://www.netbeans.org/devhome/sources/cvs.html). CVS is an open source version control system. To use it you need a CVS client. The IDE includes a CVS client written in Java, in the JavaCVS module. CVS allows the tracking of version histories and functionality to allow users to check out, modify, and update files.
The sources to NetBeans can be downloaded via anonymous CVS; permission to write to the CVS repository is customarily granted on request, provided that the requester has submitted some patches or other code and that the other developers on the project agree to it.
The address of the CVS server is cvs.netbeans.org. The
CVSROOT environment variable for a CVS client to
check out the NetBeans sources should be
:pserver:[email protected]:/cvs with a
blank password.
The site is divided into projects, each of which has a virtual hostname. So, for example, to find proposals regarding the Editor, go to http://editor.netbeans.org/. Some projects do have their own mailing lists, but most of the discussion happens on two main development mailing lists, [email protected] and [email protected].
Projects are mostly a web-site user interface abstraction; each module on netbeans.org has its own virtual hostname—but in some cases, there is not a justification for large amounts of web content about, say, support for sourceless Java .class files. Having a parent project allows for logical groupings of modules and the possibility of mailing lists based on topics common across a subset of projects.
The name of a project corresponds to its name as a CVS
module—for example, cvs co editor checks out
the source code to the Source Editor. cvs co all
will download the entire NetBeans source base. For details on the
NetBeans sources and CVS access to them, see the sources pages on
netbeans.org (http://www.netbeans.org/devhome/sources/index.html).
If you have a question, a problem, a solution, a module, or just want to get involved, these are the first places to go. Development decisions are made in public, on public mailing lists. Here is a breakdown of the major mailing lists:
- [email protected]
Discussion about using the IDE.
- [email protected]
General development discussion.
- [email protected]
Discussion of the Open APIs and their usage, and requests for changes or enhancements.
- [email protected]
User interface planning and discussion.
- [email protected]
Discussion of issues relating to netbeans.org infrastructure, such as mailing lists and the web site and community issues.
- [email protected]
The weekly NetBeans newsletter contribution list. The NetBeans newsletter covers interesting threads from the mailing lists and is a “week in review” for the NetBeans project. If you’d like to see certain issues go out as part of the newsletter, send the information to this address so that the volunteer writing the newsletter that week knows about them.
Additionally, bear in mind that projects may have their own mailing
lists—for example, [email protected].
If there are multiple participants in your module project, one of the most effective ways to keep up with what is going on in the project is to sign up for the project’s CVS mailing list. Whenever someone commits code into the source base of your project, you will get an email with the log message detailing what they did. This is a tremendous resource for collaboration—please don’t overlook it!
To subscribe to the CVS mailing list for a given module or project,
send a blank email to
cvs-subscribe@
someproject.netbeans.org.
Module owners are also expected to subscribe to the issues mailing list for their project. This mailing list receives emails whenever bug or enhancement reports for the project are created or updated.
To subscribe to the issues mailing list for a given module or
project, send a blank email to
issues-subscribe@
someproject.netbeans.org.
netbeans.org currently uses Issuezilla, scion of Bugzilla, the venerable bug-tracking tool from the Mozilla web browser project. Each virtually-hosted module also gets its own bug-tracking category in Issuezilla.
While the query interface to Issuezilla is somewhat terrifying at first glance, it becomes fairly easy to use with practice. A bug report specifies a number of things, such as these:
The version of NetBeans in which the bug was observed
The operating system on which it was observed
The component (module) that has the problem
The subcomponent, such as code, documentation, or user interface
A summary of the bug
A description of the bug
Keywords to help classify the bug
Who (if anyone) is responsible for fixing it
Part of contributing bug reports is making sure that they are clear and specific. Where possible, include the exact steps to produce the bug and attach your log file, which contains platform information and many diagnostics. Note that a BugSubmitter module is now in progress that will mine this information directly from a running copy of NetBeans and save time and effort. As of April 2002, it is not yet included in the standard builds, but probably soon will be. For more information on writing effective bug reports, see the HOWTO document on the NetBeans web site (http://qa.netbeans.org/bugzilla/reportbug.html). Two other good resources on writing effective bug reports are
Simon Tatham’s entertaining How to Report Bugs Effectively (http://www.chiark.greenend.org.uk/~sgtatham/bugs.html)
The Mozilla project’s How to write effective bug reports (http://www.mozilla.org/quality/bug-writing-guidelines.html)
Elisabeth Hendrickson’s insightful treatise on the subject (http://www.qualitytree.com/feature/webr.pdf)
The social context of open source projects is mailing lists, and yet there is remarkably little written about how to be an effective participant on them. While this is an area that is under-researched, we can share some of the things that have worked for us.
- Lurk before posting
If you have just signed up to a mailing list, read it for a while before posting to it, and get a sense of who the people there are and what the community is like.
- Read the entire thread (or a lot of it) before responding
A fast way to lose credibility in a public community is to sound like you don’t know what you’re talking about. Take some time to know the context in which you’re responding.
- Assumptions are as important as what you say explicitly
Indirect communication is sometimes more important than direct communication. That which is directly communicated is more likely to arouse resistance than what is indirectly communicated. Another way of saying this is that tone means a lot.
- You catch more flies with honey
Even if someone replies to you with overt hostility, treat them with respect and make sure that the assumptions underlying your response are that they are trying to help. That makes it much more likely that the next response will have constructive content.
- Greet people when replying
Simply including “Hi, David,” (or whomever you’re addressing) dramatically changes the tone of a message, and it shows that you’ve taken the time to read and appreciate the message you are replying to.
- Be concise
A message that covers a huge range of information is less likely to draw responses—it’s too much work to read it. Also, if there are several important points, it is likely that the resulting thread of responses will not address all of them. By having a topic for a post and sticking to it, it keeps the conversation focused and makes it easier for other people to respond. Also, since not everybody reads every post on the mailing lists, some people who may have something valuable to contribute to the conversation may never end up reading it, because the subject didn’t indicate it was of interest to them.
The NetBeans mailing lists are remarkably free of the flame wars found elsewhere on the Internet, largely because of this type of interaction. It is a wonderful community of bright, interesting people, and we hope to meet you there!