Skip to content

Latest commit

 

History

History
136 lines (89 loc) · 9.72 KB

CONTRIBUTING.md

File metadata and controls

136 lines (89 loc) · 9.72 KB
Raw

Contributing to OpenJFX on GitHub

OpenJFX is an open source project and we love to receive contributions from our community — you! There are many ways to contribute, from improving the documentation, submitting bug reports and feature requests or writing code which can be incorporated into OpenJFX itself.

Bug reports

If you think you have found a bug in OpenJFX, first make sure that you are testing against the latest version - your issue may already have been fixed. If not, search our issues list in the Java Bug System (JBS) in case a similar issue has already been opened. More information on where and how to report a bug can be found at bugreport.java.com.

It is very helpful if you can prepare a reproduction of the bug. In other words, provide a small test case which we can run to confirm your bug. It makes it easier to find the problem and to fix it.

Provide as much information as you can. The easier it is for us to recreate your problem, the faster it is likely to be fixed.

Feature requests

If you find yourself wishing for a feature that doesn't exist in OpenJFX, you are probably not alone. There are bound to be others out there with similar needs. Many of the features that OpenJFX has today have been added because our users saw the need. Open an issue on our issues list on JBS which describes the feature you would like to see, why you need it, and how it should work.

Contributing code and documentation changes

If you have a bug fix or new feature that you would like to contribute to OpenJFX, please find or open an issue about it first. Talk about what you would like to do. It may be that somebody is already working on it, or that there are particular issues that you should know about before implementing the change. Feature requests, in particular, should be discussed ahead of time and will require significant effort on your part.

We enjoy working with contributors to get their code accepted. There are many approaches to fixing a problem and it is important to find the best approach before writing too much code.

Note that it is unlikely the project will merge refactors for the sake of refactoring. These types of pull requests have a high cost to maintainers in reviewing and testing with little to no tangible benefit. This especially includes changes generated by tools. For example, converting all generic interface instances to use the diamond operator.

Fork and clone the repository

Once you have created a bug report or confirmed its existence on JBS, you will need to fork the repository and clone it to your local machine. See the GitHub help page for help.

Before submitting a pull request

If you are a first time contributor to OpenJFX, welcome! Please do the following before you submit your first pull request:

  • Sign the Contributor Agreement

    In order for us to evaluate your contribution, you need to sign the Oracle Contributor Agreement (OCA). Ultimately, the goal is to send accepted Pull Requests upstream to the OpenJFX repository hosted on openjdk.java.net. We are not asking you to give up your copyright, but to give us the right to distribute your code without restriction. By doing this you assert that the code you contribute is yours to contribute, and not third-party code that you do not own. We ask this of all contributors in order to assure our users of the origin and continuing existence of the code. You only need to sign the OCA once.

  • Read the code review policies

    Please read the entire section below on how to submit a pull request, as well as the OpenJFX Code Review Policies. If this is a feature request, please note the additional requirements and expectations in the New features / API additions section of the Code Review Policies doc.

TIP: A GitHub pull request (PR) should not be the first time we hear about your proposed change to OpenJFX. Unless clearly identified as experimental or work-in-progress (WIP), we will usually close a pull request that isn't associated with an existing bug report. Reading the policies below will help you in getting your change approved.

Submitting your changes via a pull request

Once your changes and tests are ready to submit for review:

  1. Test your changes

    Run the test suite to make sure that nothing is broken.

  2. Rebase your changes

    Update your local repository with the most recent code from the main repository, and rebase your branch on top of the latest develop branch. We prefer your initial changes to be squashed into a single commit. See the GitHub help page for help. Later, if we ask you to make changes, add them as separate commits. This makes them easier to review.

  3. File a bug in JBS

    If there isn't already a bug filed in JBS, then please file one at bugreport.java.com. A JBS bug ID is needed even if you have already filed an issue in the GitHub issue tracker. A GitHub issue can be used as a convenience, but JBS is the official bug database for the OpenJFX Project. Once you submit a pull request, you can add the "github-bug" label on the JBS bug, along with an Issue link to the PR. If you don't have direct JBS access, one of the Project Committers or Authors will do this for you.

  4. Submit a pull request

    Push your local changes to your forked copy of the repository and submit a pull request. In the pull request, choose a title which sums up the changes that you have made, and in the body provide more details about what your changes do. The title should include a JBS Bug ID, which will make it easier for reviewers to cross-reference your pull requests with JBS.

  5. Send an email requesting a code review

    Send a Request For Review (RFR) email to the openjfx-dev mailing list. The email subject should include the JBS bug ID. The body of the review request should contain a pointer to the JBS issue and a pointer to the pull request. Here is an example RFR email:

    Subject: RFR: 8888888: The Bug Synopsis

Please review the fix for The Bug Synopsis:
https://bugs.openjdk.java.net/browse/JDK-8888888
https://github.com/javafxports/openjdk-jfx/pull/12345

Then sit back and wait. There will probably be discussion about the pull request and, if any changes are needed, we would love to work with you to get your pull request merged into OpenJFX.

Please adhere to the general guideline that you should never force push to a publicly shared branch. Once you have opened your pull request, you should consider your branch publicly shared. Instead of force pushing you can just add incremental commits; this is generally easier on your reviewers. If you need to pick up changes from develop, you can merge develop into your branch. A reviewer might ask you to rebase a long-running pull request in which case force pushing is okay for that request. Note that squashing at the end of the review process should also not be done, that will be done when the pull request is integrated via GitHub.

Contributing to the OpenJFX codebase

JDK 11 (at a minimum) is required to build OpenJFX. You must have a JDK 11 installation with the environment variable JAVA_HOME referencing the path to Java home for your JDK 11 installation. By default, tests use the same runtime as JAVA_HOME. Currently OpenJFX builds are running on JDK 11 (recommended) and JDK 12.

It is possible to develop in any major Java IDE (Eclipse, IntelliJ, NetBeans). IDEs can automatically configure projects based on Gradle setup.

The following formatting rules are enforced for source code files by the white-space checker that is run as part of our CI test builds:

  • Use Unix-style (LF) line endings not DOS-style (CRLF)
  • Do not use TAB characters (exception: Makefiles can have TABS)
  • No trailing spaces
  • No files with execute permission

Please also follow these formatting guidelines:

  • Java indent is 4 spaces
  • Line width is no more than 120 characters
  • The rest is left to Java coding standards
  • Disable “auto-format on save” to prevent unnecessary format changes. This makes reviews much harder as it generates unnecessary formatting changes. If your IDE supports formatting only modified chunks that is fine to do.
  • Wildcard imports (import foo.bar.baz.*) are forbidden and may cause the build to fail. Please attempt to tame your IDE so it doesn't make them and please send a PR against this document with instructions for your IDE if it doesn't contain them.
  • Don't worry too much about import order. Try not to change it but don't worry about fighting your IDE to stop it from doing so.

OpenJFX uses Gradle for its build. Before submitting your changes, run the test suite to make sure that nothing is broken, with:

bash ./gradlew all test

If you are changing anything that might possibly affect rendering, you should run a full test with robot enabled:

bash ./gradlew -PFULL_TEST=true -PUSE_ROBOT=true all test

Even more documentation on OpenJFX projects and its build system can be found on the OpenJFX Wiki.