I updated the Incubator Modules proposal to address Phil's feedback,
along with updating the example incubator module:
https://github.com/kevinrushforth/jfx/blob/javafx.incubator/INCUBATOR-MODULES.md
https://github.com/openjdk/jfx/pull/1375
-- Kevin
On 2/22/2024 2:32 PM, Kevin Rushforth wrote:
Something like this might be reasonable as long as we also add "and
hasn't been modified in the current release". I could easily image the
case where an incubating feature goes into, say JavaFX 26 in March,
and by the time feedback comes in that prompts a change in the API,
it's July or August already, meaning that any changes will go into
JavaFX 28.
The time between when a feature first released (in a GA release) and
the feature freeze for the next release is only a little over 3 months
(which is why most features will incubate for at least two releases).
-- Kevin
On 2/22/2024 1:08 PM, Philip Race wrote:
W.r.t to (3) perhaps we could include in the write up an expectation
that continued incubation implies continued updates.
Meaning if there are no updates in a release then that either means
it is ready to be final next time round, or that the
author is no longer actively pursuing it and this should inform the
Project Lead as to what action should be taken next.
-phil.
On 2/21/24 1:55 PM, Kevin Rushforth wrote:
These are all good points.
1. I agree. This seems like a good idea for all the reasons you mention.
2. I'll add the additional information. And I like your suggestion
to require a JEP (*) to either drop or finalize an incubating feature.
3. Yes, I was deliberately vague on what constitutes a reasonable
amount of time. Given that we are changing the default to
"re-incubate" it does make sense to have a "soft timeout" so
incubating features don't incubate forever without an intentional
action to keep them alive.
I'll update the proposal accordingly.
Thanks.
-- Kevin
(*) We don't exactly follow the JEP process as described in JEP 2,
but for larger features we expect a proposal that touches on the
important points in a JEP-like document and is discussed on the
mailing list. That's what we mean when we say "needs a JEP".
On 2/21/2024 9:47 AM, Philip Race wrote:
1) The first thing that jumps out at me is the namespace :
javafx.incubator
The JDK's JEP 11 says "An incubator module is identified by
the|jdk.incubator.|prefix in its module name"
It says the same about the packages inside the module.
"An incubating API is identified by the|jdk.incubator.|prefix in
its exported package names".
This is to avoid using the standard namespace prefixes for JDK of
java. and javax. used for final APIs/modules.
So similarly I think JavaFX incubators should avoid the javafx.
prefix and I suggest "jfx." be used instead.
This closely mirrors the "jdk." used in JEP 11, taking "java" out
of the prefix and making it entirely an acronym,
for both module and package names.
The pain of updating your code when the API goes final can be eased
by IDEs and is something you would
need to do anyway because "incubator" is in all the names in either
case.
2) The second thing is you don't say what the steps are to promote
the incubating module to final.
JEP 11 says a new JEP is needed for that, but it also says a new
JEP is needed to re-incubate
which is something JavaFX will not require.
So do you expect it will be a new JEP for that ?
I think that would be best to do that as the JEP to propose the
incubator could be several years old and stale by then.
You also don't say what it takes to drop it.
So how about the basic process is that the first JEP simply
proposes the incubating module, once
it is in as you say it evolves by normal RFEs across releases ?
Then when it is EITHER ready to go final OR be removed, a new JEP
must be proposed for that.
A removal JEP should generally be quite short :-)
So I suggest to add a sentence along those lines to the proposal.
"To either make the API of an incubating module final, or to remove
it, then a new JEP should be submitted,
referencing the incubator JEP".
3) The "reasonably small number of JavaFX releases" is I am sure
intentionally vague, but perhaps
we could say
(1) Incubators which span beyond a 24 month period and are not yet
ready will need
a simple public approval from the project lead to remain for some
additiional period at the discretion
of the Project Lead by adding a simple comment in the JEP,
otherwise the Project Lead will submit a removal JEP and
(2) the submitter of the JEP can propose to remove it at any time.
-phil.
On 2/21/24 9:37 AM, Kevin Rushforth wrote:
JEP 11 [1] defines a process for delivering non-final JDK APIs in
incubator modules.
Similarly, some JavaFX APIs would benefit from spending a period
of time in a JavaFX release prior to being deemed stable. I
propose JavaFX incubator modules as a means of putting non-final
API in the hands of developers, while the API progresses towards
either finalization or removal in a future release. This is
especially useful for complex features with a large API surface.
The JavaFX proposal is largely the same as the JDK one, but has
some important differences.
Please take a look at the preliminary proposal [2]. I have also
created a Draft PR [3], for illustrative purposes only, to show
how this might work.
Please reply to this message with any feedback.
Thanks.
-- Kevin
[1] https://openjdk.org/jeps/11
[2]
https://github.com/kevinrushforth/jfx/blob/javafx.incubator/INCUBATOR-MODULES.md
[3] https://github.com/openjdk/jfx/pull/1375
