You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by Phil Steitz <ph...@gmail.com> on 2005/06/12 17:13:08 UTC
[math] 1.1 clirr report, backward compatibility
A clirr report comparing 1.0 and 1.1-dev is available here:
http://people.apache.org/~psteitz/math-1.1-clirr.txt
The ERRORs shown are due to the addition of the submatrix methods to
the RealMatrix and BigMatrix interfaces. I would like to remove the
interface changes (leaving the new methods in the impls) to preserve
compatibility. Any objections to this? Any other problems?
Phil
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [math] 1.1 clirr report, backward compatibility
Posted by Rodrigo di Lorenzo Lopes <br...@terra.com.br>.
Hi,
No, I dont see problems in freeze interface, with an exception:
_ Java (Commons Math) is not a friendly with linear algebra. We are
using vectors like one row (or column) matrix (it is a real pain to use
vectors this way), and it is not uncommon multiplies arrays by Euclidean
vectors. Moreover vectors are not only Euclidean Spaces (in fact,
matrixes are generalization of Vectors) So, to reduce the contact
surface and to treat most abstrac concepts, I´d like that Matrix
interface inherences from a Vector interface. And using more abstract
interface could be easier to freeze a interface.
[]´s
Rodrigo
Mark Diggory wrote:
> Very cool Phil,
>
> So, when (which version) would we make this methods available? I'm
> concerned that this report suggests that adding methods to an interface
> is breaking backward compatibility. When I think the opposite, in that
> its breaking "forwards compatibility" of existing application. You tend
> to need to break forwards compatibility to make progress on an API's
> design.
>
> In out case, adding these methods should only effect a small subset of
> the user base (specifically those who may have extended either the
> interface or the implementation on their own, effecting them because the
> signatures may be incompatible). I'm not even sure if we have anyone in
> our userbase actually doing this...
>
> Stray Thoughts:
>
> 1.) Should versioning drive development or vis versa (maybe we're
> already working on 2.0 if we're breaking compatibility with 1.0)?
>
> 2.) I've been dealing with versioning on another project lately, we
> adopted the following standard versioning scheme
>
> xx.yy.zz
>
> where
>
> xx: Major version number incremented when major backward incompatible
> changes occur.
> yy: Minor version number incremented when forwards incompatible changes
> occur
> zz: Patch version number, incremented when changes neither cause
> forwards or backwards incompatibility,
>
> 3.) Maybe we should consider making the Interfaces "final"? This would
> stop users from extending them and allow us more room to make
> additions/removals to the interfaces without the above usecase I
> initially referred to occurring above...
>
> -Mark
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [math] 1.1 clirr report, backward compatibility
Posted by Phil Steitz <ph...@gmail.com>.
I think we all agree that the matrix API needs work and I would prefer
not to hold the 1.1 release until we have worked out what will have to
be 2.0 changes. So, I propose that for 1.1, we simply remove the new
methods from the interfaces, but leave them in the implementations.
If there are no objections, I will do that so we can move the release
along.
I agree with Stephen that 1) we can't make incompatible changes in a
1.x release and 2) we should try to avoid introducing incompatible
changes (to existing classes / interfaces) even in 2.0. I agree with
Rodrigo and others, though, that the linear package needs to be
improved. Lets pick this discussion back up once we have 1.1 out.
Phil
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [math] 1.1 clirr report, backward compatibility
Posted by Rodrigo di Lorenzo Lopes <br...@terra.com.br>.
So, only to put my opinion in vote terms:
+1 could break backward compatibility in release 2.0 if necessary:
We must change the API. There are so many to improve. We cannot be
plastered , specially now that commons math is still far from a stable
API. But I agree with backward compatibility directions anyway.
+1 to create a most abstract interface like:
interface InterfaceFoo2 extends InterfaceFoo1
The reasons I´ve already posted in last mail.;)
Mark Diggory wrote:
> Simon Kitching wrote:
>
>> On Mon, 2005-06-13 at 14:47 +1200, Simon Kitching wrote:
>>
>>
>>> Hi Mark,
>>>
>>> In the example below, I would regard this change as being an
>>> incompatible change anyway. Code using the new API isn't compatible
>>> with
>>> code implementing the old API because an exception can be thrown when
>>> invoking a normal-looking method. Maybe if the new method's javadoc
>>> explicitly states that "some implementations may not support this
>>> operation and will throw an exception" but even then it feels wrong to
>>> me.
>>>
>>
> Well, its not elegant, the exception handling establishes that there
> is a forwards compatibility issue with the third parties
> implementation (which they would then have to correct). Ultimately,
> either way the third party needs to make the modification, the Stub
> just delays this fact. Which is better, break during compilation, or
> break during runtime? This shows a downfall in the strategy, a break
> during compilation is more likely to be caught by the third party
> developers and an exception is more likely to be caught by the third
> parties "users". It'd seem better if the incompatibility were caught
> by the developers, so in this way my example sucks. The simplest case
> ends up the best. Just modify the Interface directly (yes, on a Major
> release version) and let the third party developers adapt, thats
> software evolution.
>
>>> There are some cases where this pattern does work, though.
>>>
>>> Commons-digester declares Rule as an abstract class rather than an
>>> interface. This allowed the begin/body/end methods to be enhanced with
>>> additional parameters, with the new methods delegating back to the old
>>> ones by default. This pattern is also described in the eclipse doc
>>> referenced by Stephen below. There isn't any interface involved,
>>> though:
>>> an abstract class is used *in place of* an interface.
>>>
>>> In commons-digester 2.x (nowhere near release yet), Action is an
>>> interface whose javadoc declares explicitly that it may change in minor
>>> releases, and that users should subclass AbstractAction instead:
>>> http://svn.apache.org/repos/asf/jakarta/commons/proper/digester/branches/digester2/src/java/org/apache/commons/digester2/
>>>
>>>
>>>
>>
>>
>> I should note that the reason that digester2 adopted the "interface +
>> abstract implementation" rather than the digester1 "abstract class
>> instead of interface" approach was that people pointed out:
>> * interfaces are useful for generating dynamic proxies at runtime.
>> * mock objects for unit testing are easier done on interfaces
>>
>>
>> Neither of these have problems associated with evolving the interface;
>> the dynamic problem of course isn't relevant and the unit tests can
>> assume to be only internal to the project and can be updated to match
>> the new release.
>>
>> And where 99% of user code is simply *using* the API instead of
>> *implementing* the API, they can deal with the nice and traditional
>> interface. Only implementers of the API really need to care about the
>> existence of the abstract class.
>>
>>
>>
> Not only this but that 1% actually implementing the API is more than
> likely going to be lurking on your developer list and contributing to
> its development ;-)
>
> IMHO, our current userbase is simply just using the API at this point
> and will tolerate interface changes if it improves the API, it would
> be an interesting poll to see if anyone actually implemented their own
> Matrix classes on our interfaces and I'd be extremely surprised if it
> had.
>
> -Mark
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: commons-dev-help@jakarta.apache.org
>
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [math] 1.1 clirr report, backward compatibility
Posted by Mark Diggory <md...@gmail.com>.
Simon Kitching wrote:
>On Mon, 2005-06-13 at 14:47 +1200, Simon Kitching wrote:
>
>
>>Hi Mark,
>>
>>In the example below, I would regard this change as being an
>>incompatible change anyway. Code using the new API isn't compatible with
>>code implementing the old API because an exception can be thrown when
>>invoking a normal-looking method. Maybe if the new method's javadoc
>>explicitly states that "some implementations may not support this
>>operation and will throw an exception" but even then it feels wrong to
>>me.
>>
>>
Well, its not elegant, the exception handling establishes that there is
a forwards compatibility issue with the third parties implementation
(which they would then have to correct). Ultimately, either way the
third party needs to make the modification, the Stub just delays this
fact. Which is better, break during compilation, or break during
runtime? This shows a downfall in the strategy, a break during
compilation is more likely to be caught by the third party developers
and an exception is more likely to be caught by the third parties
"users". It'd seem better if the incompatibility were caught by the
developers, so in this way my example sucks. The simplest case ends up
the best. Just modify the Interface directly (yes, on a Major release
version) and let the third party developers adapt, thats software evolution.
>>There are some cases where this pattern does work, though.
>>
>>Commons-digester declares Rule as an abstract class rather than an
>>interface. This allowed the begin/body/end methods to be enhanced with
>>additional parameters, with the new methods delegating back to the old
>>ones by default. This pattern is also described in the eclipse doc
>>referenced by Stephen below. There isn't any interface involved, though:
>>an abstract class is used *in place of* an interface.
>>
>>In commons-digester 2.x (nowhere near release yet), Action is an
>>interface whose javadoc declares explicitly that it may change in minor
>>releases, and that users should subclass AbstractAction instead:
>>http://svn.apache.org/repos/asf/jakarta/commons/proper/digester/branches/digester2/src/java/org/apache/commons/digester2/
>>
>>
>>
>
>I should note that the reason that digester2 adopted the "interface +
>abstract implementation" rather than the digester1 "abstract class
>instead of interface" approach was that people pointed out:
> * interfaces are useful for generating dynamic proxies at runtime.
> * mock objects for unit testing are easier done on interfaces
>
>
>Neither of these have problems associated with evolving the interface;
>the dynamic problem of course isn't relevant and the unit tests can
>assume to be only internal to the project and can be updated to match
>the new release.
>
>And where 99% of user code is simply *using* the API instead of
>*implementing* the API, they can deal with the nice and traditional
>interface. Only implementers of the API really need to care about the
>existence of the abstract class.
>
>
>
Not only this but that 1% actually implementing the API is more than
likely going to be lurking on your developer list and contributing to
its development ;-)
IMHO, our current userbase is simply just using the API at this point
and will tolerate interface changes if it improves the API, it would be
an interesting poll to see if anyone actually implemented their own
Matrix classes on our interfaces and I'd be extremely surprised if it had.
-Mark
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [math] 1.1 clirr report, backward compatibility
Posted by Simon Kitching <sk...@apache.org>.
On Mon, 2005-06-13 at 14:47 +1200, Simon Kitching wrote:
> Hi Mark,
>
> In the example below, I would regard this change as being an
> incompatible change anyway. Code using the new API isn't compatible with
> code implementing the old API because an exception can be thrown when
> invoking a normal-looking method. Maybe if the new method's javadoc
> explicitly states that "some implementations may not support this
> operation and will throw an exception" but even then it feels wrong to
> me.
>
> There are some cases where this pattern does work, though.
>
> Commons-digester declares Rule as an abstract class rather than an
> interface. This allowed the begin/body/end methods to be enhanced with
> additional parameters, with the new methods delegating back to the old
> ones by default. This pattern is also described in the eclipse doc
> referenced by Stephen below. There isn't any interface involved, though:
> an abstract class is used *in place of* an interface.
>
> In commons-digester 2.x (nowhere near release yet), Action is an
> interface whose javadoc declares explicitly that it may change in minor
> releases, and that users should subclass AbstractAction instead:
> http://svn.apache.org/repos/asf/jakarta/commons/proper/digester/branches/digester2/src/java/org/apache/commons/digester2/
>
I should note that the reason that digester2 adopted the "interface +
abstract implementation" rather than the digester1 "abstract class
instead of interface" approach was that people pointed out:
* interfaces are useful for generating dynamic proxies at runtime.
* mock objects for unit testing are easier done on interfaces
Neither of these have problems associated with evolving the interface;
the dynamic problem of course isn't relevant and the unit tests can
assume to be only internal to the project and can be updated to match
the new release.
And where 99% of user code is simply *using* the API instead of
*implementing* the API, they can deal with the nice and traditional
interface. Only implementers of the API really need to care about the
existence of the abstract class.
Regards,
Simon
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [math] 1.1 clirr report, backward compatibility
Posted by Simon Kitching <sk...@apache.org>.
Hi Mark,
In the example below, I would regard this change as being an
incompatible change anyway. Code using the new API isn't compatible with
code implementing the old API because an exception can be thrown when
invoking a normal-looking method. Maybe if the new method's javadoc
explicitly states that "some implementations may not support this
operation and will throw an exception" but even then it feels wrong to
me.
There are some cases where this pattern does work, though.
Commons-digester declares Rule as an abstract class rather than an
interface. This allowed the begin/body/end methods to be enhanced with
additional parameters, with the new methods delegating back to the old
ones by default. This pattern is also described in the eclipse doc
referenced by Stephen below. There isn't any interface involved, though:
an abstract class is used *in place of* an interface.
In commons-digester 2.x (nowhere near release yet), Action is an
interface whose javadoc declares explicitly that it may change in minor
releases, and that users should subclass AbstractAction instead:
http://svn.apache.org/repos/asf/jakarta/commons/proper/digester/branches/digester2/src/java/org/apache/commons/digester2/
Regards,
Simon
--
A. Because it breaks the logical sequence of discussion
Q. Why is top posting bad?
On Sun, 2005-06-12 at 22:21 -0400, Mark Diggory wrote:
> This is where the strategy I was referring to comes in. Lets say for
> instance that the following API is the case:
>
> public interface Foo {
> public Object getBar();
> }
>
> With the following "Stub" implementation.
>
> public class FooImpl implements Foo {
> public Object getBar() {
> throw new UnsupportedOperationException();
> }
> }
>
> A third party implements this Stub like so:
>
> public class MyFooImpl extends FooImpl {
> public Object getBar() {
> return new String("Bar");
> }
> }
>
> After which the designers of the Foo API decide its important to also
> provide a setter for Foo. So they add the method to both the stub and
> the interface like so:
>
> public interface Foo {
> public Object getBar();
> public void setBar(Object bar);
> }
>
> public class FooImpl implements Foo {
> public Object getBar() {
> throw new UnsupportedOperationException();
> }
> public void setBar(Object bar) {
> throw new UnsupportedOperationException();
> }
> }
>
> Now, was third parties implementation broken because of this interface
> change? No. The Stub provides continued backward compatibility for the
> thirdparty implementation.
>
> -Mark
>
> Stephen Colebourne wrote:
>
> >
> > Simon Kitching wrote:
> >
> >> So looking at possible solutions...
> >>
> >> The current situation is:
> >> interface Foo
> >> class Impl implements Foo
> >>
> >> Is it possible to do this?
> >> interface ExtendedFoo implements Foo
> >> class Impl implements ExtendedFoo
> >>
> >> In this way, Foo doesn't change, but new code can pass objects around as
> >> ExtendedFoo in order to access the new functionality.
> >>
> >> [NB: I'm not actually suggesting a literal use of the prefix Extended. A
> >> real, meaningful, name should be selected]
> >>
> >> Alternatively how about this?
> >> interface NewStuff
> >> class Impl implements Foo, NewStuff
> >
> >
> > Indeed, all are possible solutions, as is
> > interface Foo2 extends Foo
> >
> > Also, if you haven't read it,
> > http://eclipse.org/eclipse/development/java-api-evolution.html is a
> > *very* good read on this topic.
> >
> > Stephen
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [math] 1.1 clirr report, backward compatibility
Posted by Mark Diggory <md...@gmail.com>.
This is where the strategy I was referring to comes in. Lets say for
instance that the following API is the case:
public interface Foo {
public Object getBar();
}
With the following "Stub" implementation.
public class FooImpl implements Foo {
public Object getBar() {
throw new UnsupportedOperationException();
}
}
A third party implements this Stub like so:
public class MyFooImpl extends FooImpl {
public Object getBar() {
return new String("Bar");
}
}
After which the designers of the Foo API decide its important to also
provide a setter for Foo. So they add the method to both the stub and
the interface like so:
public interface Foo {
public Object getBar();
public void setBar(Object bar);
}
public class FooImpl implements Foo {
public Object getBar() {
throw new UnsupportedOperationException();
}
public void setBar(Object bar) {
throw new UnsupportedOperationException();
}
}
Now, was third parties implementation broken because of this interface
change? No. The Stub provides continued backward compatibility for the
thirdparty implementation.
-Mark
Stephen Colebourne wrote:
>
> Simon Kitching wrote:
>
>> So looking at possible solutions...
>>
>> The current situation is:
>> interface Foo
>> class Impl implements Foo
>>
>> Is it possible to do this?
>> interface ExtendedFoo implements Foo
>> class Impl implements ExtendedFoo
>>
>> In this way, Foo doesn't change, but new code can pass objects around as
>> ExtendedFoo in order to access the new functionality.
>>
>> [NB: I'm not actually suggesting a literal use of the prefix Extended. A
>> real, meaningful, name should be selected]
>>
>> Alternatively how about this?
>> interface NewStuff
>> class Impl implements Foo, NewStuff
>
>
> Indeed, all are possible solutions, as is
> interface Foo2 extends Foo
>
> Also, if you haven't read it,
> http://eclipse.org/eclipse/development/java-api-evolution.html is a
> *very* good read on this topic.
>
> Stephen
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: commons-dev-help@jakarta.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [math] 1.1 clirr report, backward compatibility
Posted by Stephen Colebourne <sc...@btopenworld.com>.
Simon Kitching wrote:
> So looking at possible solutions...
>
> The current situation is:
> interface Foo
> class Impl implements Foo
>
> Is it possible to do this?
> interface ExtendedFoo implements Foo
> class Impl implements ExtendedFoo
>
> In this way, Foo doesn't change, but new code can pass objects around as
> ExtendedFoo in order to access the new functionality.
>
> [NB: I'm not actually suggesting a literal use of the prefix Extended. A
> real, meaningful, name should be selected]
>
> Alternatively how about this?
> interface NewStuff
> class Impl implements Foo, NewStuff
Indeed, all are possible solutions, as is
interface Foo2 extends Foo
Also, if you haven't read it,
http://eclipse.org/eclipse/development/java-api-evolution.html is a
*very* good read on this topic.
Stephen
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [math] 1.1 clirr report, backward compatibility
Posted by Simon Kitching <sk...@apache.org>.
So looking at possible solutions...
The current situation is:
interface Foo
class Impl implements Foo
Is it possible to do this?
interface ExtendedFoo implements Foo
class Impl implements ExtendedFoo
In this way, Foo doesn't change, but new code can pass objects around as
ExtendedFoo in order to access the new functionality.
[NB: I'm not actually suggesting a literal use of the prefix Extended. A
real, meaningful, name should be selected]
Alternatively how about this?
interface NewStuff
class Impl implements Foo, NewStuff
Regards,
Simon
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [math] 1.1 clirr report, backward compatibility
Posted by Phil Steitz <ph...@gmail.com>.
I agree, strongly, with Stephen on this for [math] and commons in
general. That's why I asked so many times if we had the API right
before releasing 1.0. In retrospect, the linear stuff should probably
have been held back, but we released it so we need to maintain
comapability.
I also agree with Mark that the linear API is less flexible than the
rest of math and I would like to provide a way for Rodrigo and others
to extend naturally to make the whole package more useful. I am sure
that we can find creative ways to do this without breaking binary or
source compatibility.
> Again, I stress this point. Commons has many interfaces that we would
> like to change after the fact (eg. MultiMap in [collections], or
> DynaProperty in [beanutils]). AFAIN, none have been changed even over a
> major release version (awaiting someone to prove me wrong...).
>
> If this were code within a company, then it wouldn't matter.
Actually, if the company is large and there are lots of projects that
depend on the component, the same situation applies ;-)
> But this is
> a publicly available, fully released, API. Open source is sometimes a
> pain to work with. This is one of those occasions. And IMHO, all commons
> would suffer were the change to happen.
>
> For the record (and in accordance with informing people at the earliest
> point possible), I will -1 a 1.x release that changes an interface. I
> will -0/-1 a 2.0 release that changes an interface depening on further
> discussion. (Bearing in mind that my vote is non-binding, as a non-math
> committer)
Your release votes *are* binding. Thanks for the feedback and thanks
in advance for reviewing the RC(s) ;-)
Phil
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [math] 1.1 clirr report, backward compatibility
Posted by Mark Diggory <md...@gmail.com>.
Stephen,
First, thanks for the viewpoint, and I agree that API changes should be
well thought out and well planned. But we appear to have very differing
opinions on the need to allow software to evolve.
Stephen Colebourne wrote:
> Mark Diggory wrote:
>
>> I would initially agree, but Math is still in early development (our
>> second minor release). I really doubt anyone has created any
>> alternate implementations of these interfaces that are in any
>> production env. I think Math is for the time being an implementation,
>> not a standard. If others were implementing any of our API's I think
>> we would have found out by now.
>
> Why? How would we know? Users just download the jar, and implement
> away. They don't need to talk back to the list. By defining a 1.0
> release [math] said 'this is complete' and 'these interfaces will not
> change'. If we were talking 0.6 to 0.7 here it wouldn't matter.
And if they do, they should understand that its a new API and subject to
some evolution within constraints outlined in our versioning
specification. 2.0 can and should be allowed to have changes in
interface because its more important to make the improvements requested
from our userbase than to not make a change for the benefit of some
silent party. If your using the API and have a problem with a change,
speak up, we'll be glad to work with you to come to a solution.
>> So I'll ask again, when is the appropriate time to add methods to an
>> interface? Seems your suggesting "never". I disagree, I believe that
>> in our case these modifications can be made and the result will be a
>> major version release, so I would say these changes go into 2.0,
>
> Again, I stress this point. Commons has many interfaces that we would
> like to change after the fact (eg. MultiMap in [collections], or
> DynaProperty in [beanutils]). AFAIN, none have been changed even over
> a major release version (awaiting someone to prove me wrong...).
>
Why not over a major version? Major versions are opportunities to fully
break backwards / forwards compatibility and evolve the API. It sounds
sad to me that you guys had opportunities to evolve the Collections API
and didn't take them because you think you'll loose users. I wonder how
many you failed to gain because you didn't make such improvements?
> If this were code within a company, then it wouldn't matter. But this
> is a publicly available, fully released, API. Open source is sometimes
> a pain to work with. This is one of those occasions. And IMHO, all
> commons would suffer were the change to happen.
From my perspective, much of commons (and apache in general) is quite
adept at adapting to changes in a package over time.
Did you do any tests to see what in commons was dependent on those
modifications? Did you talk to those specific developers it would appear
to effect and get their viewpoints?
> For the record (and in accordance with informing people at the
> earliest point possible), I will -1 a 1.x release that changes an
> interface. I will -0/-1 a 2.0 release that changes an interface
> depening on further discussion. (Bearing in mind that my vote is
> non-binding, as a non-math committer)
Yes, I would -1 a 1.x release interface change as well.
I think blocking all interface changes across versions, even major
versions is just too extreme a viewpoint. OS is about building and
evolving "useful" API's. A library full half baked packages because none
were given the leway to evolve isn't very useful at all. In the end you
just end up with allot of users forking the codebase and not
contributing back to the project because no one wants to wait around for
improvements that never get made. So I would wholeheartedly support a
2.x interface change.
-Mark
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [math] 1.1 clirr report, backward compatibility
Posted by Stephen Colebourne <sc...@btopenworld.com>.
Mark Diggory wrote:
> I would initially agree, but Math is still in early development (our
> second minor release). I really doubt anyone has created any alternate
> implementations of these interfaces that are in any production env. I
> think Math is for the time being an implementation, not a standard. If
> others were implementing any of our API's I think we would have found
> out by now.
Why? How would we know? Users just download the jar, and implement away.
They don't need to talk back to the list. By defining a 1.0 release
[math] said 'this is complete' and 'these interfaces will not change'.
If we were talking 0.6 to 0.7 here it wouldn't matter.
> So I'll ask again, when is the appropriate time to add methods to an
> interface? Seems your suggesting "never". I disagree, I believe that in
> our case these modifications can be made and the result will be a major
> version release, so I would say these changes go into 2.0,
Again, I stress this point. Commons has many interfaces that we would
like to change after the fact (eg. MultiMap in [collections], or
DynaProperty in [beanutils]). AFAIN, none have been changed even over a
major release version (awaiting someone to prove me wrong...).
If this were code within a company, then it wouldn't matter. But this is
a publicly available, fully released, API. Open source is sometimes a
pain to work with. This is one of those occasions. And IMHO, all commons
would suffer were the change to happen.
For the record (and in accordance with informing people at the earliest
point possible), I will -1 a 1.x release that changes an interface. I
will -0/-1 a 2.0 release that changes an interface depening on further
discussion. (Bearing in mind that my vote is non-binding, as a non-math
committer)
Stephen
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [math] 1.1 clirr report, backward compatibility
Posted by Mark Diggory <md...@gmail.com>.
I would initially agree, but Math is still in early development (our
second minor release). I really doubt anyone has created any alternate
implementations of these interfaces that are in any production env. I
think Math is for the time being an implementation, not a standard. If
others were implementing any of our API's I think we would have found
out by now. I don't think we can guarantee that these apis will not
change over time, there is no "Standard" agreed upon for them outside of
Commons Math, there was no committee that said, this is what the "Math
API" will look like as in the way something like JAXP has arisen...
So I'll ask again, when is the appropriate time to add methods to an
interface? Seems your suggesting "never". I disagree, I believe that in
our case these modifications can be made and the result will be a major
version release, so I would say these changes go into 2.0, if we don't
want them in 1.1 then role them back temporarily for the release, or
better yet, tag the release in the cvs and move the tag on the
appropriate files prior to this change.
Finally, I think that a defining both the Interface and a Implementation
"stub", having third parties implement the stub to implement/extend the
API gives us the power to do such changes on minor revisions without
"breaking" anyones build in the future.
-Mark
Stephen Colebourne wrote:
> Were I a voting member of [math] I would -1 such an incompatible
> change to an interface. Interfaces need to be considered sacrosanct
> and unchangable, no matter how painful that is. This is particularly
> important in a high profile project like commons, where errors cause
> serious implications to users.
>
> We have got this wrong before:
> - lang 2.0 deliberately changed the semantics of isEmpty. At least
> major OSS user stopped using the library as a result.
> - collections 3.0 accidentally changed IteratorUtils.EMPTY_ITERATOR.
> Many OSS users still have a bad view of collections as a result.
>
> Although the causes were different, the effect was the same. Thats why
> we should be running a tool like clirr for each commons release. As,
> I've said before, commons needs to strive to be whiter than white.
>
> Lets not to get it wrong again when we have found the issue.
>
> Stephen
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: commons-dev-help@jakarta.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [math] 1.1 clirr report, backward compatibility
Posted by Stephen Colebourne <sc...@btopenworld.com>.
Mark Diggory wrote:
> So, when (which version) would we make this methods available? I'm
> concerned that this report suggests that adding methods to an interface
> is breaking backward compatibility. When I think the opposite, in that
> its breaking "forwards compatibility" of existing application. You tend
> to need to break forwards compatibility to make progress on an API's
> design.
>
> In out case, adding these methods should only effect a small subset of
> the user base (specifically those who may have extended either the
> interface or the implementation on their own, effecting them because the
> signatures may be incompatible). I'm not even sure if we have anyone in
> our userbase actually doing this...
Were I a voting member of [math] I would -1 such an incompatible change
to an interface. Interfaces need to be considered sacrosanct and
unchangable, no matter how painful that is. This is particularly
important in a high profile project like commons, where errors cause
serious implications to users.
We have got this wrong before:
- lang 2.0 deliberately changed the semantics of isEmpty. At least major
OSS user stopped using the library as a result.
- collections 3.0 accidentally changed IteratorUtils.EMPTY_ITERATOR.
Many OSS users still have a bad view of collections as a result.
Although the causes were different, the effect was the same. Thats why
we should be running a tool like clirr for each commons release. As,
I've said before, commons needs to strive to be whiter than white.
Lets not to get it wrong again when we have found the issue.
Stephen
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [math] 1.1 clirr report, backward compatibility
Posted by Mark Diggory <md...@gmail.com>.
Very cool Phil,
So, when (which version) would we make this methods available? I'm
concerned that this report suggests that adding methods to an interface
is breaking backward compatibility. When I think the opposite, in that
its breaking "forwards compatibility" of existing application. You tend
to need to break forwards compatibility to make progress on an API's
design.
In out case, adding these methods should only effect a small subset of
the user base (specifically those who may have extended either the
interface or the implementation on their own, effecting them because the
signatures may be incompatible). I'm not even sure if we have anyone in
our userbase actually doing this...
Stray Thoughts:
1.) Should versioning drive development or vis versa (maybe we're
already working on 2.0 if we're breaking compatibility with 1.0)?
2.) I've been dealing with versioning on another project lately, we
adopted the following standard versioning scheme
xx.yy.zz
where
xx: Major version number incremented when major backward incompatible
changes occur.
yy: Minor version number incremented when forwards incompatible changes
occur
zz: Patch version number, incremented when changes neither cause
forwards or backwards incompatibility,
3.) Maybe we should consider making the Interfaces "final"? This would
stop users from extending them and allow us more room to make
additions/removals to the interfaces without the above usecase I
initially referred to occurring above...
-Mark
Phil Steitz wrote:
>A clirr report comparing 1.0 and 1.1-dev is available here:
>
>http://people.apache.org/~psteitz/math-1.1-clirr.txt
>
>The ERRORs shown are due to the addition of the submatrix methods to
>the RealMatrix and BigMatrix interfaces. I would like to remove the
>interface changes (leaving the new methods in the impls) to preserve
>compatibility. Any objections to this? Any other problems?
>
>Phil
>
>---------------------------------------------------------------------
>To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
>For additional commands, e-mail: commons-dev-help@jakarta.apache.org
>
>
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [math] 1.1 clirr report, backward compatibility
Posted by Mark Diggory <md...@gmail.com>.
Sure this sounds fine for the current case.
Yet another idea. I notice that sometimes API's will use an abstract
"Adapter" strategy where those publishing a "standard" interface will
also provide an "Adapter" or default implementation with a stubbed out
implementation. Such an Adapter or "Stub" acts as a SPI for any third
parties implementing the API.
The power of this is that you can add methods into the Interface in
minor versions and implement "stubs" for them, then third party
implementations are still backwards/forwards compatible because they
inherit the stub. It is then the third parties job to move their
implementation forward by implementing the stubs.
For instance in our implementation of BigMatrix/Matrix, we would direct
the third parties not to implement these interfaces directly, but to
override the stub we provide as a backed SPI to the API.
Either way, have a good flight and we'll chat again later...
-Mark
Phil Steitz wrote:
>About to get on a plane, so may not be able to respond to follow ups
>for a day or two, but my plan was to leave the methods in the
>implementations, but remove from the interfaces (so the methods would
>be there to use, you would just have to cast or use the impls
>directly. I think it is best to stick with the more or less standard
>practice in commons and keep 1.x all binary compatible, with only 2.0
>allowed to break anything. Even if we made the interface final, the
>problem would be breaking those who *implemented* the interface
>without the new methods. I will think about this some more and am
>open to any other creative suggestions that anyone has on how to
>handle this.
>
>Phil
>
>On 6/12/05, Mark Diggory <md...@gmail.com> wrote:
>
>
>>Very cool Phil,
>>
>>So, when (which version) would we make this methods available? I'm
>>concerned that this report suggests that adding methods to an interface
>>is breaking backward compatibility. When I think the opposite, in that
>>its breaking "forwards compatibility" of existing application. You tend
>>to need to break forwards compatibility to make progress on an API's
>>design.
>>
>>In out case, adding these methods should only effect a small subset of
>>the user base (specifically those who may have extended either the
>>interface or the implementation on their own, effecting them because the
>>signatures may be incompatible). I'm not even sure if we have anyone in
>>our userbase actually doing this...
>>
>>Stray Thoughts:
>>
>>1.) Should versioning drive development or vis versa (maybe we're
>>already working on 2.0 if we're breaking compatibility with 1.0)?
>>
>>2.) I've been dealing with versioning on another project lately, we
>>adopted the following standard versioning scheme
>>
>>xx.yy.zz
>>
>>where
>>
>>xx: Major version number incremented when major backward incompatible
>>changes occur.
>>yy: Minor version number incremented when forwards incompatible changes
>>occur
>>zz: Patch version number, incremented when changes neither cause
>>forwards or backwards incompatibility,
>>
>>3.) Maybe we should consider making the Interfaces "final"? This would
>>stop users from extending them and allow us more room to make
>>additions/removals to the interfaces without the above usecase I
>>initially referred to occurring above...
>>
>>-Mark
>>
>>Phil Steitz wrote:
>>
>>
>>
>>>A clirr report comparing 1.0 and 1.1-dev is available here:
>>>
>>>http://people.apache.org/~psteitz/math-1.1-clirr.txt
>>>
>>>The ERRORs shown are due to the addition of the submatrix methods to
>>>the RealMatrix and BigMatrix interfaces. I would like to remove the
>>>interface changes (leaving the new methods in the impls) to preserve
>>>compatibility. Any objections to this? Any other problems?
>>>
>>>Phil
>>>
>>>---------------------------------------------------------------------
>>>To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
>>>For additional commands, e-mail: commons-dev-help@jakarta.apache.org
>>>
>>>
>>>
>>>
>>>
>>>
>>---------------------------------------------------------------------
>>To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
>>For additional commands, e-mail: commons-dev-help@jakarta.apache.org
>>
>>
>>
>>
>
>---------------------------------------------------------------------
>To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
>For additional commands, e-mail: commons-dev-help@jakarta.apache.org
>
>
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [math] 1.1 clirr report, backward compatibility
Posted by Phil Steitz <ph...@gmail.com>.
About to get on a plane, so may not be able to respond to follow ups
for a day or two, but my plan was to leave the methods in the
implementations, but remove from the interfaces (so the methods would
be there to use, you would just have to cast or use the impls
directly. I think it is best to stick with the more or less standard
practice in commons and keep 1.x all binary compatible, with only 2.0
allowed to break anything. Even if we made the interface final, the
problem would be breaking those who *implemented* the interface
without the new methods. I will think about this some more and am
open to any other creative suggestions that anyone has on how to
handle this.
Phil
On 6/12/05, Mark Diggory <md...@gmail.com> wrote:
> Very cool Phil,
>
> So, when (which version) would we make this methods available? I'm
> concerned that this report suggests that adding methods to an interface
> is breaking backward compatibility. When I think the opposite, in that
> its breaking "forwards compatibility" of existing application. You tend
> to need to break forwards compatibility to make progress on an API's
> design.
>
> In out case, adding these methods should only effect a small subset of
> the user base (specifically those who may have extended either the
> interface or the implementation on their own, effecting them because the
> signatures may be incompatible). I'm not even sure if we have anyone in
> our userbase actually doing this...
>
> Stray Thoughts:
>
> 1.) Should versioning drive development or vis versa (maybe we're
> already working on 2.0 if we're breaking compatibility with 1.0)?
>
> 2.) I've been dealing with versioning on another project lately, we
> adopted the following standard versioning scheme
>
> xx.yy.zz
>
> where
>
> xx: Major version number incremented when major backward incompatible
> changes occur.
> yy: Minor version number incremented when forwards incompatible changes
> occur
> zz: Patch version number, incremented when changes neither cause
> forwards or backwards incompatibility,
>
> 3.) Maybe we should consider making the Interfaces "final"? This would
> stop users from extending them and allow us more room to make
> additions/removals to the interfaces without the above usecase I
> initially referred to occurring above...
>
> -Mark
>
> Phil Steitz wrote:
>
> >A clirr report comparing 1.0 and 1.1-dev is available here:
> >
> >http://people.apache.org/~psteitz/math-1.1-clirr.txt
> >
> >The ERRORs shown are due to the addition of the submatrix methods to
> >the RealMatrix and BigMatrix interfaces. I would like to remove the
> >interface changes (leaving the new methods in the impls) to preserve
> >compatibility. Any objections to this? Any other problems?
> >
> >Phil
> >
> >---------------------------------------------------------------------
> >To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
> >For additional commands, e-mail: commons-dev-help@jakarta.apache.org
> >
> >
> >
> >
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: commons-dev-help@jakarta.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [math] 1.1 clirr report, backward compatibility
Posted by Mark Diggory <md...@gmail.com>.
Very cool Phil,
So, when (which version) would we make this methods available? I'm
concerned that this report suggests that adding methods to an interface
is breaking backward compatibility. When I think the opposite, in that
its breaking "forwards compatibility" of existing application. You tend
to need to break forwards compatibility to make progress on an API's
design.
In out case, adding these methods should only effect a small subset of
the user base (specifically those who may have extended either the
interface or the implementation on their own, effecting them because the
signatures may be incompatible). I'm not even sure if we have anyone in
our userbase actually doing this...
Stray Thoughts:
1.) Should versioning drive development or vis versa (maybe we're
already working on 2.0 if we're breaking compatibility with 1.0)?
2.) I've been dealing with versioning on another project lately, we
adopted the following standard versioning scheme
xx.yy.zz
where
xx: Major version number incremented when major backward incompatible
changes occur.
yy: Minor version number incremented when forwards incompatible changes
occur
zz: Patch version number, incremented when changes neither cause
forwards or backwards incompatibility,
3.) Maybe we should consider making the Interfaces "final"? This would
stop users from extending them and allow us more room to make
additions/removals to the interfaces without the above usecase I
initially referred to occurring above...
-Mark
Phil Steitz wrote:
>A clirr report comparing 1.0 and 1.1-dev is available here:
>
>http://people.apache.org/~psteitz/math-1.1-clirr.txt
>
>The ERRORs shown are due to the addition of the submatrix methods to
>the RealMatrix and BigMatrix interfaces. I would like to remove the
>interface changes (leaving the new methods in the impls) to preserve
>compatibility. Any objections to this? Any other problems?
>
>Phil
>
>---------------------------------------------------------------------
>To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
>For additional commands, e-mail: commons-dev-help@jakarta.apache.org
>
>
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org