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
