Contributing Code

Contributing code to the Apache NetBeans project is not very different to contributing code for any other Apache software project, so the Apache’s Guide for New Project Contributors is worth a read.

We follow the Apache Code of Conduct, and expect all contributors to follow it as well.

We appreciate new contributors to adhere to the following guidelines, to make things easier for all of us:

  1. Before starting to code, you may want to discuss the problem in the developer mailing list (see mailing lists), giving the reason for submitting your pull request so that it is clear and more experienced members can suggest appropriate solutions/ideas.

  2. All commits must include the author’s full name and email address. For important modifications you will need to submit an Individual Contributor License Agreement (ICLA).

  3. All new files must include the Apache Software Foundation license header. See any NetBeans source code in case of doubt.

  4. All commits must contain a meaningful commit message. A meaningful commit message holds in the first line a summary of the commit and in the body (beginning on the third-line) an explanation of what was changed and why it was done. Remember that in the future this commit message is most probably the only source of information why a change was committed to the code base. If the commit fixes a reported issue, the summary line should hold the issue number and title [NETBEANS-XXX] Maven pom.xml file corrupted after inserting dependecies for example.

  5. A Pull Request can consist of multiple commits. These commits should group the changes into meaningful entities. Fixup commits should be squashed into the base commit they fix.

  6. For contributors: Be prepared to be asked questions about your PR

    • A reviewer might have questions and you should be able to answer why you did a fix in a certain way and why it is safe and appropriate.

    • Remember that the review sometimes takes as long, as creating a patch in the first place.

    • Good commit messages help as they anticipate questions.

  7. For reviewers: Keep in mind that the contributor wants to fix a problem and has put effort into it. So be polite and focused.

  8. Don’t change code that is correct and works.

    • Consider a simple loop. In many cases you can switch between for-loop, for-each-loop and stream construct. All are valid solutions, don’t change the code if it is not broken.

    • An improvement is a different case. For example a try-with-resource construct is in general more correct than the try-finally construct which many developers fail to implement correctly.

    • Constructs leading to warnings from the javac are also good candidates for simple fixes.

  9. Run unit tests and, if you introduce new feature/fixes, add unit tests. So before you start your work, check that unit tests for the module you are working on run correctly and after you are done keep doing.

    • If unit tests fail, fixing these would be a good addition to the code base (it would be good to use a separate commit for this)

  10. Keep your pull requests up-to-date. When the PR can’t be merged directly (it can happen that changes are introduced into the code base, that conflict with your PR) you should then update it accordingly.

  11. Follow the coding conventions of the file. Your code should match that style and not stand out. For new files, please follow the code conventions for the NetBeans code base.

  12. Try to keep the code readable, maintainable, easy to debug and performant.

Learn to run and debug NetBeans IDE or Platform applications

Watch a series of 5 short videos (2 minutes on average) or see Developing NetBeans with NetBeans for help on how to build, run and debug the NetBeans IDE or any NetBeans platform application from sources.

Contributing to Apache NetBeans in GitHub

Bootstrapping (do this once)

Since you don’t have write permissions to the GitHub apache mirror, you need to fork https://github.com/apache/netbeans in GitHub, this is done using the "fork" button on the top right of the GitHub page.

You then need to clone the forked repository in your computer.

cd <your-project-dir>
git clone https://github.com/<your-username>/netbeans.git

At this stage it is a good idea to check that you can build and run NetBeans.

cd netbeans
ant
ant tryme

Finally, in your computer, you need to setup your name and email in GitHub. This will also help git to rebase in order to fulfill its task.

git config --global user.name "John Doe"
git config --global user.email "john@doe.org"

The --global argument can be removed if you want to setup only the current repository.

Also add the Apache NetBeans project as your upstream in order to submit PRs:

git remote add upstream https://github.com/apache/netbeans.git

After all this you’re ready to submit pull requests.

Branching and submitting pull requests

