WIP

Getting ready to contribute to NetBeans

Adhere to the ASF Code of Conduct

Please read the Apache Software Foundation Code of Conduct and adhere to it. Pull Requests that violate the ASF Code of Conduct will be rejected.

Your PR may take time to be reviewed by a committer, in special during release phases, so be patient.

Bootstrapping (need to be done only once)

You will not have write permission to github apache mirror, you need to
fork https://github.com/apache/incubator-netbeans to your own repositories.

You need to clone the forked repository and setup name and mail. This also may help git rebase to fullfil its task.

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

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

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

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

Use branches

You now want to create a Pull Request for a fix or a new feature. Pull Request are not fixed in time. I you change your history the PR will be impacted.

 A PR will be reviewed by committers and they may ask you additional work.To easy your work it's better to create a branches per feature you want to submit as Pull Request.

Creating and pointing at  a new branch from master requires 3 steps

1. git checkout master
2. git branch mywork
3. git checkout mywork

You can then code, commit and push to your forked repository. You can then use the github UI to create a Pull request from your branch.

https://help.github.com/articles/creating-a-pull-request/

You will need an ICLA (Individual Contributor License Agreement) for important modifications.

Commit message related to JIRA issue must start with [NETBEANS-<issue number>]

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:

[NETBEANS-xxx] Improved YAML lexer

Improved ability for night vision and
the robustness on I/O errors.

Oops, forgot to include lic file

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.

<How to squash guide here>

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

Keeping your own fork in sync with Apache GitHub repo

<to be described :  possible link we can use: https://help.github.com/articles/syncing-a-fork/>

git fetch upstream

git checkout master

git merge upstream/master

Tip: Syncing your fork only updates your local copy of the repository. To update your fork on GitHub, you must push your changes

git push origin master

Updating a stale Pull Request

Over time your Pull Request is likely to go stale. A "stale" pull request is one that is no longer up to date with the main line of development, and it needs to be updated before it can be merged into the project. This typically happens because there's meanwhile been changes in main branch on the same files that are included in the PR, thus resulting in a merge conflict.

<to be described :  possible link we can use: https://github.com/edx/edx-platform/wiki/How-to-Rebase-a-Pull-Request>

PR Coding Best Practices

When submitting a PR keep in mind these principles:

1. Please submit an issue to JIRA (https://issues.apache.org/jira/projects/NETBEANS/summary) explaining your setup (platform, tc.), why your PR is needed and a case to reproduce, if possible.
2. In the code, try to be concise and right to the point. Just modify whatever needs to be modified to solve the issue at hand.
3. If your code is complex:
   1.  submit a unit test as well.
   2.  add comments for the most complex parts.
4. Try to keep the code readable, maintainable, easy to debug and performant.
5. When submitting a PR start your commit message with NETBEANS-XYZ, where XYZ is the issue number. By doing so your PR will be automatically associated to the JIRA issue.
6. After submitting a PR, NetBeans committers will review it for approval before being finally merged. This may take some time, so please be patient.

Streaming API considerations

Avoid using unnecessary streaming API constructs. For instance, this code:

for (Transaction commit : SPIAccessor.DEFAULT.getCommits(bag)) {
	SPIAccessor.DEFAULT.check(commit, true);
}

Is perfectly readable and performant, but it could be transformed to the Streaming API equivalent:

SPIAccessor.DEFAULT.getCommits(bag).forEach((commit) -> SPIAccessor.DEFAULT.check(commit, true));

But the resulting code will be slower and more difficult to debug, so the change does not really add more value to the source code.

When using the Streaming API always try to write readable constructs and make the code easy to debug (by splitting complex streaming API constructs in multiple lines, for instance).

Keep explicity typing

Try not to remove typing when using generics with the diamond operator. So, for instance, you could replace

ArrayList<JCVariableDecl> fieldGroup = null;
// lots of lines here...
fieldGroup = new ArrayList<JCVariableDecl>();

With

ArrayList<JCVariableDecl> fieldGroup = null;
// lots of lines here...
fieldGroup = new ArrayList<>();

This is, you could use the diamond operator in the assignment, but this will result in a less readable code. Try to keep explicit typing visible as much as possible, pondering always readability over syntax sugar.

Internationalization

If the source code might be translated to other languages then please add the comment `// NOI18N` to the string literals that must not be translated. Strings to be translated should be properly added to resource bundles.

If the source code is not be translated then avoid adding `// NOI18N` comments to the string literals, this just adds clutter and makes the code less readable.