Mikaël,
I think that this is the path paved with good intentions.
We'll need to start at the bottom, in the Equinox runtime. For example,
we'll need to change a *great many *things in p2 before PDE works again;
we'll also need to change many things in p2 so that Oomph works again,
we'll need to change a great many things in Oomph itself so that it
works again, we'll need to do a whole heck of a lot of in JDT (likely
leaving no time to make JDT better for the end-user) and so on, and so
on, until everyone on the entire end-to-end internal food chain is
exhausted. Then we'll inflict this pain on the bad, very bad external
community, who will likely also become exhausted negotiating API *before
*using it. At that point we'll find out we made mistakes at the start of
the chain, and then we will ripple the next set of API changes through
the system. In a few years we'll arguably have the world's most shining
gem, the best in the world, of all possible worlds. After all, with
20/20 hindsight we can make everything perfect. The result will conform
to all principles of greatness beyond impeach. But more than likely
we'll have little or no community left. The users won't care at all,
those that are left, using the tools that have migrated and still
actually work, because the users won't see the underlying greatness of
the shining gem we have created. And the developers, those that are
left, will wonder if the Eclipse desktop platform is really such a great
place to target for development.
As an analog that is currently in my face, my recent effort to use the
latest GWT and AppEngine technology leaves me feeling compelled to
delete it all and never look at it again. I should expect package name,
natures, builders, tools, and validators to simply be renamed, removed,
moved, or arbitrarily changed whenever Google decides that's in my best
interest. I should expect that can and will happen at any point in the
future.
In the end, what you suggest is definitely an interesting new path. To
think that StringBuffer to StringBuilder replacement was the catalyst to
guide us onto that path...
On 25.01.2018 09:20, Mikaël Barbero wrote:
Very interesting thread, thanks to all for sharing your opinion.
Changing existing internals could break clients because so far, they
can use it. Should we change our policy and stop exporting new
internal packages so that they really cannot be used? And for existing
internal that one wants to change/remove, we should probably go with a
deprecation policy like for "real" API. Maybe the deprecation period
before change/deletion will not be as long as for "real" API, but I
guess we would get best of both worlds with such a policy, isn't it?
WDYT?
Cheers,
--
*Mikaël Barbero - *Eclipse Foundation
IT Services - Release Engineering
📱 (+33) 642 028 039
📧 [email protected]
<mailto:[email protected]>
🐦 @mikbarbero
Le 25 janv. 2018 à 07:37, Ed Merks <[email protected]
<mailto:[email protected]>> a écrit :
Leo,
While I agree in principle, the principles lead down a path where I'm
sure no one really wants to go; it is the path paved with good
intentions.
Specific comments below.
On 24.01.2018 18:24, Leo Ufimtsev wrote:
Hello Ed,
On Wed, Jan 24, 2018 at 7:27 AM, Ed Merks <[email protected]
<mailto:[email protected]>> wrote:
I'm a more than little annoyed to see that this method
org.eclipse.jface.internal.text.html.HTMLPrinter.insertPageProlog(StringBuffer,
int, RGB, RGB, String)
I understand your frustration, we sometimes have to deal with
similar problems.
E.g when Gtk makes changes to their methods, it breaks SWT and
causes glitches in Eclipse.
But:
As the package suggests, it's an /internal/ method:
org.eclipse.jface./_*internal*_/.text.html.
'Internal' means it's not suppose to be used by public.
Yes, the point of "internal" has been hammered upon, but it's a
general point, like human rights, and of course we all agree the
humans should have plenty of those. But it strays far and wide from
the specific problem at hand. The irony of the specific problem is
apparent is when you look at the call hierarchy of the methods in
question. They're not used internally at all, unless JDT is
considered internal, which it clearly is not. As a result of JDT's
trending setting example, you'll find uses of this in any code that
tries to have really nice hover information like JDT does. Given
there bugs are open asking for it to be API, it's clear there are
clients of this specific code. Yes, they're all bad, very bad.
Of course I empathize with Lars' efforts to make improvements, and I
have in fact helped him in part with those changes, so I more than
resent arguments that I personally stand in the way of the platform's
great progress. Of course I could have been less of a jerk in how I
phrased my opinion on this specific change. Sorry for that.
If you wish to use internal api because it's useful to you, then you
should first put in effort to make
the api public and /only then/ use it. Not use it and then complain
about it's removal.
Yes, the human rights issue again. The Bugzilla record speaks for
itself though as does the call hierarchy of the methods, which makes
it clear they exist to be used outside of the project that provides
them. Had this high standard been applied to JDT, we'd not have this
problem. There simple is a double standard. Had we applied this
standard when developing Oomph, there would be no Oomph. So while
it's a high and mighty principle that one cannot argue against
without the wrath of the human rights activists protesting at your
door, it's simply not pragmatic and has not been well applied by the
overall Eclipse PMC itself.
And again, the specifics of the problem StringBuffer ->
StringBuilder; of course a trivial change, one that I can change in
two minutes in EMF, but not without maintaining my compatible version
ranges in EMF.
Because you chose to use internal api, and your suggestion to revert
the code removal, you are slowing down platform
development and by extension slowing down the whole Eclipse
development process.
Yes, I see it's a significant human rights violation. But I thought I
did my part for human rights when I changed EMF's templates to
generate StringBuilder in places such as the generated toString()
method of each EClass.
I know JDT, Dani and his team, are very careful with changing
internals because they know many clients use them, and they know that
while making rapid progress is great, if they behave disruptively
because they have the intrinsic right to so so, they could end up
with fewer clients. And kudos to Dani and his team for their
consideration; EMF uses JDT internals as well and has never in 15
years been broken by any JDT internal "API" changes, even with the
changes for Java 9. It's an impressive accomplishment for the JDT
team, and I'm sure that as a whole it slows them down, but they
carefully consider the overall balance.
It's very important for us to stay agile and move quickly, this
involves being able to refactor old code, remove redundant code etc..
It's not so clear to outsiders in which direction things are moving
quickly. I don't think StringBuffer -> StringBuilder is arguably a
case in point. No one actually cares whether a toString method uses
StringBuilder as opposed to StringBuffer, but of course that can be
easily changed because no one can see that change. But changing the
signature of visible methods begs for more caution and consideration,
especially when these internals are in fact only used externally.
As case in point, in Fedora, "yum" got dropped and replaced with
'dnf' package manager
because "yum" had too much internal api being used by external users
and they couldn't refactor/stay agile.
My experience with HTMLPrinter is that it took me longer than
necessary to fix some color related issues
in platform because HTML printer was such a mess of multiple
redundant methods.
I'm actually very glad those methods were removed and I think they
should stay removed.
Fortunately it wasn't your decision! I'd be very, very, very glad to
remove Package.getESubpackages() because it's a pointless abomination
that only ever causes problems while providing no semantic value
whatsoever. But that's really API, not "internal". But if I wanted
to be agile (and I really do!), I'd increment to EMF 3.0, and make
all kinds of improvements, but the disruption to the community would
far outweigh any value that such an effort would bring.
This is nothing personal. If we move too slowly, eclipse will die
and we will all loose :-(.
Conversely, if you move too disruptively, Eclipse will also die
because all kinds of tools that end users love will stop working in
Photon, so end users won't install Photon and that will make look
Eclipse bad. While you can argue (and will of course be right) that
the providers of those tools were human rights violators for using
"internal", the perception of the general users will be that Eclipse
releases are disruptive and break their tools. The users will then
look closely at what new features and improved performance they get
in return by moving to Photon, and being unable to find any that are
relevant to them, they'll shake their heads and wonder if some other
IDE might be a better alternative. In addition, the folks developing
the tools will also dread each new Eclipse release and will wonder if
it's really a good place to develop tools.
So best we all balance these highly principled issues---I do not
argue that the principles are sound---and look to make improvements
in the least disruptive way possible, accepting the fact that for
most downstream clients and for most users, having their code and
their tools simply keep working is the most important goal for them.
Of course that flies in the face of agile refactoring and rapid
progress, and of course that suggestion will set the development
teams' hair on end. But for EMF, that's something I live with,
because I know most clients, and no users, will care what I do in
EMF; they will only notice when I've done something if I breaks them
and then they'll have a bad impression of EMF. My arguments about
principles will fall deaf ears.
Moving forward, I suggest we help each other move fast and keep
things going quickly.
This involves not using internal api and try to make sure platform
development is fast and effective.
This would argue for applying these high standards within the overall
platform itself, so PDE should not use any internals of p2, e.g., so
"import org.eclipse.equinox.internal.p2.director.PermissiveSlicer" in
org.eclipse.pde.internal.core.target.IUBundleContainer clearly argues
that to implement cool things in PDE one needs the highly useful
internals of p2. Similarly JDT should not use any internals of UI,
JFace, Text, and so on.
Unfortunately this is not highly pragmatic, though it does conform to
the high principles we expect all downstream clients to emulate. If
we expect downstream clients to be highly principled, the standard
needs to be set first and foremost but those arguing for the value of
those principles. Start the effort in your own back yard, and then
show to the world that all cool things can be implemented with the
public APIs with no need to use internals across projects. When
that effort is complete, climb up onto that high horse and go on the
crusade.
Unfortunately, instead of moving forward quickly, this digression
into high principles would result in the teams spending *all *their
time figuring out what API clients really need in order to implement
highly-functional, cool applications. The end-effect would be that
all the clients who already have highly-functional, cool application
would be broken and would need to migrate to a new set of APIs, which
hopefully really do satisfy *all *their needs.
Is this really the path down which you want to go? It is definitely
not the path down which I want to see us go, but the platform teams
sets their own path.
In EMF I have paved the path differently. In principle, "private" is
bad: if it's useful, clients will want to use it, derive from it, and
specialize it. In principle, "internal" is pointless: if it's
available clients, will definitely use it, and then when the pure,
correct, final API is realized, clients will be disrupted by the
internal -> API migration. Of course this leaves me in a bind when I
change anything, but as a counter example, one of my most significant
technical accomplishments in my career was to add generics to the
Ecore model itself in such a way that no one in my company noticed,
though EMF was used in hundreds of products. So significant change
is still possible down this other path, but yes, it's way more
restricted for me, so I fully understand that others choose a
different path. I will not argue that my path is the best path, but
it has served the majority of my client base well.
I think the middle path is the one taken by JDT, a path that
recognizes that internals are used because they can be used and
because they often need to be used. I would hope that the path
moving forward balances all such considerations.
Thanks
has gone from deprecated to deleted in less than a 5 week period:
https://github.com/eclipse/eclipse.platform.text/commits/master/org.eclipse.jface.text/src/org/eclipse/jface/internal/text/html/HTMLPrinter.java
<https://github.com/eclipse/eclipse.platform.text/commits/master/org.eclipse.jface.text/src/org/eclipse/jface/internal/text/html/HTMLPrinter.java>
JDT, EMF, Xtext, and Oomph all use this method.
I really don't care to hear the arguments about it being
internal because:
1. I don't see that JDT ought to have exclusive special
privileges to use internal things.
2. I don't see any reason why it should be internal.
3. And any client wanting to implement hovers that work like
the ones for JDT, will have the same needs as JDT and will
solve the problem the same way.
I'd like to avoid dwelling on the fact that this is simply a
pointless change, but I can't help it. Surely one wouldn't
change this simply to improve performance in code that has no
relevant performance impact! It seems to me at best a misguided
effort that would be better spent on real improvements.
Please revert this change before M5.
https://bugs.eclipse.org/bugs/show_bug.cgi?id=530240
<https://bugs.eclipse.org/bugs/show_bug.cgi?id=530240>
And in the future, please consider that any internal API that is
used by any other project is going to cause problems for many
projects just as it did for JDT:
https://bugs.eclipse.org/bugs/show_bug.cgi?id=529118
<https://bugs.eclipse.org/bugs/show_bug.cgi?id=529118>
_______________________________________________
cross-project-issues-dev mailing list
[email protected]
<mailto:[email protected]>
To change your delivery options, retrieve your password, or
unsubscribe from this list, visit
https://dev.eclipse.org/mailman/listinfo/cross-project-issues-dev
<https://dev.eclipse.org/mailman/listinfo/cross-project-issues-dev>
--
Leo Ufimtsev, Software Engineer, Red Hat
_______________________________________________
cross-project-issues-dev mailing list
[email protected]
To change your delivery options, retrieve your password, or unsubscribe from
this list, visit
https://dev.eclipse.org/mailman/listinfo/cross-project-issues-dev
_______________________________________________
cross-project-issues-dev mailing list
[email protected]
<mailto:[email protected]>
To change your delivery options, retrieve your password, or
unsubscribe from this list, visit
https://dev.eclipse.org/mailman/listinfo/cross-project-issues-dev
_______________________________________________
cross-project-issues-dev mailing list
[email protected]
To change your delivery options, retrieve your password, or unsubscribe from
this list, visit
https://dev.eclipse.org/mailman/listinfo/cross-project-issues-dev
_______________________________________________
cross-project-issues-dev mailing list
[email protected]
To change your delivery options, retrieve your password, or unsubscribe from
this list, visit
https://dev.eclipse.org/mailman/listinfo/cross-project-issues-dev
