Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

8273280: Update README.md and CONTRIBUTING.md for jfx17u #1

Closed
wants to merge 1 commit into from
Closed
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
@@ -1,227 +1,14 @@
Contributing to OpenJFX
=======================
Contributing to OpenJFX 17 Updates
==================================

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.
The OpenJFX 17 Updates repository is _not_ accepting new contributions. If you are looking to contribute to OpenJFX, please visit [openjdk/jfx](https://github.com/openjdk/jfx) instead.

Bug reports
-----------
Important bug fixes that have already been fixed in the mainline can be backported with approval. New fixes should first go into the mainline, and then can be considered for backporting. Approval from one of the project leads is required prior to integrating the fix.

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](https://bugs.openjdk.java.net) 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](https://bugreport.java.com/).
To backport a fix, import the patch from the jfx mainline into a branch of your personal fork of this repo. Then, create a [Backport Pull Request](https://wiki.openjdk.java.net/display/SKARA/Backports#Backports-BackportPullRequests), by creating the PR with the title:

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](https://bugs.openjdk.java.net) 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](https://github.com/openjdk/jfx) and clone it to your local machine. See
the [GitHub help page](https://help.github.com/articles/fork-a-repo) 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](https://www.oracle.com/technetwork/community/oca-486395.html) (OCA). 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](https://wiki.openjdk.java.net/display/OpenJFX/Code+Reviews). If this is a feature request, please note the additional requirements and expectations in the [New features / API additions](https://wiki.openjdk.java.net/display/OpenJFX/Code+Reviews#CodeReviews-NewFeaturesC.Newfeatures/APIadditions.) section of the Code Review Policies doc.

* File a bug in JBS for every pull request

A [JBS](https://bugs.openjdk.java.net) bug ID is needed for every
pull request. If there isn't already a bug filed in JBS, then please
file one at [bugreport.java.com](https://bugreport.java.com/).
A developer with an active OpenJDK ID can file a bug directly in JBS.

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]((https://github.com/openjdk/jfx)), and rebase your branch on top of the latest `master` branch. We prefer your initial changes to be squashed into a single commit. See the [GitHub help page](https://help.github.com/articles/about-git-rebase/) for help. Later, if we ask you to make changes, add them as separate commits. This makes them easier to review.

3. Submit a pull request

Push your local changes to your forked copy of the repository and
[submit a pull request](https://help.github.com/articles/using-pull-requests).
The title of the pull request must start with the 7-digit JBS bug id
(without the `JDK-` prefix), followed by a colon (`:`), then a space,
and finally the bug title as taken from JBS. You should include
additional details about your change in the Description of the pull
request. For example, the following is a valid pull request title:

```
8231326: Update README and CONTRIBUTING docs for Skara
```

The Skara bot will then run `jcheck` on the server to verify the format
of the PR title and check for whitespace errors. Once that passes,
it will automatically send a Request For Review (RFR) email to the
[openjfx-dev](mailto:openjfx-dev@openjdk.java.net) mailing list.
See the
[Skara project page](https://github.com/openjdk/skara#openjdk-project-skara)
for information on `jcheck` and other Skara tools.

TIP: prefix the pull request title with `WIP:` if you aren't yet
ready for it to be reviewed. The Skara bot will not send an RFR
email unless the title starts with a 7-digit bug ID.

Please cross-link the JBS Issue and the pull request. A link to the
JBS issue can be added as part of the pull request's Description. A
link to the PR, can be added as an issue link in the JBS bug. If
you don't have direct JBS access, one of the Project Committers or
Authors will do this for you.

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 `master`, you can merge
`master` 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. The Skara bot will squash your commits into a
single commit, and rebase it onto the target branch when the pull
request is integrated.

4. Code review

All pull requests _must_ be reviewed according to the
[OpenJFX Code Review Policies](https://wiki.openjdk.java.net/display/OpenJFX/Code+Reviews).
It is the responsibility of the Reviewer(s) and the Committer who
will integrate the change to ensure that the code review policies
are followed, and that all concerns have been addressed.

Discussion and review of the pull request can happen either by adding
a comment to the PR itself, or by replying to the mailing list "RFR"
thread. The Skara bot will cross-forward between them.
To approve a pull request, a reviewer must do that in the PR itself.
See the following
[GitHub help page](https://help.github.com/en/articles/reviewing-proposed-changes-in-a-pull-request)
for help on reviewing a pull request.

If any changes
are needed, you would push additional commits to the branch
from which you made the pull request.

The code review continues until there are no unaddressed concerns, and
at least the minimum number of reviewers have approved the PR -- which
is one for low-impact bug fixes and two for enhancements or high-impact
bug fixes.

NOTE: while the Skara tooling will indicate that the PR is
ready to integrate once the first reviewer with a "Reviewer" role
in the project has approved it, this may or may not be sufficient
depending on the type of fix. For example, you must wait for a second
approval for enhancements or high-impact bug fixes.

5. Integrate the pull request

Once the review has completed as described above, you can integrate
the PR.

A. Verify the commit message. The Skara tooling adds a comment with
the commit message that will be used. You can add a summary to the
commit message with the `/summary` command. You can add additional
contributors with the `/contributor` command. Commands are issued
by adding a comment to the PR that starts with a slash `/` character.

B. Issue the `/integrate` command. If you have the "Committer" role
(or higher) in the Project, then the Skara bot will merge the change
with no further action on your part. If you are not a Committer,
then you must get a Committer to sponsor your change. This is often
one of the reviewers who reviewed your PR, but it need not be. The
sponsor will issue the `/sponsor` command after you issue `/integrate`
once they are satisfied that the review criteria have been met.

6. Resolve the JBS bug as "Fixed"

There is currently no automation for resolving JBS bugs, although
a future Skara improvement will automate this. Until then,
the Committer who integrated or sponsored the fix is responsible for
resolving the JBS issue. You do this with the "Resolve" action in JBS,
selecting "Fixed" as the resolution. You also need to add the commit
notification message (minus the list of modified files) as a comment.
This includes the URL of the commit. For example:

```
Changeset: 1de25a49
Author: Kevin Rushforth <kcr@openjdk.org>
Date: 2019-09-23 08:15:36 +7000
URL: https://git.openjdk.java.net/jfx/commit/1de25a49
8231126: libxslt.md has incorrect version string
Reviewed-by: ghb
```


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
`git jcheck`, which is run by the Skara bot:

* 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 &ldquo;auto-format on save&rdquo; 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:

```sh
bash ./gradlew all test
```

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

```sh
bash ./gradlew -PFULL_TEST=true -PUSE_ROBOT=true all test
Backport LONG-COMMIT-HASH
```

Even more documentation on OpenJFX projects and its build system can be found on the
[OpenJFX Wiki](https://wiki.openjdk.java.net/display/OpenJFX/).
where `LONG-COMMIT-HASH` is the long (40 char) commit hash of the fix as found in the main jfx repo. The Skara tooling will then note that it is a backport, and replace the title with the correct issue title.

This comment has been minimized.

@johanvos

johanvos Sep 14, 2021
Collaborator

Should the next parts of the process be explained as well (e.g. optional review if no clean patch, merging?)

This comment has been minimized.

@kevinrushforth

kevinrushforth Sep 14, 2021
Author Member

Good idea, but I'd prefer to do that as a follow-on fix; that change could then be backported to jfx11u (as a clean backport).

This comment has been minimized.

@johanvos

johanvos Sep 14, 2021
Collaborator

makes sense

This comment has been minimized.

@@ -1,22 +1,8 @@
# OpenJFX
# OpenJFX 17 Updates

OpenJFX is an open source, next generation client application platform for desktop, mobile and embedded systems based on JavaSE. It is a collaborative effort by many individuals and companies with the goal of producing a modern, efficient, and fully featured toolkit for developing rich client applications. This is the open source project where we develop JavaFX.

OpenJFX is free software, licensed under [GPL v2 with the Classpath exception](LICENSE), just like the JDK. Anybody is welcome to contribute to this project, port it to other platforms or devices, or do anything else that a free software license allows you to do!

OpenJFX is a project under the charter of the OpenJDK. The [OpenJDK Bylaws](https://openjdk.java.net/bylaws) and [License](LICENSE) govern our work. The OpenJFX project membership can be found on the [OpenJDK Census](https://openjdk.java.net/census#openjfx). We welcome patches and involvement from individual contributors or companies. If this is your first time contributing to an OpenJDK project, you will need to review the rules on [becoming a Contributor](https://openjdk.java.net/bylaws#contributor), and sign the [Oracle Contributor Agreement](https://www.oracle.com/technetwork/community/oca-486395.html) (OCA).

## Issue tracking

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](https://bugs.openjdk.java.net) 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](https://bugreport.java.com/).

## Getting Started

For instructions on building JavaFX, see the [Building OpenJFX](https://wiki.openjdk.java.net/display/OpenJFX/Building+OpenJFX) Wiki page.

For information about downloading and using JavaFX, see the [JavaFX community site](https://openjfx.io/).
This repository has the source code for OpenJFX 17 Update Releases. The main repository for OpenJFX development is [https://github.com/openjdk/jfx](https://github.com/openjdk/jfx).


## Contributing

Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct, and the process for submitting pull requests to us.
Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on submitting backport pull requests to OpenJFX 17. If you are looking to contribute to OpenJFX, please visit [openjdk/jfx](https://github.com/openjdk/jfx) instead.