On 2011-12-02, henrib wrote: > It seems to me we have a hard time allowing both stability and usability. > Stability of APIs does not contradict usability of the library, at least > should not.
I'm glad you say that right at the beginning as the "versus" in the subject line seems to imply something else. 8-) > Some of us are looking for very long term/stable/high-quality solutions > because they need to aggregate lost of components, the stability users. > Others are looking for best-of-breed/narrow scope/malleable libraries a with > a guaranteed quality, the usability users. [Aside: is best-of-breed really impossible in a stable environment?] I don't think this is all there is to it. As one of the few people who still see value in Gump I tend to be in the stability camp - if there really are only these two choices. But it is more about the impact a new release has on the users than the number of components anybody aggregates. I don't think anybody likes the idea of having to modify code every time you update your dependencies. > Thus the importance of clearly stating in our libraries what is > 'stable' and what is 'usable'. While I like the idea to explicitly mark what you consider a stable/reliable API I don't think I like the tags. Or at least the tag "usable". That it implies the "stable" parts are not usable makes me itch. > As an kickstart proposal, may be something as simple as 2 annotations > actually could be enough: @stable, @usable. > @stable meaning the contract this API represents will not change without > being first @deprecated > @usable meaning this API is valid for this major version but may change in > each minor with no warning > We might also use a clear 'internal' sub-package name as a frontier > delimiter on the same rule. Maybe we actually have three sorts of public APIs * APIs that we promise not to break unless we perform a major relase in which case we also change package names (and artifactIds). This is what you call @stable. * APIs that may break in minor releases. What you call @usable There is some danger to it in that you mark too many parts unstable and forget about them. I really think users prefer stable APIs to begin with unless the unstable ones offer important features and promise to become stable at one point in time. Compress has a package that has *experimental* warnings in Javadocs all over the place. It has carried this label for four minor relases now. Is it still experimental? I think anything not @stable needs to be revisited from time to time. * APIs that are only public for technical reasons but really are internal to the component. I think these are different from what you call @usable. And these should be allowed to change without warning as long as users are aware of the policy. So yes, I understand and agree that we sometimes want to add features and push them out to users before we understand them well enough to provide a stable API. And I really welcome any approach of explicitly marking those parts so that users - and people reviewing releases - know what to expect. But I also think the non-stable APIs have to be reconsidered from time to time and eventually become stable. Stefan --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
