Skip to main content

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
Re: [cross-project-issues-dev] HTMLPrinter is Broken

I agree with Lars.

Dani



From:   Lars Vogel <lars.vogel@xxxxxxxxxxx>
To:     Cross project issues <cross-project-issues-dev@xxxxxxxxxxx>
Date:   25.01.2018 10:22
Subject:        Re: [cross-project-issues-dev] HTMLPrinter is Broken
Sent by:        cross-project-issues-dev-bounces@xxxxxxxxxxx



> 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.

> 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. 

Best regards, Lars

On Thu, Jan 25, 2018 at 9:20 AM, Mikaël Barbero <
mikael.barbero@xxxxxxxxxxxxxxxxxxxxxx> 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
? mikael.barbero@xxxxxxxxxxxxxxxxxxxxxx
? @mikbarbero

Le 25 janv. 2018 à 07:37, Ed Merks <ed.merks@xxxxxxxxx> 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 <ed.merks@xxxxxxxxx> 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
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

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


_______________________________________________
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



-- 
Leo Ufimtsev, Software Engineer, Red Hat


_______________________________________________
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

_______________________________________________
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


_______________________________________________
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
_______________________________________________
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://urldefense.proofpoint.com/v2/url?u=https-3A__dev.eclipse.org_mailman_listinfo_cross-2Dproject-2Dissues-2Ddev&d=DwICAg&c=jf_iaSHvJObTbx-siA1ZOg&r=1UITCR5rxUZHSFczvfaNFK4ymEbEiccRX7VKchpqz0Y&m=ylXTjSrATz1TJoDUeSeRUa-J8mQOA3EpFfZMRlzUYdc&s=E9dFzCn204V3hqa63z34TermEavX6QmB2hMfor4NL0g&e=




Back to the top