> 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.barb...@eclipse-foundation.org> 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.barb...@eclipse-foundation.org > 🐦 @mikbarbero > > Le 25 janv. 2018 à 07:37, Ed Merks <ed.me...@gmail.com> 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.me...@gmail.com> 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/mas >> ter/org.eclipse.jface.text/src/org/eclipse/jface/internal/te >> xt/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@eclipse.org >> 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 listcross-project-issues-...@eclipse.org > To change your delivery options, retrieve your password, or unsubscribe from > this list, > visithttps://dev.eclipse.org/mailman/listinfo/cross-project-issues-dev > > > _______________________________________________ > cross-project-issues-dev mailing list > cross-project-issues-dev@eclipse.org > 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@eclipse.org > 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.vo...@vogella.com, Web: http://www.vogella.com
_______________________________________________ cross-project-issues-dev mailing list cross-project-issues-dev@eclipse.org To change your delivery options, retrieve your password, or unsubscribe from this list, visit https://dev.eclipse.org/mailman/listinfo/cross-project-issues-dev
