On Sun, Sep 23, 2018 at 5:40 PM Peter Nabbefeld <peter.nabbef...@gmx.de>
wrote:
>
>
> Am 23.09.18 um 17:02 schrieb Jan Lahoda:
> > 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.
>
> CSL and GSF are sth. I've not quite well understood:
> There's some information available how to start, but if it comes to
> details, I'm quickly lost. I'm also not sure, if these are different
>
I think that having a reasonable documentation was traditionally one of the
requirements for a public API modules. (I doubt csl.api went through the
API review process.)
> kinds of language tools or if they're building one on the top of the other.
>
> Probably that's some kind of "implied friend-only" by organization, i.e.
> the lack of information causes it not to be used, though publicly
> available.
> >
> >> 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).
>
> I don't see two major NetBeans releases within 6 months, currently. But,
> depending on the size of some module, IMHO, two or three major releases
> of NetBeans should show most weaknesses of an API to stabilize it. If a
> distinct functionality does not (yet) work as expected, declare it as
> such, and make this part "private" (i.e. a friend-only module only
> accessible from the API to be made public). There're many well-designed
>
Looking at html.editor.lib (another module mentioned in this context), I
wonder if that's considered to work "as expected", or if there are parts
that should be "private". Looking at the module, I am frankly a bit lost on
where should I begin to use it. (I assume I'd add a task using parsing.api
to "text/html", and then see if the Parser.Result I get is
HtmlParsingResult, but why are there 4 more classes with ParseResult in
name?)
After thinking of this for a little, I guess the ideal approach for
changing a friend module to public API module would be if folks interested
in the given API would get together, reviewed the API, improved it as
needed (and as possible, because with 20+ friends, it may be unrealistic to
do certain changes), added documentation, etc. and proposed to make the
updated version public.
It is of course possible to simply remove the "for friends only" flag, but
that's not going to improve the API and documentation.
Jan
APIs in NetBeans, some even integrated twice or more times, just because
> they are managed like the "Holy Gral". One example may be the hinting
> system, which is differently implemented e.g. for Java and HTML. Some
> rules will have to be specified language-specific, but probably some
> parts could be unified.
>
> Regards
> Peter
>
>
> >
> > 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
> >>
> >>
> >>
> >>
>
>
> ---------------------------------------------------------------------
> 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
>
>
>
>
