Bugzilla – Full Text Bug Listing
| Summary: | [api] Need a process and policy for API deprecation | ||
|---|---|---|---|
| Product: | Community | Reporter: | Martin Oberhuber <mober.at+eclipse> |
| Component: | Architecture Council | Assignee: | eclipse.org-architecture-council |
| Status: | RESOLVED FIXED | QA Contact: | |
| Severity: | normal | ||
| Priority: | P3 | CC: | ahunter.eclipse, bokowski, bpayton, caniszczyk, darin.eclipse, david_williams, d_a_carver, irbull, jeffmcaffer, KetanPadegaonkar, lchan, Mike_Wilson, Olivier_Thomann, slewis, steffen.pingel, thatnitind, tom.schindl |
| Version: | unspecified | ||
| Target Milestone: | --- | ||
| Hardware: | PC | ||
| OS: | Windows XP | ||
| Whiteboard: | |||
| Bug Depends on: | 279539 | ||
| Bug Blocks: | |||
|
Description
Martin Oberhuber
Thanks for the summary Martin. I think the only thing that's left out is having a clear communications channel. Please someone correct me if I'm wrong, the way most people find out about new or deprecated API is just downloading a newer Eclipse release (or milestone for that matter). I know we have a migration guide, but that isn't the same. A proposal could be that part of the release trains, we're able to create an API report and show new things that have been added, things that have been recently deprecated (with a reason why and alternative) and things that have been removed. A lot of this is becoming possible with the work going on in PDE API Tools. Also, I think the most important thing here is to set expectations so people don't feel angry if anything has been removed or deprecated. Right now, we can't really point people somewhere and say, well, here's the policy and you agreed to it by consuming our stuff. On the topic of release trains... I think the role of the release train has been evolving to where it provides us an opportunity to enact quality requirements. We can't force projects to adopt any particular policy, but if they join the train, they have to do X. As long as the requirements are meant to improve quality and have a benefit to our adopters, I'm for them. Ok, that's enough from me, let's get other people in the discussion. re the role of the release train...
If the end result of a deprecation is the actual removal (or a breaking change in the semantics) of a particular API, then any components that depend on the API will require updating. To me, being part of a release train means committing to ensuring that _all_components_in_the_train_work_ (not just mine), and thus I should minimally not implement such a change unless I have ensured that the dependent components can be updated for the release. In extreme cases -- for example, when a component that depends on my change is no longer in active development -- I would have to decide between making the change or updating the component myself. (Or work with the rest of the community to cause the inactive component to be removed from the train.)
I said "minimally" above because, although ensuring that a particular release train actually works seems obvious to me, that still doesn't take into account the rest of the ecosystem that is built on top of our releases. To help with this, we need to make every possible effort to give the rest of the community time to respond. One suggestion: Our "porting guides" should have more forward looking statements, something like
"
As of the Ganymede release, the following API are deprecated:
<api>
<description of what to do instead>
<communication channel to discuss impacts and get support>
...
These will continue to be available in the Ganymede+1 release, but will be removed afterwards. If you have a dependency on any of these API, please update your code accordingly.
"
(In reply to comment #2) > These will continue to be available in the Ganymede+1 release, but will be > removed afterwards. I feel that this is a somewhat too strong statement. Scott Lewis has made a very interesting remark on bug 261874 comment 3, that we really need to see the full lifecycle of API from proposal over adoption to deprecation; over this lifecycle, we need the discussion in both directions between producers and consumers. I agree with Chris that the discussion channel is the real trick to address. The process of deprecation seems simple enough: * producer deprecates Foo (explaining to use Bar instead). - consumer either makes the change, or - responds that he cannot use Bar because..., or - does not respond within reasonable time frame. * producer now decides to - simply remove Foo (after sufficient positive feedback), or - proved more/better alternatives Bar2, Bar3, or - extend the deprecation period, i.e. leave Foo in there for 1 more cycle - or provide a separate compatibility layer bundle for Foo, - or perhaps even take back the deprecation In my mind, the mere deprecation is just a message to the community that we don't like Foo anymore. Of course deprecation does (and should) convey the *intent* to remove X eventually, but the actual outcome (removal or other) depends on the feedback. If we set expectations right, i.e. tell consumers that the outcome depends on their feedback, they will be less malevolent against deprecation and more interested in giving the feedback. Again, what we need is well-working feedback channels, and methods to create machine-readable feedback even from binary, no-longer-developed bundles. Here is one idea that I had: * Create an internet-accessible database ("DeprecationDB"), where - key is the fully qualified signature of a deprecated item - value is information such as the Javadoc for the deprecation - associated are client feedback reports for the item, such as * bundle name / method signature of known user of item * number of uses of item inside Organization - allow bugzilla-like E-Mail communications (CC to item etc) for giving feedback i.e. have the two-channel discussion in both directions, but keyed to the item to be deprecated. * In the end, every deprecation will have a track record of the interested parties (stakeholders), actual measurable data (who uses it and how often). Some ideas of workflow with this: * Project makes Foo as deprecated --> Build process automatically adds Foo to deprecationDB * Clients use tooling to make regular scans of their code/binaries to detect references to anything deprecated --> Usage is automatically reported to deprecationDB --> People are signed up for E-Mail communications over the new deprecation --> The communication link is established * Even end-users could run the tooling on products they obtained: for instance, a Wind River customer could run the tooling, then get back to wind river and say "You're using deprecated X here, what are you going to do about it?" I'm not sure who could be investing the time to actually work on deprecationDB, so it may perhaps be time to wake up from my dream. But if, on the other hand, deprecationDB really gives us the data we need to make all of Eclipse get rid of more legacy and be more innovative, the benefit could be huge... I'm curious to hear what others think about this. PS regarding the release train... in my point of view, the train projects are also just consumers, although consumers who are expected to be "nearer to the source" than anyone else. In other words, if we cannot persuade the train projects to buy into a change, we cannot expect to persuade anyone else. I'm not too much a fan of forcing the train projects to do things they don't want to do... because we also can't force the wider consumer community. The train projects should be exemplary for the wider community, i.e. set a positive example (in a "yes, we *can* make the change" mentality). We need to work together with them to have them *want* accept and react to deprecation... and I believe we can do so by providing really good tooling. Note that in the case of really simple refactorings of deprecated stuff (which may be as simple as rewriting patterns: e.g. eFeatureID --> getFeatureID() the deprecationDB could even contain such rewriting patterns, and tooling could make the rewritings automatically... And, one more word on deprecationDB:
This doesn't need to be a heavy-weight thing. Web-accessible Javadocs show that it's easy to select a web page out of an URL that's generated from a field,method or type signature. Same is true for a Wiki. In its simplest incarnation, the deprecationDB could consist of
1. A downloadable file with signatures of all deprecated items
(for the checker tool to find deprecated references).
2. An initially auto-generated Wiki page for each deprecated signature,
which holds a link into Javadoc for the deprecation ("what are the
alternatives") and allows the Community to freely discuss the deprecation.
Through the "Wiki Watch" feature we'd get E-Mail notifications and a medium for free discussions (could also link into bugzilla of course if we want).
In other words, all we need is a Wiki, and a reference finder tool which automatically generates proper Wiki URLs in its report. Consumers who run the tool can opt-in on each Wiki discussion based on the URls in the report.
re deprecation infrastructure: We have lots of cool sutff in the API tooling. I'm betting that something very useful can be made out of this. machine readable format that allows API tools to give an Error when using deprecated stuff that is due to be removed. Re comms channel: +1. RSS feed of newly deprecated stuff. Tags with the various project names. "intend to deprecate" "actually deprecate" "will be removed" re moving people along: This is a hard one. Our collective history is riddled with of examples of people not interested in absorbing ripples. There is no reason to believe that deprecations are any different. Getting everyone to "agree" seems an unlikely high bar. Basically guarantees that nothing will ever be removed. Understanding where people *cannot* is very interesting. people who *will not* less so. (of course this is easier to say the further down the stack you are) re the train: absolutely the train has to all work. The deprecation removal deadline should be early in the cycle to people can react. M4 say. Consumers will have known that the deletion was coming but hard compile error are very motivating... re bundles no longer under development and the train. They are unlikely to be on the train. (In reply to comment #6) > Re comms channel: +1. RSS feed of newly deprecated stuff. What's most important for me here is that we also have a "backward" channel for actually getting information. Even if it's just machine generated saying "API X that you're deprecating is getting used in bundle Y version Z from Provider Foobar". RSS won't do that for us. > reason to believe that deprecations are any different. Getting everyone to > "agree" seems an unlikely high bar. Right, I'd better soften this as "not disagree within ... (reasonable) period of time". Again, the crack is at least getting "some" feedback as a discussion base. The following is an interesting read: http://java.sun.com/j2se/1.4.2/docs/guide/misc/deprecation/deprecation.html Sun basically says that deprecation should come as soon as when new (better) API for a concept has been created. I read this as deprecation being first of all a signal that something better is available; and only secondary that it may eventually be removed. Again this seems to go towards two "levels" of deprecation: 1. Marking that something better is available 2. Marking that it's so bad it's better removed. (In reply to comment #4) > I'm not too much a fan of forcing the train projects to do things they don't > want to do... because we also can't force the wider consumer community. > Hold on. Obviously we can't force the "wider consumer community" to do something, if for no other reason than we can't identify the set of all possible consumers who could be impacted. However, *we* are making the release train; it is the thing that we produce *together*. If we need to "force" people, in this case, it effectively means that there are projects that are part of the release train that _do_not_care_if_the_result_works_. Personally, that seems like total nonsense to me. The worst case might be that, as a contributor to the train, I'm unaware that I've done something that breaks another part of the train, but once I know about it I should do everything in my power to make sure that that other part is successful too. This is not a question of "force", it's just the way software development has to work: Imagine being a developer on any other large, multi-person development effort, and deciding to change the behavior of some fundamental piece of API without talking to the other developers or helping to update the places where that API is referenced. (hint: it's not a successful strategy.) If you don't want to be part of the train, that's fine. If you do, then you have to act in the best common interest. I haven't had much time to think about this problem lately, and given the lack of comment traffic, it appears that's true for the rest of us too. In an effort to kick start the discussion again, here is another idea about how to think about deprecation... (In reply to comment #8) > The following is an interesting read: > http://java.sun.com/j2se/1.4.2/docs/guide/misc/deprecation/deprecation.html > > Sun basically says that deprecation should come as soon as when new (better) > API for a concept has been created. I read this as deprecation being first of > all a signal that something better is available; and only secondary that it may > eventually be removed. > > Again this seems to go towards two "levels" of deprecation: > 1. Marking that something better is available > 2. Marking that it's so bad it's better removed. > The more I think about this, the less I see it as being about "levels" of deprecation, and the more I see it as being about separate concerns: 1) The particular API in question has been marked as being something to avoid. This is true, regardless of whether there is an alternative or whether it will ever be deleted. If you have existing code that uses it, you should consider modifying that code, and you should not build new dependencies on the deprecated API. 2) There *may* be an alternative way to solve the problem this API addressed. Obviously, deprecating some piece of function without having a new (better) alternative is bad, in general, but it's easy to imagine scenarios where there either is no simple mapping from the old way to the new way (e.g. "Mac OS Carbon is deprecated; use Cocoa." ;-) ), or it may even be the case that the component is moving in a new direction and it's no longer reasonable to support capabilities like those provided by the "old" way. 3) At some point, this API may be removed. This is not a question of "badness". As Martin noted in the bug description, there are many reasons why you might want to deprecate API. The thing is though, in many of those cases (e.g. reduce bloat, reduce burden of creating new API), you can't realize the benefit of the deprecation until the old API is actually removed. <- or it's very difficult, at least. As to how each of these concerns are captured, 1) is captured by the presence of an @deprecated tag, and 2) is covered by the presence of explanatory text as described by the Sun doc Martin referenced: Within documentation comments, we define the new paragraph tag "@deprecated". (See JLS, $$184.) It can appear in both class and member documentation comments, and will apply specifically the construct its comment introduces. The tagged paragraph can be empty. If it is not, it should tell the programmer how to avoid using the deprecated feature. There should be "@see" tagged paragraphs which refer to the new versions of the same functionality. Obviously, if there *is* a new alternative, it would be silly to not specify it here, if for no other reason that failing to do so will guarantee many "so what do I do now?" questions get asked on the newsgroups and mailing lists. So that seems perfectly reasonable, but does not address 3). I spoke with Olivier about the potential for adding an additional tag to describe *when* a particular API will be removed, and that seems like something that we could support. My first thought for what this could look like was something like... @until <some release version> ... which appealed just for its symmetry with @since. The problem, of course, is that based on our version numbering rules, you would almost always just write... @until <current major version + 1> ... which doesn't actually tell you anything useful. What's really important is knowing the *date* when it would be removed, so lets consider... @until <date it will be removed> Essentially, the presence of the @until tag would imply that you can assume that that API will be present and that you can continue to use it (still with deprecation warnings) up to that date. After that point, the API should be removed, which will cause errors for anyone attempting to reference it. Our tools would generate errors even if the code is *not* removed. [Part of this is ensuring that the deprecated API continues to function as expected *until* it is removed, but that shouldn't be surprising.] Now, from the point of view of the release train, what is actually important is knowing when the API will be removed, not when it was deprecated, so any deprecations that did not include the @until tag are effectively just informational (i.e. "you shouldn't be using this"). For those where @until is specified, we could easily generate reports that showed which components were at risk, well in advance of when code gets broken, and produce individual "porting guide" entries for each component to help other consumers. Note that, none of this so far has said how much lead time should be provided. I'm willing to believe the rules could be different for projects in their early stages of development, but as I've said before, I favor requiring two years of lead time for anything on the release train. Anyway, it's time to get back to getting M7 out. What do you think both about this and what I said in comment #9? I still believe that part of being on the release train is treating the *whole* train as something we *all* ship. If we think in those terms, are sensitive to the needs of the downstream consumers of what we do, and build support like this to help us, it seems like we'll be ok. @until sounds interesting. Not keen on the time-based idea though. Some API marked @until june 2010 is still valid for use in 2012 if you are using the right version. Similarly, there could be maintenance streams that remain active longer than the next major release so picking the date of the major release as the @until date leaves ambiguous what will happen in the maintenance stream. Having said that, version numbers are hard as we don't know how the rest of the API will change over time. This dictates the flow of version numbers Related to that, how does the removal of deprecated API affect the version number fo the container (package, bundle, feeature, ...). Clearly it is a breaking change, we are simply saying here that it is an acceptable breakage. But should folks on the outside be able to reason about this? This seems like a key/major element. (In reply to comment #11) Thanks for commenting, Jeff. Hopefully the rest of the AC members are tracking this too. There are several points, like requiring 2 years lead time for all breaking changes on all release train projects, that I thought would generate more controversy. > @until sounds interesting. Not keen on the time-based idea though. Some API > marked @until june 2010 is still valid for use in 2012 if you are using the > right version. Similarly, there could be maintenance streams that remain > active longer than the next major release so picking the date of the major > release as the @until date leaves ambiguous what will happen in the maintenance > stream. > I recognize this is a possibility, but honestly think the value would outweigh any ambiguity. Our current situation is that we have no oversight and no ability to reason about deprecation, with the end result being no one ever removes anything -- or at least, they never do it more than once (after they get roasted by their community). Also, I believe maintenance releases can *never* remove API methods, so effectively by definition, the @until tag could only make sense on the main development stream. Of course, it's still possible to have multiple, split development streams and want to only remove the method in one, etc., but this doesn't feel like a common usecase. In any case, this was only one possible way to describe the information that we actually want: An accurate list, available with plenty of lead time, that describes what API is going to be removed and when code that depends on it will break. This strategy appealed to me really only because it put that information close to the code, in a form that our tools could potentially help with. I am definitely happy to hear alternative suggestions. > Having said that, version numbers are hard as we don't know how the rest of the > API will change over time. This dictates the flow of version numbers > > Related to that, how does the removal of deprecated API affect the version > number fo the container (package, bundle, feeature, ...). Clearly it is a > breaking change, we are simply saying here that it is an acceptable breakage. > But should folks on the outside be able to reason about this? This seems like a > key/major element. > I'm not sure what you're getting at here. I don't think anything being proposed puts new constraints on our existing version numbering strategy. (In reply to comment #12) > > @until sounds interesting. Not keen on the time-based idea though. Some API > > marked @until june 2010 is still valid for use in 2012 if you are using the > > right version. Similarly, there could be maintenance streams that remain > > active longer than the next major release so picking the date of the major > > release as the @until date leaves ambiguous what will happen in the maintenance > > stream. > > > I recognize this is a possibility, but honestly think the value would outweigh > any ambiguity. Our current situation is that we have no oversight and no > ability to reason about deprecation, with the end result being no one ever > removes anything -- or at least, they never do it more than once (after they > get roasted by their community). > > Also, I believe maintenance releases can *never* remove API methods, so > effectively by definition, the @until tag could only make sense on the main > development stream. Of course, it's still possible to have multiple, split > development streams and want to only remove the method in one, etc., but this > doesn't feel like a common usecase. from the point of view of someone not "in the know" reading @until June 2009 they would think that in one month that element will be removed. They don't necessarily know/understand the difference between maintenance streams and main line etc. > In any case, this was only one possible way to describe the information that we > actually want: An accurate list, available with plenty of lead time, that > describes what API is going to be removed and when code that depends on it will > break. This strategy appealed to me really only because it put that information > close to the code, in a form that our tools could potentially help with. I am > definitely happy to hear alternative suggestions. Yup. My alternative suggesiton is to use releases not dates. > > Having said that, version numbers are hard as we don't know how the rest of the > > API will change over time. This dictates the flow of version numbers > > > > Related to that, how does the removal of deprecated API affect the version > > number fo the container (package, bundle, feeature, ...). Clearly it is a > > breaking change, we are simply saying here that it is an acceptable breakage. > > But should folks on the outside be able to reason about this? This seems like a > > key/major element. > > > I'm not sure what you're getting at here. I don't think anything being proposed > puts new constraints on our existing version numbering strategy. Our current API/version number relationship is that 3.5 is binary compatible with >= 3.0 and < 3.5. If in 3.5 we finally removed a deprecated type/member from 3.3, 3.3-based things will not work on 3.5. So as a minimum the version number semantics have to be updated to say that 3.x is binary compatible with 3.y where x-2 <= y < x. Failing that, the deletion of the deprecated elements constitute a binary incompatibility and the new version number should be 4.0 (or some such). (In reply to comment #13) > ... > > In any case, this was only one possible way to describe the information that we > > actually want: An accurate list, available with plenty of lead time, that > > describes what API is going to be removed and when code that depends on it will > > break. This strategy appealed to me really only because it put that information > > close to the code, in a form that our tools could potentially help with. I am > > definitely happy to hear alternative suggestions. > > Yup. My alternative suggesiton is to use releases not dates. > Sorry, I misunderstood. You mean releases == release train names, or project release (i.e. what we used to call "marketing") numbers, or component version numbers, or...? To me it seems like the problem with any of the "number" based ones is that, because removing API is a breaking change, by definition, the number will always be "current major version + 1", which doesn't tell you anything about *when* you need to deal with the change. Am I missing something? > ... > Our current API/version number relationship is that 3.5 is binary compatible > with >= 3.0 and < 3.5. If in 3.5 we finally removed a deprecated type/member > from 3.3, 3.3-based things will not work on 3.5. So as a minimum the version > number semantics have to be updated to say that 3.x is binary compatible with > 3.y where x-2 <= y < x. Failing that, the deletion of the deprecated elements > constitute a binary incompatibility and the new version number should be 4.0 > (or some such). > Well, I just assumed it would be 4.0, since it *is* a binary incompatibility. Note: I realize that could be a problem for us on the platform, given how we've been saying "e4 turns into Eclipse 4.0", but we aren't actually going to remove stuff from the 3.x stream. On bundle/package versions, I think we would need to increment the major number on removal of deprecated API. This will "break" clients whose version ranges exclude the next major version, but that's a good thing: it forces them to revisit their usage to make sure they are still working well in the new version with the removed API. The only alternative I can think of to @until <date> would be @until <release name> (such as @until Galileo). We would also need to make sure the next n+2 releases have names at all times. Any system based on @until <version number> doesn't seem to convey any information for the reasons McQ gave. If you say @until 4.0, it doesn't help because they don't know when the 4.0 release will occur (this year, next year, etc?). To me that reads, "it will be here until it isn't here". I'm not sure which of the two (date or name) is more useful. Perhaps an in between solution would be "@until release of June 2010". This is more helpful for clients that aren't insiders who would know what the release of June 2010 might be called. yes, release = marketing name. Individual package/bundle version numbers may progress and a variable rate. Saying "@until relase in June xxx" is ok but seems like a poor man's way of saying "@until Indigo <whatever is two after Galileo>". IMHO it however better than simply @until June 2010 (that I find very ambiguous) Related thought. Most of the discussion here has presumed that projects release on the train. So we say things like "two releases" etc. It is entirely likely (and perhaps currently true) that some projects release more frequently. For them, 2 releases might mean 9 months. Thoughts? (In reply to comment #16) > yes, release = marketing name. Individual package/bundle version numbers may > progress and a variable rate. Saying "@until relase in June xxx" is ok but > seems like a poor man's way of saying "@until Indigo <whatever is two after > Galileo>". IMHO it however better than simply @until June 2010 (that I find > very ambiguous) > I'm more interested in having us do *something* here than I am about what it looks like. I guess I am somewhat worried that the marketing name is just as likely to be confusing, and has related issues as John notes in comment #15, but if we could get agreement on using the marketing name, that would be good enough. > Related thought. Most of the discussion here has presumed that projects > release on the train. So we say things like "two releases" etc. It is > entirely likely (and perhaps currently true) that some projects release more > frequently. For them, 2 releases might mean 9 months. Thoughts? > So, this is an important question. I tend to focus on the release train, since I believe that is where we need to make the greatest effort to ensure we can make progress without breaking each other, but projects that aren't part of the release train can still build up webs of dependencies that they need to deal with. Clearly, using marketing names in the @until tag would not make sense for a project that is not releasing on the train and does not have a coincident release cycle. As I've said before, I believe two *years* should be the minimum delay before removing a deprecated API. I actually believe this should be true for both release train and other projects. I realize this is a burden on new projects (as was captured by Martin's comment "Eclipse-wide consistency vs. different project maturity levels"), but that burden is part of what makes us work so hard to build solid API in the first place. Agreed on the 2 years model. for wording we need a way of saying "this code will be removed in major releases starting <now + 2 years>" I thnk we are agreeing on the semantics etc but struggling a bit with the communication of the semantics. (In reply to comment #18) > Agreed on the 2 years model. > > for wording we need a way of saying "this code will be removed in major > releases starting <now + 2 years>" > > I thnk we are agreeing on the semantics etc but struggling a bit with the > communication of the semantics. > Ok. Anyone else have a suggestion for how to describe it? I still believe that putting the information at the code site (and then mining it to generate other doc) makes the most sense. I think it would make sense to have a version number, release train name, and date in the tag:
@until 4.0 Indigo (June 2010)
The version number is helpful when you're using an old version. It lets you know that as long as you stay on the old version, you are OK - and if you plan to move to the new version, you must migrate. The marketing name and dates provide more context to humans - i.e. has it already happened (available) or is it in the future.
For projects that don't have release trains/dates, the version number alone would still work.
From a tooling point of view, the version number is helpful. Our API descriptions don't include marketing names or dates...
I don't think a @until tag is going to work very well, since it's talking about the future, and things might change after the particular release that includes the tag has shipped. So the tag information can easily get stale. Instead, how about something like this: Include a *link* to a site (an API information repository, if you will) that has *current* information about that API, such as: -- deprecated in 3.3 -- to be removed in 3.6 (or whatever) -- alternative API information, if any The Eclipse Project has defined its deprecation policy in http://wiki.eclipse.org/Eclipse/API_Central/Deprecation_Policy Projects are welcome to use that policy as a template for adopting themselves. For now, the Architecture Council is not interested in "pushing" a policy to projects, but projects are invited to adopt the Platform one. I am marking this bug fixed since a policy has been defined and published. Some of the ideas for follow-up work which were mentioned in this bug should be tracked by separate items moving forward. |