On Sun, Sep 23, 2018 at 3:22 PM Peter Nabbefeld <peter.nabbef...@gmx.de>
wrote:
> 1) Yes, usually the API is reasonably stable in most areas after being
> used as a friend-only API for some releases, so if it is difficult to
> change, this will be a rare event. So, You'll have rarely to do many
> changes and can do some effort in these rare cases, if really necessary.
> IMHO that should be fine.
>
So, I thought one of the modules we are talking about here is csl.api, but
it turned out that *is* a public API currently (which, frankly, scares me a
little bit). So I took a look at gsf.testrunner and the last API change
appears to be from 2015 (according to apichanges.xml), which does not seem
to be *that* long ago.
>
> 2) About Your inline comment: Well, it may happen, that functionality
> will be weighted more than API design. OTOH, I'd see this as an issue
> for a compatibility layer: Let the old API stay alive, while creating a
> new one. Then deprecate it, and remove the compatibility layer one or
> two major releases of NB later.
>
This way I'd expect modules to be stable, but also more usable by the
> community.
>
Given two major release may be 6 months in our current scheme, this sounds
neither particularly stable, nor particularly convenient for someone doing
the change (creating a compatibility layer is likely to have a fairly high
cost).
Jan
>
> Kind regards
>
> Peter
>
>
> Am 23.09.18 um 13:49 schrieb Jan Lahoda:
> > So, if I understand correctly, the view is a combination of c) ("it is OK
> > if doing changes to the API is difficult", like writing compatibility
> > layers, more elaborate migration tutorials, updating existing plugins
> etc.)
> > and b) (making an occasional incompatible change).
> >
> > I think I am fine with that, I just want to ensure the consequences are
> > understood. It is of course absolutely possible that a specific API won't
> > need any enhancements, and so will be fine.
> >
> > One more comment inline.
> >
> > On Sun, Sep 23, 2018 at 12:55 PM Peter Nabbefeld <peter.nabbef...@gmx.de
> >
> > wrote:
> >
> >> The problem here is:
> >>
> >> 1. If every API is friend-only, nobody will be able to depend on those
> >> without first becoming a friend. Or You have to depend on implementation
> >> version. So, these APIs will never be reviewed by the broader community
> >> and will never be ready for usage.
> >>
> >
> >> 2. If the API is public, You may break other implementors plugins.
> >> You'll usually never do that to just annoy them, but because You've got
> >> some serious problem without changing it. As a result, the API should
> >> become more stable, more usable, and of better quality in general.
> >>
> > Not sure about this: when an API is not designed to be enhancible
> > compatibly, and is not sufficient (i.e. needs to be enhanced), I suspect
> > preference will be given to making the change compatibly, even at the
> cost
> > of making the API less nice. So, over time, the API will probably be more
> > complete, but possibly less clean.
> >
> > Thanks,
> > Jan
> >
> > Probably, for the time the major version of NB doesn't change, there
> >> should be a compatibility layer, if possible.
> >>
> >> 3. If the API changes, there needs of course to be a migration tutorial,
> >> which must be upgraded if there are still any questions around about how
> >> to upgrade the plugin.
> >>
> >> 4. Plugin developers are: plugin developers, so it should not be a big
> >> issue for them to update their dependent module, if there's a tutorial.
> >>
> >> 5. As sometimes developers loose interest in further maintaining their
> >> plugin, there should be the source available somewhere, so other
> >> developers could take care of those. Ideally, the plugins should also be
> >> licensed under AL2.0, so they could be supplied in some Apache contrib
> >> repository.
> >>
> >> So, IMHO modules should be friend-only for a maximum of 2 or 3 releases.
> >> After this, I'd expect them to be reasonable stable to make them public,
> >> so the community could experiment with those and probably make proposals
> >> for a better API. If the API changes then, most developers depending on
> >> the module will even be happy about the new possibilities. But they
> >> should also tell, if some change may make their usage of the module
> >> impossible, of course, so the problems could be considered early.
> >>
> >> Kind regards
> >>
> >> Peter
> >>
> >>
> >>
> >> Am 23.09.18 um 12:04 schrieb Jan Lahoda:
> >>> On Sun, Sep 23, 2018 at 11:03 AM Christian Lenz <
> christian.l...@gmx.net>
> >>> wrote:
> >>>
> >>>> Hey guys,
> >>>>
> >>>> please see my last 3 comments of this ticket. It explains, why it is
> >>>> important to have public APIs instead of Friends:
> >>>>
> >>
> https://issues.apache.org/jira/browse/NETBEANS-1035?focusedCommentId=16574478&page=com.atlassian.jira.plugin.system.issuetabpanels%3Acomment-tabpanel#comment-16574478
> >>>>
> >>> My personal opinion only.
> >>>
> >>> I think noone doubts the a public API is better for plugins. However, I
> >>> think that it is necessary that at least one of the following is true:
> >>> a) someone signs up to make a proper public API, that we will be able
> to
> >>> enhance compatibly
> >>> b) we accept that there are smaller or bigger incompatible API changes
> >>> (size of the incompatible change depends on the nature of the change
> and
> >> of
> >>> the existing API)
> >>> c) we accept that some changes to the API will be very difficult to do
> >>> (compatibly), maybe even so difficult that they won't be made (so
> >> difficult
> >>> that noone will sign up to do the change)
> >>>
> >>> So, I wonder what are the views of others on these.
> >>>
> >>> Thanks,
> >>> Jan
> >>>
> >>>
> >>>> The Thing is, no one know, what other nice Plugins will come in the
> >>>> future, but everytime, someone creates a Plugin which Needs to be
> >> friend,
> >>>> depends on only the next release that someone adds it. That means,
> that
> >>>> this Plugin will first work only for the next release, if someone
> >> decided
> >>>> to add this Plugin as a friend. Same happens for every other Plugins
> >> that
> >>>> Comes later.
> >>>>
> >>>> It is not that everytime a user want to use the newest IDE, often
> >> someone
> >>>> stays at the IDE if there is Nothing really new for him/her to Change
> >>>> update. That means, that he/she could miss the Plugin, if it is
> relevant
> >>>> for him. In this release.
> >>>>
> >>>> And what happens, if someone removes the Plugin as a friend? That
> >> happens
> >>>> for Geertjans KendoUI Plugin. The Plugin worked some versions before,
> >> not
> >>>> now anymore, because it was removed from being a friend.
> >>>>
> >>>> Making APIs public makes much more sense for 3rd-party Plugin
> >> developers.
> >>>> I think HTML, JS, CSS, C/C++ PHP and whatever is there is stable
> enough
> >> for
> >>>> years to say: yes, make them public. And will there some exceptions,
> >> that
> >>>> the devs figure out, someone can fix it Maybe as a patch or for the
> next
> >>>> release, which is acceptable.
> >>>>
> >>>>
> >>>> Cheers
> >>>>
> >>>> Chris
> >>>>
> >>>>
> >>>>
> >>>> Von: Laszlo Kishalmi
> >>>> Gesendet: Sonntag, 23. September 2018 04:45
> >>>> An: dev@netbeans.incubator.apache.org
> >>>> Betreff: Re: Public vs. Friend API Reloaded (Summary)
> >>>>
> >>>> Hi all,
> >>>> This list is what we have inside the current codebase (Without Yenta
> on
> >>>> other locations.)
> >>>> I put those here which have 10+ friend marked. (The complete list is
> >>>> attached)
> >>>> Upon this list it could be a good choice to try make the following
> >> public
> >>>> (maybe for NetBeans 10):
> >>>> • gsf.testrunner
> >>>> • gsf.testrunner.ui
> >>>> I know that a few external language plugins are using those as well,
> and
> >>>> the API is quite a good shape anyway.
> >>>> What do you think?
> >>>> Generated using: find . -name project.xml -exec grep -H -c friend\> {}
> >>>> \;|sort -r -gt : -k 2 |grep -v :0
> >>>> ./ide/dlight.nativeexecution/nbproject/project.xml:147
> >>>> ./ide/dlight.nativeexecution.nb/nbproject/project.xml:145
> >>>> ./ide/web.common/nbproject/project.xml:68
> >>>> ./ide/gsf.testrunner/nbproject/project.xml:40
> >>>> ./php/php.api.phpmodule/nbproject/project.xml:39
> >>>> ./java/java.api.common/nbproject/project.xml:39
> >>>> ./ide/options.editor/nbproject/project.xml:39
> >>>> ./java/maven/nbproject/project.xml:37
> >>>> ./enterprise/j2ee.common/nbproject/project.xml:34
> >>>> ./profiler/profiler.api/nbproject/project.xml:32
> >>>> ./profiler/lib.profiler/nbproject/project.xml:32
> >>>> ./java/maven.embedder/nbproject/project.xml:31
> >>>> ./webcommon/web.clientproject.api/nbproject/project.xml:29
> >>>> ./profiler/lib.profiler.common/nbproject/project.xml:29
> >>>> ./ide/gsf.testrunner.ui/nbproject/project.xml:28
> >>>> ./php/php.api.executable/nbproject/project.xml:27
> >>>> ./ide/html.editor.lib/nbproject/project.xml:26
> >>>> ./enterprise/j2ee.api.ejbmodule/nbproject/project.xml:25
> >>>> ./ide/web.browser.api/nbproject/project.xml:24
> >>>> ./ide/lib.terminalemulator/nbproject/project.xml:24
> >>>> ./profiler/lib.profiler.ui/nbproject/project.xml:23
> >>>> ./java/maven.model/nbproject/project.xml:23
> >>>> ./java/j2ee.core.utilities/nbproject/project.xml:23
> >>>> ./enterprise/websvc.jaxwsmodel/nbproject/project.xml:23
> >>>> ./ide/team.commons/nbproject/project.xml:22
> >>>> ./ide/html.editor/nbproject/project.xml:22
> >>>> ./profiler/profiler/nbproject/project.xml:21
> >>>> ./platform/libs.jna/nbproject/project.xml:21
> >>>> ./php/php.api.editor/nbproject/project.xml:21
> >>>> ./java/java.preprocessorbridge/nbproject/project.xml:20
> >>>> ./ide/web.common.ui/nbproject/project.xml:20
> >>>> ./ide/terminal/nbproject/project.xml:20
> >>>> ./ide/terminal.nb/nbproject/project.xml:20
> >>>> ./java/j2ee.persistenceapi/nbproject/project.xml:19
> >>>> ./enterprise/javaee.specs.support/nbproject/project.xml:19
> >>>> ./webcommon/javascript2.lexer/nbproject/project.xml:17
> >>>> ./ide/xml.multiview/nbproject/project.xml:17
> >>>> ./ide/versioning.util/nbproject/project.xml:17
> >>>> ./ide/code.analysis/nbproject/project.xml:17
> >>>> ./php/php.api.framework/nbproject/project.xml:16
> >>>> ./ide/xml.text/nbproject/project.xml:16
> >>>> ./ide/versioning.core/nbproject/project.xml:16
> >>>> ./webcommon/javascript2.types/nbproject/project.xml:15
> >>>> ./platform/core.startup.base/nbproject/project.xml:15
> >>>> ./ide/editor.settings.storage/nbproject/project.xml:15
> >>>> ./enterprise/websvc.clientapi/nbproject/project.xml:15
> >>>> ./enterprise/web.project/nbproject/project.xml:15
> >>>> ./websvccommon/websvc.jaxwsmodelapi/nbproject/project.xml:14
> >>>> ./webcommon/javascript2.editor/nbproject/project.xml:14
> >>>> ./platform/core.startup/nbproject/project.xml:14
> >>>> ./java/j2ee.persistence/nbproject/project.xml:14
> >>>> ./ide/xml.axi/nbproject/project.xml:14
> >>>> ./enterprise/websvc.jaxwsapi/nbproject/project.xml:14
> >>>> ./websvccommon/websvc.saas.api/nbproject/project.xml:13
> >>>> ./java/whitelist/nbproject/project.xml:13
> >>>> ./enterprise/websvc.core/nbproject/project.xml:13
> >>>> ./platform/o.n.core/nbproject/project.xml:12
> >>>> ./ide/web.webkit.debugging/nbproject/project.xml:12
> >>>> ./ide/dlight.terminal/nbproject/project.xml:12
> >>>> ./webcommon/javascript2.model/nbproject/project.xml:11
> >>>> ./php/php.api.annotation/nbproject/project.xml:11
> >>>> ./java/maven.indexer/nbproject/project.xml:11
> >>>> ./java/javaee.injection/nbproject/project.xml:11
> >>>> ./java/j2ee.metadata.model.support/nbproject/project.xml:11
> >>>> ./ide/hudson/nbproject/project.xml:11
> >>>> ./extide/options.java/nbproject/project.xml:11
> >>>> ./enterprise/j2ee.sun.dd/nbproject/project.xml:11
> >>>> ./enterprise/glassfish.common/nbproject/project.xml:11
> >>>> ./platform/o.n.bootstrap/nbproject/project.xml:10
> >>>> ./java/java.testrunner/nbproject/project.xml:10
> >>>> ./java/java.j2seproject/nbproject/project.xml:10
> >>>>
> >>>>
> >>
> ./ide/xml.schema.completion/test/unit/src/org/netbeans/modules/xml/schema/completion/resources/project.xml:10
> >>>> ./ide/jumpto/nbproject/project.xml:10
> >>>> ./enterprise/web.jsf/nbproject/project.xml:10
> >>>> ./enterprise/web.jsfapi/nbproject/project.xml:10
> >>>>
> >>>> On 09/21/2018 05:26 PM, Tim Boudreau wrote:
> >>>> You may want to survey modules on Github that use implementation
> >>>> dependencies or use Uenta to bypass them. For example, I've been
> >> tweaking
> >>>> the rust module from github, which does tag with a couple of csl
> >> modules.
> >>>> Those should count toward "friends".
> >>>>
> >>>> -Tim
> >>>>
> >>>> On Fri, Sep 21, 2018 at 8:01 PM Laszlo Kishalmi <
> >> laszlo.kisha...@gmail.com
> >>>> wrote:
> >>>>
> >>>> Dear all,
> >>>>
> >>>> I'd like to summarize whet happened on the "API Friendliness" issue:
> >>>>
> >>>> We collected a number of possible options on our previous discussions
> >> at:
> >>>>
> >>
> https://cwiki.apache.org/confluence/display/NETBEANS/Public+vs+Friend+API
> >>>> Commenting these options remained really silent though. This means our
> >>>> Friend APIs most likely stay as they are now.
> >>>>
> >>>> I must acknowledge that adding new friends to an existing API is
> easier
> >>>> than ever having NetBeans under Apache umbrella.
> >>>>
> >>>> I plan not to give up on making some APIs public though. Regarding the
> >>>> low interest of making something big around this area, I think the
> most
> >>>> viable solution is:
> >>>>
> >>>> Option 4: Make Module Public when There is more than a Certain Number
> of
> >>>> Friend Dependencies.
> >>>>
> >>>> So sometime in the future I'm going to create a list of how many
> friends
> >>>> a module does have and share the list with you.
> >>>>
> >>>>
> >>>> Thank you all who participated in this effort!
> >>>>
> >>>> Laszlo Kishalmi
> >>>>
> >>>>
> >>>> ---------------------------------------------------------------------
> >>>> To unsubscribe, e-mail: dev-unsubscr...@netbeans.incubator.apache.org
> >>>> For additional commands, e-mail:
> dev-h...@netbeans.incubator.apache.org
> >>>>
> >>>> For further information about the NetBeans mailing lists, visit:
> >>>> https://cwiki.apache.org/confluence/display/NETBEANS/Mailing+lists
> >>>>
> >>>>
> >>>>
> >>>> --
> >>>> http://timboudreau.com
> >>>>
> >>>>
> >>>>
> >>>>
> >>
> >> ---------------------------------------------------------------------
> >> To unsubscribe, e-mail: dev-unsubscr...@netbeans.incubator.apache.org
> >> For additional commands, e-mail: dev-h...@netbeans.incubator.apache.org
> >>
> >> For further information about the NetBeans mailing lists, visit:
> >> https://cwiki.apache.org/confluence/display/NETBEANS/Mailing+lists
> >>
> >>
> >>
> >>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscr...@netbeans.incubator.apache.org
> For additional commands, e-mail: dev-h...@netbeans.incubator.apache.org
>
> For further information about the NetBeans mailing lists, visit:
> https://cwiki.apache.org/confluence/display/NETBEANS/Mailing+lists
>
>
>
>
