> As far as deprecating API, CDT does not have a deprecation policy, certainly
> nothing like the quite heavyweight one the platform does. The reality is if
> we did have such a policy, I don't think this kind of code clean-up would
> ever happen. The removal of CDI and the code cleanup was announced
> well in advance on the mailing list.
Sorry to extend this thread even further. IMO, the best mechanism for giving a heads-up on API cleanup is through annotations. That is far more effective and
reliable than mailing lists, EclipseCON presentations and BOFs, wikis, etc. You are advertising your intentions directly to
every developer that is integrating CDT into a product, injecting the notification directly into his development workflow. If the developer has turned off such warnings/errors, or fails to act on the markers…oh, well. Not your fault; it’s his.
This isn’t about a heavyweight process. It’s mostly about being patient and taking due diligence. If today you decide you’d like to remove a public type, method
or field, annotate it “@Deprecated // in Neon”. In every future major release cycle, you would
grep the codebase for these annotations and see which ones are suitable for executing on based on when they were deprecated (recorded in the comment) and whether it has crossed the acceptable threshold (2 or 3 years, e.g.).
If it feels heavyweight, OK. But I guess that’s the price you pay when you’ve created SW that exposes API that hundreds of developers have latched on to. The
only acceptable alternative, IMO, is to never clean up API, which is not a good solution in my book. Anyway, I’m butting in here only because I think it would be good if we do more than just avert this particular break of GNU ARM Eclipse. Hopefully there will
be some process/behavioral change that will make this situation less likely to happen again.
John
From: cdt-dev-bounces@xxxxxxxxxxx [mailto:cdt-dev-bounces@xxxxxxxxxxx]
On Behalf Of Jonah Graham
Sent: Wednesday, May 25, 2016 6:10 AM
To: CDT General developers list. <cdt-dev@xxxxxxxxxxx>
Subject: Re: [cdt-dev] missing org.eclipse.cdt.debug.mi.core in Neon?
Hi John,
I agree with what you say. This is our chance to cleanup API and we have to do it now (and regularly in the future) to keep CDT maintainable.
As far as deprecating API, CDT does not have a deprecation policy, certainly nothing like the quite heavyweight one the platform does. The reality is if we did have such a policy, I don't think this kind of code clean-up would ever happen.
The removal of CDI and the code cleanup was announced well in advance on the mailing list.
That said, we (CDT devs) have a responsibility to people who are active in the community to not make life unnecessarily hard for them. I think this is a perfect test case (as was TCF a couple of months ago). Someone depending on CDT came
along, tried out the new release before it was released, and found their code didn't work. Working with them (GNU ARM now and TCF earlier) we determined that the cleanup had to mostly happen on their side to keep up to date with the APIs.
In the case of TCF, the review led mostly to removing some defunct dependencies. Then we were left with one awkward API change. The decision was to copy the new code from
http://eclip.se/456116#c10 from CDT 9 into TCF so that TCF could continue to work with CDT 8 and CDT 9 from a single source and binary distribution.
In the case of GNU ARM the issues were almost identical to TCF. In addition though there was another class that needed to be copied, but copying it is not straightforward http://eclip.se/488909#c3
as it has lots of dependencies too. Therefore I think the best solution is to clean up the code as was done in Bug 488909, but maintain the original API too. That resurrection is covered by
http://eclip.se/494504.
I hope I have done enough to satisfy everyone that careful consideration has been undertaken on these changes and that there are no objections to
http://eclip.se/494504 for CDT 9.0.
On 25 May 2016 at 02:58, John Cortell <john.cortell@xxxxxxx> wrote:
> mark them as deprecated, and just keep them there for a while,
> until everything will be migrated to 9.0 and compatibility with 8.x
> will no longer be required.
If I understand this correctly, the request is to defer API cleanup until GNU ARM Eclipse no longer supports CDT 8.x. When will that be? And who's to say that at that point, another CDT product isn't caught off guard by the cleanup and requests the same thing--another
deferral. And let's keep in mind that API cleanup (breakage) can only happen on a major release, which does not happen every year. It's happening this summer, but who knows when the next opportunity will be. I'm just wondering if this effectively comes down
to a request to never clean up API if its breaks backward compatibility. Products that deploy different versions for different Eclipse release trains is not unheard of. It's for sure a pain for both consumer and producer, but it's doable and many have done
it.
That said, API that is removed should have been marked deprecated for at least 2-3 years, IMO. If that wasn't the case here, it seems reasonable to cry foul.