Skip to main content
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
RE: [eclipse-pmc] Draft deprecation policy
+1 - Really nice work!
 
I only have 3 minor comments / questions:
  • "The old API has been, or will be, no longer available in a later release" - I do not understand what this means. Is this about Eclipse 3.x and 4.x being developed in parallel Streams, so it says that sufficient reason for deprecating a 3.x API is when the 4.x Stream has decided to no longer support it?
    "Has been no longer available in a later release" seems an Oxymoron, and "will be no longer available in a later release" a Tautology. From a logical point of view, having both in one sentence is really interesting :) I'm wondering how this could be clarified.
  • "...on moving to equivalent new API " final priod is missing e.g. "... new API." (dot at the end)
  • "intent to remove the API is announced in a release in June 2007" - It remains unclear whether the intent to remove API can also be declared between releases. But perhaps that's not really relevant because the actual removal can only happen at release boundaries anyways.
    I was wondering about a case where     API is deprecated in June 2006 and the intent to remove is declared in August 2006. Plus two years means it can actually be removed in August 2008 -- thus being "release visible" in June 2009, and it would not have made any difference whether the intent to remove would have only been declared in June 2007.
Thanks,
Martin

From: eclipse-pmc-bounces@xxxxxxxxxxx [mailto:eclipse-pmc-bounces@xxxxxxxxxxx] On Behalf Of John Arthorne
Sent: Tuesday, November 03, 2009 4:07 PM
To: eclipse-pmc@xxxxxxxxxxx
Subject: RE: [eclipse-pmc] Draft deprecation policy


Thanks for the comments Martin. Based on all the feedback and our discussions in the PMC calls, I have updated the draft to use only time periods instead of a fixed number of releases. I.e., deprecated API will stick around for two years rather than two releases. This avoids the problem of putting too much emphasis on the release "marketing" number.

I also removed the sentence about not removing deprecated API if release train projects rely on it. The intent was that we would work with the community and try to accommodate their needs - maybe they have a very good reason why they can't switch off the deprecated API and we want to be good citizens rather than unilaterally breaking people. However I don't think such an inflexible rule needs to be baked into our policy. We already have this paragraph which conveys the same message:

"Objections raised to the announced removal will be considered, and options such as delaying removal, abandoning removal, or supplying compatibility support for affected clients will be considered based on community feedback."

I didn't get into specifics about tooling-friendly markup, such as the @until we have been discussing. We got bogged down in the semantics of the tag arguments and don't want that to hold us back from making progress. As you said we can add more detail in the policy later if we do start using such tags.

My second attempt at the policy can be found here:

http://wiki.eclipse.org/Eclipse/API_Central/Deprecation_Policy

John



"Oberhuber, Martin" <Martin.Oberhuber@xxxxxxxxxxxxx>
Sent by: eclipse-pmc-bounces@xxxxxxxxxxx

10/27/2009 05:42 PM

Please respond to
eclipse-pmc@xxxxxxxxxxx
To
<eclipse-pmc@xxxxxxxxxxx>
cc
Subject
RE: [eclipse-pmc] Draft deprecation policy





Hi John,
 
this looks very good! Things that I noticed:
  • In the section about major releases: "For example if an API is deprecated in release 3.9" you may want to better pick "3.6" as example for clarity.
  • I do not understand the section "In addition, the Eclipse Project will not delete deprecated API as part of an Eclipse Foundation simultaneous release..." If this is an additional constraint, it means that at the point where project X has been "unable to cease using deprecated API" that API had been announced for removal for 2 years already! Now if an Eclipse Foundation Release Train project is unable to cease using API that's scheduled for deletion, that is a bad sign of the state of that project, isn't it? Should such a project be allowed to remain on the release train?
    Having that statement in there seems to be unnecessarily weakening our position on API deprecation and deletion. We should not make the rules softer forrelease train projects, but we should be making them harder!
  • The section about "Announcing API Removal" does not specify any technique for how the "to be deleted" status of API would be processable by automated tools. This may not be necessary in the context of this policy though. I remember having controversial discussions about how to do the markup, and the question of markup should not be holding up the policy. But we may want to add markup information in an addendum at a later point in time.
  • A corollary of your policy is that at any point X in time, the current snapshot of the porting guide in CVS has the exact list of API to be removed from the Eclipse project as well as the times when removal is scheduled to occur. It may be worth explicitly noting this.
Thanks for taking action on this policy!
 
Martin

From: eclipse-pmc-bounces@xxxxxxxxxxx [mailto:eclipse-pmc-bounces@xxxxxxxxxxx] On Behalf Of John Arthorne
Sent: Friday, October 23, 2009 11:43 PM
To: eclipse-pmc@xxxxxxxxxxx
Subject: [eclipse-pmc] Draft deprecation policy


PMC members,

We've been discussing an Eclipse project deprecation policy on and off for the past year or so. With some guidance from McQ, I have written up a draft guideline for further discussion. Please look it over and we can discuss it at the next PMC call (or feel free to edit/add comments directly in the wiki page).

http://wiki.eclipse.org/Eclipse/API_Central/Deprecation_Policy

John_______________________________________________
eclipse-pmc mailing list
eclipse-pmc@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/eclipse-pmc

Back to the top