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" <[email protected]> To: Cross project issues <[email protected]> Date: 25.01.2018 13:51 Subject: Re: [cross-project-issues-dev] HTMLPrinter is Broken Sent by: [email protected] Le 25 janv. 2018 à 10:22, Lars Vogel <[email protected]> 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 new internal 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 little time 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 [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
