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

["Daniel Megert" <daniel_megert@xxxxxxxxxx>]

I'm fine to not export
internal packages in the future, but imposing deprecation rules on internal
code is a no go for me. As we saw in the actual case, when a project speaks
up, we usually are very tolerant and bring back the removed code.

Dani



From:
       "Mikaël
Barbero" <mikael.barbero@xxxxxxxxxxxxxxxxxxxxxx>
To:
       Cross
project issues <cross-project-issues-dev@xxxxxxxxxxx>
Date:
       25.01.2018
13:51
Subject:
       Re:
[cross-project-issues-dev] HTMLPrinter is Broken
Sent
by:        cross-project-issues-dev-bounces@xxxxxxxxxxx

---

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 newinternal 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 littletime 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?[attachment "signature.asc"
deleted by Daniel Megert/Zurich/IBM] 
_______________________________________________
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