NetBeans First Patch Program
The NetBeans Team announced in July 2011 that the open source project has 1 million active users. The project is unique in that its users are also developers, and we want to encourage more of them to become actively involved in making it better for everyone who uses it.
Of course, there are many ways to contribute, including submitting issues that describe bugs or useful new features, helping with localization, evangelism, documentation or answering questions on our mailing lists. Although the process for submitting code is well-documented, it involves tools and procedures with which some developers may lack experience. Experienced contributors find that that process is pretty straightforward, but it can be intimidating for new developers who want to submit their first patch.
If you've ever considered contributing code to NetBeans but felt you needed some extra guidance, we'd like to explain the "First Patch" program to you. This program attempts to pair a NetBeans user who has never contributed code with a mentor who volunteers to lead that developer through the process of submitting his or her first patch. We expect that once you've contributed your first patch, you'll have the confidence you need to submit more. You may even want to volunteer as a mentor to help someone else submit their first patch.
To be clear, this program is aimed at getting through the patch process, not on learning Java or the NetBeans APIs. You're welcome to find an existing issue to work on or to file a new one, but in any case, the change should be a relatively simple improvement to NetBeans -- any of these issues would be perfect candidates (but see the bottom of this page for a list of issues that other people have already signed up to work on). The mentor who is assigned to assist you will be able to provide guidance in any of the following areas:
- How to check out the source tree
- How to build NetBeans from source
- How to locate the code which needs to be changed
- Advice on how to implement the change, per NetBeans coding standards
- How to write a unit test for the fix, if applicable
- How to create a patch
- How to use IssueZilla to submit the patch and track progress
- How to verify the fix has been correctly applied to the NetBeans codebase
As a volunteer, you'll gain experience while making NetBeans better for all who use it. Of course, your resume/CV will probably also benefit from being able to say that you've contributed to one of the most popular open source projects around. But most importantly, you'll be able to give something back to the NetBeans community.
How to Participate
To ensure participants get the attention they deserve, each mentor will work with just one developer, so space is limited.
Although we are currently running a second session of the program, we once again have more developers than mentors. If you're an experienced NetBeans contributor who wants to volunteer as a mentor, please contact Tom Wheeler (firstname.lastname@example.org) directly. If you'd like to participate in the program to submit your first patch, e-mail Tom and he'll make sure you're added to the wait list and included if there's a third session.
Program Milestones and Schedule
The following is a list of milestones for the First Patch program. It's here to show the sequence of events, who is responsible for each step and help keep you on track. Although the list may seem long at first, many of the tasks take just a few minutes to complete.
Before the program begins (phase 0)
(To complete by Monday, 3 October 2011)
- 0.1.- Developer submits the Contributor Agreement (CA)
- 0.2.- Developer creates an account on netbeans.org (to allow updates to IssueZilla and the Wiki)
- 0.3.- Contributor Agreement is approved by Oracle
- 0.4.- Developer identifies the issue he/she wants to work on to the program administrator (Tom Wheeler).
Finding what you need to fix (phase 1)
(To complete by Sunday, 16 October 2011)
- 1.1.- Program officially begins and the mentor is assigned/introduced to developer
- 1.2.- Developer assigns issue to himself/herself, changes its status to STARTED and adds both the mentor and tomwheeler to cc list
- 1.3.- Developer checks out code from Mercurial
- 1.4.- Developer builds the appropriate configuration of NetBeans from source
- 1.5.- Developer identifies the files which needs to be changed, then updates the issue to describe how he/she will implement the fix and test those changes. This will be called the "implementation plan."
- 1.6.- Mentor reviews the developer's implementation plan and makes helpful suggestions about possible improvements.
- 1.7.- Developer updates the issue to describe any changes to the implementation plan.
Modifying the code to fix the issue (phase 2)
(To complete by Wednesday, 26 October 2011)
- 2.1.- Developer implements the changes described in the implementation plan.
- 2.2.- Developer tests that the changes fix the issue
- 2.3.- Developer creates a patch and attaches it to the issue in IssueZilla
Testing the fix (phase 3)
(To complete by Sunday, 30 October 2011)
- 3.1.- Mentor examines the patch to ensure it's consistent with the implementation plan and NetBeans coding standards
- 3.2.- Mentor applies the patch, builds the sources and runs any relevant automated tests
- 3.3.- Mentor verifies (via either a manual or automated test) that the issue is fixed
- 3.4.- Mentor updates the issue to state that it's ready for inclusion in NetBeans if the patch is OK. If it's not, mentor explains what needs to be changed and developer repeats the "modifying the code to fix the issue" step to include these changes.
Applying/verifying the fix in NetBeans (phase 4)
(To complete by Wednesday, 9 November 2011)
- 4.1.- The mentor will push the change in Mercurial if he/she has commit access, or will work with another NetBeans developer so he/she can verify and test the change. The mentor will either let the developer know that the patch is OK, or if not, what needs to be changed.
- 4.2.- A few days after the change has been pushed to Mercurial, developer downloads a nightly build to check that the issue is fixed, then marks the issue VERIFIED in IssueZilla.
- 4.3.- Mentor contacts the program administrator (Tom Wheeler) to inform him that the issue is now resolved. Program Administrator adds developer to list of graduates on the First Patch wiki page.
As a participant, you'll need to communicate with two people. Your first few contacts will be with Tom Wheeler (email@example.com), who set up the First Patch program. After you've signed the contributor agreement and told Tom what issue you plan to work on, Tom will introduce you to the mentor who will be helping you.
Your mentor will be responsible for reviewing your implementation plan and patch, testing your patch and verifying that the issue is resolved. Additionally, he or she will answer any questions you have along the way, particularly on how to use Mercurial, IssueZilla or about NetBeans coding standards. Although e-mail is probably the best way to stay in contact with your mentor, you may also communicate in other ways (e.g. Skype, telephone, etc.) if you both find it convenient to do so. Your mentor will strive to answer your questions within a day or two, but should also inform you (and Tom Wheeler) if he or she plans to be unavailable for more than two days during the program. Both developers and mentors should feel free to contact Tom Wheeler (firstname.lastname@example.org) if they're having trouble or need clarification.
Finally, it will be very helpful if developers can take notes as they work through submitting their first patch, then summarize those notes for Tom Wheeler at the end. This will give use the feedback we need to improve any documentation that is unclear and to try and make the process for submitting patches even easier for new contributors.
Issues Already Claimed
The following issues have already been claimed by other participants for the second session, so you will not be able to choose them:
- #51924 - Ulrich Cech
- #82745 - Charles Edward Bedón Cortázar
- #134643 - Mario Schroeder
- #148359 - Dhawal Saiya
- #187579 - Neeraj Chauriya
- #197502 - Ernest Lötter
- #201303 - Constantin Drabo
- #159203 - Martin Skurla
- #134448 - Maxim Shekhovets
- #143105 - Imad Bougataya
- #174206 - Constantin Drabo
Patches should be developed against the main repository. However, if the main repository does not build or pass validation, then you should can develop your patches against main-golden repository instead.
We'd like to congratulate the following developers who have already graduated from the First Patch program. Here are the graduates of the first session:
- Jonathan Spooner (spoonerj30) fixed issue #180655. Jonathan was mentored by Anuradha Gunasekara.
- Timothy Sparg (tim_sa) fixed issue #119629. Timothy was mentored by Tushar Joshi.
- Victor Herrera (hmvictor) fixed issue #59240. Victor was mentored by Antonio Vieiro.
Here are the graduates of the second session (which is still in progress):
- Ernest Lötter (elotter) fixed issue #197502. Ernest was mentored by Jonathan Spooner.
- Ulrich Cech (UlrichCech) fixed issue #51924. Ulrich was mentored by Emilian Bold.
Advice from our Graduates
Here are some of the ways that our First Patch graduates said that the process for contributing to NetBeans could be improved. We hope to incorporate these suggestions into the relevant parts of netbeans.org.
- When you do a hg clone, you see very little progress from hg itself, this is quite disturbing especially with a remote repository the size of NetBeans. With to slow connections or intermitted access to the repository, the hg progress bar extension is very useful since it allows you to monitor Mercurial's progress.
- It would be helpful to document any coding conventions for properties files, just as there are coding standards for source files.
- There are some additional tests you can -- and should -- run after you've developed your patch. This will help to verify that your fix doesn't break any existing code. Those tests are described here in items 1-5 at the top of the page.
The following are questions you'll be asked upon graduating from the First Patch program. Please keep these in mind as you go through the program so you can take notes along the way.
- What did you find was the most difficult part of creating and submitting your first patch to NetBeans? Do you have any suggestions for how this could be improved; for example, by clarifying the documentation or simplifying a process?
- Now that you've graduated from being a NetBeans user to a NetBeans developer, how would you convince someone else to do the same?
- If you were mentoring a developer who was going to create his or her first patch, what advice would you give before getting started?
Note to self
Tom Wheeler is adding this note to remind himself to always do the following:
- Use hg ci -u email@example.com to record the commit as the person who submitted the patch (I didn't know about this option, and have thus far just included the submitter's name in the comment)
- Be sure to update the CREDITS.html file to add the submitter once he has verified the fix is in NetBeans nightly build (I have done this retroactively for all graduates).