| //// |
| Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| //// |
| = Contributing Code |
| :jbake-type: page |
| :jbake-tags: community |
| :jbake-status: published |
| :keywords: Submitting pull requests to Apache NetBeans |
| :description: Submitting pull requests to Apache NetBeans |
| :toc: left |
| :toclevels: 4 |
| :toc-title: |
| |
| [[contributing-code]] |
| Contributing code to the Apache NetBeans project is not very different to contributing code for any other Apache software project, |
| so the link:https://www.apache.org/dev/contributors[Apache's Guide for New Project Contributors] is worth a read. |
| |
| We follow link:https://www.apache.org/foundation/policies/conduct.html[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: |
| |
| . Before starting to code, you may want to discuss the problem in the developer mailing list (see xref:../community/mailing-lists.adoc[mailing lists]), giving the reason for submitting your pull request so that it is clear and more experienced members can suggest appropriate solutions/ideas. |
| . All commits must include the author's full name and email address. For *important modifications* you will need to submit an link:https://www.apache.org/licenses/icla.pdf[Individual Contributor License Agreement (ICLA)]. |
| . All new files must include the Apache Software Foundation license header. See any NetBeans source code in case of doubt. |
| . 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. |
| . 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. |
| . 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. |
| . For reviewers: Keep in mind that the contributor wants to fix a problem and has put effort into it. So be polite and focused. |
| . 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. |
| . 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) |
| . 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. |
| . Follow the coding conventions of the file. Your code should match that style and not stand out. For new files, please follow the xref:codeconventions.adoc[code conventions for the NetBeans code base]. |
| . Try to keep the code *readable, maintainable, easy to debug* and *performant*. |
| |
| == Learn to run and debug NetBeans IDE or Platform applications |
| xref:build-run-debug-tutorials.adoc[Watch a series of 5 short videos] (2 minutes on average) or see xref:submit-pr.adoc#develop[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 link:https://github.com/apache/netbeans[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. |
| |
| [source, shell] |
| ---- |
| 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. |
| |
| [source, shell] |
| ---- |
| 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. |
| |
| [source, shell] |
| ---- |
| 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: |
| |
| . Change to the `master` branch with `git checkout master`. |
| . 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 xref:submit-pr.adoc#squash[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 link:https://help.github.com/articles/creating-a-pull-request/[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 link:https://github.com/apache/netbeans/pulls[https://github.com/apache/netbeans/pulls]. |
| |
| The pull request will then be reviewed by the xref:../community/who.adoc[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. |
| |
| [[squash]] |
| === 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: |
| |
| [options="header", cols="1,7"] |
| |=== |
| |#|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. |
| |
| link:https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History[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. |
| |
| [[develop]] |
| == Developing NetBeans with NetBeans |
| These steps assume you have already forked, cloned and configured your NetBeans development repository. |
| |
| . 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_ |
| |
| . 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_ |
| |
| . 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_ |
| |
| . 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_ |
| |
| . 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 |
| |
| . 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]] |
| == Donating Code |
| |
| You may find official information here: link:https://incubator.apache.org/ip-clearance/[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 link:https://incubator.apache.org/ip-clearance/[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. |
| |