| //// |
| 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, it is a good practice to open an issue (PTR) first in our link:https://issues.apache.org/jira/projects/NETBEANS/summary[JIRA] instance, and discuss the problem in the developer mailing list (see link:/community/mailing-lists.html[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 link:https://netbeans.org/community/guidelines/code-conventions.html[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 |
| link:/participate/build-run-debug-tutorials.html[Watch a series of 5 short videos] (2 minutes on average) showing 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. |
| |
| 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. Note that the commit message related to JIRA issues must start with `[NETBEANS-<issue number>]`. |
| |
| - 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 link:#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 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 link:/community/who.html[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. |
| |
| 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. |
| |
| [[donating-code]] |
| = 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 a JIRA 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. |
| |