Re: [cross-project-issues-dev] HTMLPrinter is Broken

[Lars Vogel <lars.vogel@xxxxxxxxxxx>]

> I say that, as long as existing internals can be used, they are de facto API.

That is incorrect and the current meaning is well defined. See
x-internal description in the help
https://help.eclipse.org/mars/index.jsp?topic=%2Forg.eclipse.platform.doc.isv%2Freference%2Fmisc%2Fbundle_manifest.html

Best regards, Lars

On Thu, Jan 25, 2018 at 1:50 PM, Mikaël Barbero
<mikael.barbero@xxxxxxxxxxxxxxxxxxxxxx> wrote:
>
> Le 25 janv. 2018 à 10:22, Lars Vogel <lars.vogel@xxxxxxxxxxx> a écrit :
>
>> Should we change our policy and stop exporting new internal packages so
>> that they really cannot be used?
>
> -2, we want to enable extenders to use and explore code before making it
> API. IMHO a good way to provide new API is by having it already been
> explored by users.
>
>
> Are internal packages really a way to provide not yet stabilized APIs? IMO
> it should be done with a new package and/or bundle with a low version number
> (like 0.x)? internal should be for internal (sic), i.e., for implementation
> details.
>
> Also, if you use internal to test new API, there are chances that if your
> new API is successful you will never move it outside the a.b.c.internal
> package because you will have too many unhappy users.
>
> Of course, I was only talking about new internal packages, as existing
> should stay exported, with the x-internal directive.
>
>
>> And for existing internal that one wants to change/remove, we should
>> probably go with a deprecation policy like for "real" API.
>
> This may be a joke, but if that was a serious suggestion, -2 to that
> proposal. Not being able to freely change internals is a horrible suggestion
> as this would effectively prevent all new development activities.
>
>
> No, it is serious and qualifying it as a joke may be unnecessary. I guess
> that your -2 was enough to state that you strongly disagree with me.
>
> Let me rephrase it in case I've mis-explained myself: I don't suggest that
> we cannot and shouldn't be free to modify internals. I say that, as long as
> existing internals can be used, they are de facto API.
>
> When we want to do a breaking change to these internals, maybe we should
> have a rule to give clients a little time to move away from this code. I did
> not made it explicit in my previous mail, but the deprecation policy for
> such code should be much shorter than for real API. My guess is that it is
> exactly what you've done by reverting the change in HTMLPrinter for Ed M.
> So, why not making it a clear policy for existing internal code.
>
> Of course, this is annoying and it slows down development. But IMO if one
> wants more freedom in changing internals, one needs to protect it by not
> exporting it or do no evil to your user. So again, I suggest that new
> internal code should be placed in new packages which won't be exported in
> the first place (see explanation above).
>
> To sum up, my overall proposition would be to acknowledge that we have
> different categories of API, each with a associated deprecation policy:
>
> - public API: same deprecation policy as today
> - existing internal packages (those which are exported with the x-internal
> directives): lightweight deprecation/removal policy. e.g., deprecate it in
> version x (say the September release) and, if marked for removal, could be
> deleted in version x+1 (December release). I guess that with the new
> platform release schedule, it won't slow down development too much.
> - all new internal code should go to non exported packages: private code
> that can change anytime.
> - beta/testing/new APIs should go to new packages, exported as public API
> with version number < 1 and which can change anytime.
>
> WDYT?
>
> _______________________________________________
> cross-project-issues-dev mailing list
> cross-project-issues-dev@xxxxxxxxxxx
> To change your delivery options, retrieve your password, or unsubscribe from
> this list, visit
> https://dev.eclipse.org/mailman/listinfo/cross-project-issues-dev



-- 
Eclipse Platform project co-lead
CEO vogella GmbH

Haindaalwisch 17a, 22395 Hamburg
Amtsgericht Hamburg: HRB 127058
Geschäftsführer: Lars Vogel, Jennifer Nerlich de Vogel
USt-IdNr.: DE284122352
Fax (040) 5247 6322, Email: lars.vogel@xxxxxxxxxxx, Web: http://www.vogella.com