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

Reply via email to