More community participation in JavaFX

[Kevin Rushforth]

To: OpenJFX Developers

We are looking to grow the community of contributors to the OpenJFX 
project, especially serious contributors who will stick around long 
enough to become reviewers, to help us keep the platform vibrant. To 
this end we are looking at ways to encourage more participation and make 
it easier for interested folks to contribute.

We are specifically looking to discuss ideas around the following areas:

* Easing barriers to contribution (e.g., making JavaFX easier to build, 
better documentation, making it easier to test changes)

* Code review policies

* API / feature review policies

* Code review tools (we currently use webrev, but that isn't set in stone)


To keep this thread productive, the following are explicitly out of scope:

* Discussion of specific features or bugs that you would like to 
implement (or wish someone else would)

* Discussion about platform support

* Discussion about version control systems (e.g., hg versus git), 
hosting of the OpenJFX repos and bug database (e.g., OpenJDK versus 
github), etc...at least for now. We are aware of the potential benefits 
of such changes, but we'd like to focus our efforts on higher-leverage 
things we can do in the short term.

* Discussion about the requirement of a signed OCA to become a contributor

* Off-topic or tangential commentary about OpenJFX that isn't directly 
related to the topic at hand


As a starting point for discussion, here are some areas I think need 
improvement; I'm sure there are others:

I. Helping contributors get started

It isn’t as easy to get started with OpenJFX as it should be. We want to 
make it easier for potential OpenJFX contributors to get started. Here 
are some ideas that I think might help:

* Improve the build instructions / Wiki (I made a first start, but there 
is much more to be done)

* Make the build itself more resilient where possible, and provide 
better error messages, specifically when dealing with native compilers 
and libraries

* Add an option to skip building all native code and use prebuilt 
binaries (like we do already for media and webkit); this is tracked by 
JDK-8092279, but it hasn’t been looked at recently

* Make it easier to build / test your local OpenJFX build using an 
OpenJDK build (currently the only way to do this is to build OpenJDK 
locally, after using configure to point to your just-built javafx.* 
modules).

* Provide step-by-step instructions for how to make a contribution, 
including testing requirements; a lot of the pieces are there, but are 
out of date or scattered in several places. As part of this, we could 
have a section on how to contribute docs, samples or tests, since that 
is often a good place to start.

* Provide a sandbox environment where contributors can discuss and test 
ideas. For example, an OpenJFX mirror on github, potentially connected 
to AdoptOpenJDK.


II. Code reviews and API reviews

Code reviews are important to maintain high-quality contributions, but 
we recognize that not every type of change needs the same level of 
review. Without lowering our standards of quality, we want to make it 
easier to get low-impact changes (simple bug fixes) accepted.

There are three categories of changes, each of which might merit a 
different review standard:

1. Low-impact bug fixes. These are typically isolated bug fixes with 
little or no impact beyond fixing the bug in question; included in this 
category are test fixes (including new tests) doc fixes, and fixes to 
sample applications (including new samples).

2. Higher impact bug fixes or RFEs. These include changes to the 
implementation that potentially have a performance or behavioral impact, 
or are otherwise broad in scope. Some larger bug fixes will fall into 
this category, as will fixes in high-risk areas (e.g., CSS).

3. New features / API additions. In addition to reviewing the 
implementation, we will need a separate approval process for the new API 
/ feature (such as the CSR, which is what we use now, or a similar process).

We take compatibility seriously, so anything that adds new API needs to 
be done with an eye towards supporting it for at least 10 years. We 
don't want to add new public API without that level of commitment. Every 
new feature forecloses on alternate future features. Significant effort 
must be taken to think about "if we did this, what could it interact 
with in the future?" Also, anything with a large potential impact on 
performance or behavioral compatibility needs to be looked at carefully.

Put another way, we want to encourage thinking about new features or new 
API in terms of a design / stewardship process; to think in terms of 
questions like "what's the right thing for JavaFX in the next 10+ years" 
rather than "here's some code that solves my problem, please take it".


As a stake in the ground, I might suggest the following:

* All changes need at least one reviewer other than the person making 
the change who can evaluate the change for correctness and consistency. 
For simple bug fixes, a single reviewer may be sufficient. Of course, 
one of our big challenges in all this is: "how do we grow more 
reviewers?", by which I mean "how do we facilitate getting contributors 
with enough expertise in a given area to eventually be able to 
effectively review contributions from others?"

* We need clear criteria for the other two categories that balance 
process efficiency with the desire to maintain compatibility and 
stability. API changes need to be approved by a lead. My thought is to 
combine the last two into a single category for purposes of reviewing 
the implementation. Anything that affects public API or behavioral 
compatibility will require CSR or similar approval, over and above the 
implementation review, which seems sufficient.

* I recommend that we formalize the concept of reviewers, using the 
OpenJDK Reviewer role for the Project. We might also consider if we want 
to make any changes to the criteria used by the JDK Project for becoming 
an OpenJFX Project Author, Committer, and Reviewer. The OpenJDK bylaws 
allow projects a fair degree of latitude to define these criteria, so we 
might consider making some modifications. For example, we might make it 
somewhat easier for a Contributor to become an Author, or for a 
Committer to become a Reviewer. I have some thoughts on this, but want 
to hear from others first.


I look forward to feedback on this proposal, and hope it will spark a 
productive discussion.

-- Kevin Rushforth, OpenJFX Project Lead