commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Thomas Neidhart <>
Subject Re: [math] next step
Date Tue, 09 Apr 2013 18:01:13 GMT
On 04/09/2013 07:51 PM, Phil Steitz wrote:
> On 4/8/13 10:24 AM, Gilles wrote:
>> On Mon, 8 Apr 2013 17:33:11 +0100, sebb wrote:
>>> On 8 April 2013 13:22, Gilles <> wrote:
>>>> On Mon, 8 Apr 2013 11:52:25 +0100, sebb wrote:
>>>>> On 8 April 2013 08:14, Luc Maisonobe <>
>>>>> wrote:
>>>>>  Hi Gary (and Sebb who had similar concerns),
>>>>>> Le 08/04/2013 00:33, Gary Gregory a écrit :
>>>>>>> I would only go back and bother with creating a branch when
>>>>>> it is
>>>>>>> needed. As for a repackage I would only do that if I knew
>>>>>> for certain
>>>>>>> that I want to break BC.
>>>>>> Yes, we need (not want) to break compatibility. This is the
>>>>>> reason we
>>>>>> had to postpone several issues. These issues change API. Typical
>>>>>> examples are removing packages, removing classes, removing
>>>>>> user public
>>>>>> methods, changing method signatures, puching methods upwards from
>>>>>> classes to interfaces, changing interfaces ...
>>>>> Might be a good time to re-organise the code into external and
>>>>> internal
>>>>> classes.
>>>> I raised a similar concern some time ago.
>>>>  Ideally one would use public/protected vs. package/private for
>>>> that, but
>>>>> that's not always possible with Java.
>>>> As far as there is no overall design, I don't think that it is
>>>> realistic,
>>>> even if it would be possible.
>>>> Focus on self-consistency is often met with reluctance to
>>>> correct the
>>>> design
>>>> when it conflicts with established use.
>>>>  But so long as a class is clearly marked as being internal to
>>>> Math, I
>>>>> think
>>>>> it's OK for the API to change at will - just as would be the
>>>>> case for
>>>>> changing the signtaure of a private or package method in any
>>>>> class.
>>>> This is obviously not the Commons policy (cf. rules akin to
>>>> "Clirr must be
>>>> clean for a minor release"). [Which is understandable from a
>>>> practical
>>>> point-of-view.]
>>>> As mentioned quite a number of times, most of the problems could be
>>>> considered
>>>> transient with a "Release early, release often" policy where we
>>>> don't
>>>> hesitate
>>>> to refactor and change the base package name. Better for
>>>> developers and no
>>>> loss
>>>> for  conservative users.
>>> Changing package name is perhaps easy for the Commons component
>>> developer.
>>> And if by conservative user you mean a user who does not want or
>>> need to
>>> upgrade, I agree.
>>> But not so easy for the end user, who may need a bug fix in one
>>> component,
>>> but may not have any control over 3rd party libraries that use
>>> Commons
>>> components.
>>> IIRC even Commons VFS developers had some problems with other
>>> Commons
>>> components releases that weren't compatible.
>>> A package name change necessarily means more than just a global
>>> edit of the
>>> source and recompile.
>>> If the package rename were the *only* change, there would be no
>>> point doing
>>> it.
>> Of course. Luc gave many examples of why the name should change.
>> Overall, to improve the design without getting in the way of users
>> who
>> happily use 3.x (and will do so forever after).
>> For bug fixes they will have to use "o.a.c.math4".
>> Or step forward and offer to maintain a (compatible) "math3" line.
>>> There must be some other API changes that have forced the package
>>> change.
>>> At least some end users will also have to change their source
>>> accordingly.
>>> Release early, release often is not an inherently good idea - it
>>> has some
>>> serious drawbacks.
>> I have put this subject on discussion (too) many times.
>> My humble opinion is (still) that CM is so broad in scope that it
>> will remain
>> forever in alpha state. [Here "alpha" is not meant to related to
>> the quality
>> of the code but to the stability of the design: new functionality
>> or new user's
>> and developers' insight will question the soundness of the design.
>> And,
>> without a clearly stated rationale for everything present and
>> future, the only
>> reasonable attitude is to keep evolving. The alternative is that
>> the cruft
>> will accumulate to the point where someone will deem more
>> efficient to start a
>> new library from scratch (or fork CM).]
> I agree that we will likely always have a mix of alpha - both design
> and implementation quality - and stable code in [math].  When you
> look at the incompatible changes we have done and have queued up for
> 4.0, most are localized and many are not really that significant
> from a user-required change standpoint.  I also agree with you,
> Gilles, that more frequent releases are better.  I honestly don't
> think we have the resources to maintain multiple lines and, having
> briefly tried to do this to backport some stuff to 2.x, I am not
> sure we *can* do it with quality, because some of the API changes
> have been to fix bugs that we have no idea how to address without them.
> So we need to figure out how to keep moving forward in a way that
> works.  Here are some alternatives.  There are probably others.
> 0) Status quo - there are infinitely many natural numbers.  Just
> keep using them: math4, math5, ...., math100,....  The main problem
> with this is Seb's point - unstable APIs are not fun to use.
> 1) Separate internal vs external API.  This will help a little; but
> unfortunately it is the public API that we often get wrong initially
> and need to fix.  This is still probably worth looking carefully at.
> 2) Separate "stable" vs "experimental" APIs.  The problem here is
> how do we decide when something is "stable" (and what does it mean
> once we have decided that) and where do we draw boundaries.  I was
> going to use the example of the stat package as having been pretty
> stable up to now; but there is in fact an incompatible change queued
> now for SpearmansCorrelation.

I really like the approach that is used in google guava, to mark new
features/classes as @Beta until they are considered stable (we can
discuss about the transition process).

Otherwise we will always be in the situation that new features are
postponed/blocked as we are unsure if the API is "good enough". Any
mistake, even a small one, has to stay till the next major release, and
this is sometimes not acceptable.

Also completely changing the package to o.a.c.mathX every year (or 2),
is far from ideal. We should strive for stable APIs, but coming up with
a good one takes time and experience (and mistakes to learn from).

Actually, I am now in a similar situation for collections, where I
wanted to add a new Trie interface, but it also means that if there are
flaws in it, we are screwed for the 4.0 release line.

> 3) Split the whole library into smaller components that are released
> individually.  This will naturally reduce the incidence of
> incompatible change at the sub-component level.  This probably
> forces us to move out of Commons and also has the downside that we
> may lose critical mass at the subcomponent level and it may be
> confusing to users.
> 4) Try more aggressively to avoid incompatible change by waiting a
> little longer to commit / release new APIs and limiting the amount
> of refactoring for nonfunctional reasons (changing code that works
> functionally in an API-incompatible way).
> Just some initial thoughts. 
> In answer to Luc's initial question, I think it would be better to
> hold off a little while on committing the incompatible changes if we
> can, just so we can easily cut a 3.2.1 if necessary to address any
> bad bugs that emerge over the next month or so.  The stuff I am
> working on can all be done compatibly, but If that is too onerous
> for others, I am OK not waiting.  If we need a 3.2.1 branch later,
> we can always just create it from the 3.2 release tag.


To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message