Re: Proposal: JavaFX Incubator Modules
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
Re: Proposal: JavaFX Incubator Modules
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
Re: Proposal: JavaFX Incubator Modules
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
Re: Proposal: JavaFX Incubator Modules
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
Re: Proposal: JavaFX Incubator Modules
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
Proposal: JavaFX Incubator Modules
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
