Bugzilla – Full Text Bug Listing
| Summary: | [discussion] Change rules about x-internal exports | ||
|---|---|---|---|
| Product: | [Eclipse Project] Platform | Reporter: | Thomas Watson <tjwatson> |
| Component: | PMC | Assignee: | Project Inbox <platform-pmc-inbox> |
| Status: | VERIFIED FIXED | QA Contact: | |
| Severity: | normal | ||
| Priority: | P3 | CC: | akurtakov, daniel_megert, Ed.Merks, hubert+eclipseorg, jonah, Lars.Vogel, raymond.auge, Vikas.Chandra |
| Version: | 4.14 | ||
| Target Milestone: | 4.15 M1 | ||
| Hardware: | PC | ||
| OS: | Mac OS X | ||
| See Also: | https://bugs.eclipse.org/bugs/show_bug.cgi?id=544977 | ||
| Whiteboard: | |||
|
Description
Thomas Watson
+1 for handling everything on a case by case basis following the normal process (committer decides, if they disagree they can escalate to project lead / PMC) (In reply to Thomas Watson from comment #0) > https://wiki.eclipse.org/Export-Package > > The current rule set for the Eclipse project is to export everything as API, > x-internal or x-friends. Bug 544977 has recently had discussion about rule > and some thoughts on changing it. > > My position is that the rule should be changed, particularly for x-internal. > The use of x-internal should be done on a case-by-case basis instead of > across the board for all internal packages. Only when we want to encourage > experimentation with some package which is not already API should we use > x-internal. Blindly opening all packages for use by other bundles is not a > good policy in my opinion. > +1 > A secondary topic is what to do with existing x-internal packages. Should > we be forced to keep x-internal package exports for existing exports or can > we be free to remove them on a case-by-case basis? > +1 for on a case-by-case basis. BUT, given we can't know what consumers have been doing for the past 20 years and what breaks as a result, I would hope that we don't go making sweeping disruptive changes just because we have the API-right to do so. My major concern here is that most of the committers appear to be on the extreme API-rights side of the equation, but who speaks for the consumer-rights? Mostly the argument is that consumers have no rights, just the privilege to negotiate APIs, which in my experience is mostly a exercise in futility. We set a high standard that consumers *mus*t follow, yet we break those rules ourselves as we see fit. https://bugs.eclipse.org/bugs/show_bug.cgi?id=538077 Of course I fully understand why negotiating APIs is so problematic from the producer's point of view. The consumer expects the producer to take on a new permanent cost/burden yet there is no incentive for the producer to do so. > My position is that we should be free to remove the export for x-internal > packages if the said package was never really meant to be used > experimentally by other bundles. +0 What is meant and what is the historical state are two independent things. We often don't even know what was meant because we just blindly followed the export everything rule, making experimentation possible. > The current policy is that we are free to > remove and change types from internal packages with no checks on breaking > changes. +0 While we have the API-right to do so, we should remember that when we do disruptive things that affect consumers we erode the confidence of our consumer base; this is not to our benefit. For example, at this point, I no longer have confidence that any API that I use, will remain API. It might well be deprecated in the next release, and then might well disappear at some later time. Some of such deprecations appear completely gratuitous to me. This does not give me warm fuzzy feelings that I might well be required to rework my downstream frameworks in a way that breaks my clients. The platform's decisions might well make decisions for me that I would not personally make for my consumers. > Removing the export is basically the same as remove the complete > package for external use. Again, this should be done on a case-by-case > basis. If a particular case proves to be very disruptive to the community > then more caution should be taken to plan the removal of the x-internal. +0 Your technical point is that given the API right to make arbitrary changes, of course removing exports is well within those rights. One can't argue against that. The problem is that disruption often won't be evident until after the release. Certainly disruption to the simrel projects will hopefully become evident quickly, assuming that these projects build regularly against the latest platform, which unfortunately appears to be a bad assumption. (In reply to Lars Vogel from comment #1) > +1 for handling everything on a case by case basis following the normal > process (committer decides, if they disagree they can escalate to project > lead / PMC) +1 and we should announce the planned removal to the community, though not with the same rules as for official APIs. Maybe announce during M1 and delete no later than with M2 (better would be M1). +1 for Eds point of view that we should not make sweeping disruptive changes. The platform always cared about its consumers and will always do. IMHO this change request is more about adding flexibility for future packages and not about removing all x-internal and x-friends directives from the existing code base. (In reply to Lars Vogel from comment #4) > +1 for Eds point of view that we should not make sweeping disruptive > changes. The platform always cared about its consumers and will always do. > > IMHO this change request is more about adding flexibility for future > packages and not about removing all x-internal and x-friends directives from > the existing code base. +1! As a consumer of Eclipse APIs for a long time I am a -1 on changing current guidance of https://wiki.eclipse.org/Export-Package. The ability to access code and use it in ways the original author had not envisioned is part of what made Eclipse ecosystem so good. The statement in the wiki is still true and continues to be for new code: > this forms a critical part of the Eclipse ecosystem by allowing experimentation and investigation. Lets try not to forget where we came from. (In reply to Jonah Graham from comment #6) > As a consumer of Eclipse APIs for a long time I am a -1 on changing current > guidance of https://wiki.eclipse.org/Export-Package. > > The ability to access code and use it in ways the original author had not > envisioned is part of what made Eclipse ecosystem so good. > > The statement in the wiki is still true and continues to be for new code: > > > this forms a critical part of the Eclipse ecosystem by allowing experimentation and investigation. > > Lets try not to forget where we came from. As mentioned it will be case by case. How about we say that if any project wants access to a certain package it can ask for it? (In reply to Dani Megert from comment #7) > > Lets try not to forget where we came from. > As mentioned it will be case by case. How about we say that if any project > wants access to a certain package it can ask for it? Also, this is one of the usecases for fragments. Fragments ARE allowed to access internals (even live in the same package as the host internal package) and if they really want to they can export the internal package for others to use. This is a much more explicit way of doing this and puts more ownership of the usage of the internal on the developer using the internal. (In reply to Dani Megert from comment #7) > As mentioned it will be case by case. How about we say that if any project > wants access to a certain package it can ask for it? That does not help as it requires a new release to be able to access it. While it would be nice if everyone contributed back beautiful new API or even requests for exposure that would be great. But in reality the hundreds (thousands?) of projects outside of official eclipse projects generally need to implement and/or fix something based on the version of Eclipse they have in their hands at that point in time. (In reply to Thomas Watson from comment #8) > Also, this is one of the usecases for fragments. Fragments ARE allowed to > access internals (even live in the same package as the host internal > package) and if they really want to they can export the internal package for > others to use. This is a much more explicit way of doing this and puts more > ownership of the usage of the internal on the developer using the internal. This is interesting, and I didn't know that. However why bother limiting by not exporting it if it does not actually limit. Creating a fragment or ignoring/suppressing a warning does not seem like that big a difference. I interpret "more ownership" in this context as "more work" but not changing the effect on the Eclipse Platform project. (In reply to Jonah Graham from comment #9) > This is interesting, and I didn't know that. However why bother limiting by > not exporting it if it does not actually limit. Creating a fragment or > ignoring/suppressing a warning does not seem like that big a difference. I > interpret "more ownership" in this context as "more work" but not changing > the effect on the Eclipse Platform project. More ownership == more control I find it interesting that a developer goes through all the effort to read code implementation details of undocumented internals and figures out some way to use the code in unintended ways and then does not want to have control over exporting such functionality themselves for consumers to use the work they did. Why not export it in the first place? To not entice more casual developers to import the package in the first place. Also, OSGi is more than just Eclipse and PDE and the Eclipse bundles get used by others that do not use PDE. Other more popular tools than PDE are used to develop OSGi bundles outside of the Eclipse community. The x-internal is not a standard directive and not paid attention to by other tools. The framework implementations do not pay attention to x-internal and there is no additional indication at runtime that an internal is being used at all. Modularity best practice is to hide the internals, this export all internals policy goes directly against modular best practices. (In reply to Thomas Watson from comment #10) > (In reply to Jonah Graham from comment #9) > > This is interesting, and I didn't know that. However why bother limiting by > > not exporting it if it does not actually limit. Creating a fragment or > > ignoring/suppressing a warning does not seem like that big a difference. I > > interpret "more ownership" in this context as "more work" but not changing > > the effect on the Eclipse Platform project. Puts the onus for this internal workaround onto the developer creating it. While the maintainer is not bound by said workaround. > > More ownership == more control > > I find it interesting that a developer goes through all the effort to read > code implementation details of undocumented internals and figures out some > way to use the code in unintended ways ... > > Modularity best practice is to hide the internals, this export all internals > policy goes directly against modular best practices. While I understand that the community might be at risk from such a change, it's also at risk of stagnation, stagnation partially caused by limitations on evolving the platform. Internals MUST be allowed to change in order to give maintainers freedom to innovate. This is the fundamental tenant of encapsulation. By loosening this tenant from the beginning with x-internal Eclipse has really put itself at risk. Because of it, many Eclipse projects are less consumable outside of the Eclipse ecosystem. I suspect that Tom's motivation here is to take back some small amount of control over his ability to innovate for the betterment of the community, not in spite of it. That being said I would be +1 for making the change on a case by case basis, it should not be made rashly and without consideration (and I agree it should happen early in the milestone process). But also, it should not be solely on the maintainer to acknowledge any side effects such changes might incur and if there is a particularly high risk scenario someone who can speak to it should probably step up to demonstrate. Beyond that, what is a maintainer left to do? What seems to be missing in the discussion so far is that changing the policy will have more effect on newly added packages which will not be exported rather than already existing ones. So for that reason we should change the rule to not require exporting everything. Existing packages should not be changed until some development in them require it - that's how I read Tom's proposal. With my SWT hat on I have another comment - the rule to always export internals caused nothing by trouble whenever someone tried to monkey patch SWT. Use some internal class/method which SWT exports on your Windows machine but there is nothing like that on Mac/Linux and viceversa. And when we were still supporting 32 bit - store return value of a method in int (as developer was on 32bit machine) to find out via runtime error its long. E.g. this is a case when removing these x-internal exports would only help the community. This has been decided in this week's PMC call: https://wiki.eclipse.org/Eclipse/PMC#Meeting_Minutes - Newly added internal packages should not use x-internal exports unless there are very good reasons - For existing packages the x-internal export can be removed with PMC approval Updated https://wiki.eclipse.org/Export-Package and sent a note to eclipse-dev. |