Before you can start modifying or upgrading the NetBeans code in your repository you should create a git branch, like this:

  1. Change to the master branch with git checkout master.

  2. Create a branch with git checkout -b mybranch (or, using two commands: git branch mybranch and git checkout mybranch).

You are now ready to start modifying the NetBeans code. Use git commit when appropriate.

  • Use git push -u origin mybranch to create and push the mybranch branch in your GitHub fork.

  • Use git push origin mybranch afterwards.

If you have submitted many different commits it’s a good idea to squash them together. See squashing commits on pull requests for help on this.

Once your code is ready to review create a pull request using the GitHub interface. See https://help.github.com/articles/creating-a-pull-request/ for help.

Be patient

Once your pull request is submitted to Apache NetBeans it will be visible in this address https://github.com/apache/netbeans/pulls.

The pull request will then be reviewed by the NetBeans Team, once there’s time to do so. Please be patient, as this may take some time, depending on other duties and ongoing work.

Squashing commits on a Pull Request

Before submitting your Pull Request it should ideally consist of a single commit only. Consider you’ve done the following on your branch:

# Commit

X

[NETBEANS-XXX] Improved YAML lexer. Improved ability for night vision and the robustness on I/O errors.

Y

Oops, forgot to include lic file

Z

Javadoc update - corrected spelling

If the PR is merged into master as-is then all these commits will be in the master too, forever. Therefore, in this example, all three commits should be squashed into one so that only X is left.

https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History

After submission (and certainly after someone starts reviewing the PR) you shouldn’t touch the PR’s history.

Developing NetBeans with NetBeans

These steps assume you have already forked, cloned and configured your NetBeans development repository.

  1. Configure NetBeans

    • Open your currently installed NetBeans

    • Enable the Developing NetBeans plugin.

      • Open the Plugins dialog (Tools→Plugins)

      • Find Developing NetBeans in either the Available or Installed list

      • If it is Available select its checkbox and click Install

      • If it is Installed but not Active, select its checkbox and click Activate

  2. Add your development repository as a NetBeans Platform

    • Open the NetBeans Platform Manager (Tools→NetBeans Platforms)

    • Click Add Platform …​

    • Navigate to <your-project-dir>/netbeans/nbbuild/ and select netbeans

    • Click Next >

    • Click Finish

    • Select the Sources tab

    • Click Add ZIP/Folder …​

    • Select <your-project-dir>/netbeans and click Open

    • Close NetBeans Platform Manager

  3. Create a new project (File→New Project…​)

    • In Categories: select Java with Ant / NetBeans Modules

    • In Projects: select Module Suite

    • Click Next >

    • Enter a Project Name: (e.g. NB-IDE-DEV)

    • Optionally change the Project Location:

    • Click Finish

  4. Locate the source code for your development repository

    • Open the Favorites window (Window→Favorites)

    • Select Add to Favorites…​ in the right-click context menu

    • Select <your-project-dir>/netbeans and click Add

  5. Set a breakpoint in the source code. As a start try the entry point public static void main (String args[])

    • In the Favorites tab navigate to platform/o.n.bootstrap/src/org/netbeans and open Main.java

    • Set a breakpoint

  6. Start the debugger

    • Select your IDE project (e.g. NB-IDE-DEV) from the Run→Set Main Project menu

    • Start the debugger :

      • Debug→Debug Main Project menu,

      • or Click the Debug toolbar item

      • or Ctrl+F5

Donating Code

You may find official information here: https://incubator.apache.org/ip-clearance/

Donator can use pull request as show above. (squashed for having a better readability of the hash)

In order to accept a donation the Apache NetBeans PMC should do a vote to accept the intention of donation.

PMC will have to setup a form to append the list at https://incubator.apache.org/ip-clearance/ and open an issue to track donation.

Donator must ensure that the following step are ok (PMC member need to check):

  • His company fill and send a Software Grant and/or corporate CLA if applicable

  • Any contributor involved in donated code has an individual CLA

  • License are correct and compatible with Apache.

Once every step are ok, PMC will call a lazy vote at general@incubator.

If no issue are detected the code can be merged.