Re: [transaction] svn commit: r494203 - in /jakarta/commons/proper/transaction/trunk: RELEASE-NOTES.txt src/java/org/apache/commons/transaction/file/ResourceManager.java

[Simon Kitching <sk...@apache.org>]

On Wed, 2007-01-10 at 14:12 -0500, Rahul Akolkar wrote:
> On 1/10/07, Joerg Heinicke <jo...@gmx.de> wrote:
> > Rahul Akolkar <rahul.akolkar <at> gmail.com> writes:
> >
> > > > "Generally speaking, an interface-compatible change will at most change the
> > > > private interface of a component, or simply add classes, methods and
> > > > attributes whose use is optional to both internal and external interface
> > > > clients."
> > >
> > > And this is not.
> >
> > In which way is it different from "simply add [..] methods [..] whose use is
> > optional to both internal and external interface clients." ??
> >
> > Even simply replacing the former jar with the next version should work as the
> > client does not know about the new methods. Only recompilation of
> > implementations need adaptions before but that's not what I consider a "use" or
> > a "client".
> >
> <snip/>
> 
> I suspect that bit is talking about Java classes (rather than
> interfaces), though I haven't tried to hunt it down in the guide. I
> flagged what I thought would lead to a versioning discussion at 1.2
> voting time. 

There is a section in the java specification that defines precisely what
"binary compatibility" involves, and adding a method to an interface
definitely breaks it.

This is an *object oriented* library we are talking about here, so "use"
includes implementing any public interfaces, subclassing any non-final
classes and overriding any public or protected methods. Unless
explicitly documented, we cannot assume that "users" of an open-source
library restrict themselves to just calling the existing classes.

If the interfaces had been explicitly documented as being "not intended
for user implementation" then this might be ok. Or if they had been
placed in a special package, as Eclipse does, to explicitly separate
internal from external apis. However if neither of these have been done,
then I would personally expect these APIs to be binary-compatible, *at
least* without a major version number update.

In the branch for digester 2.x, I explicitly indicated the binary
stability expectations for the Action interface:
http://svn.apache.org/repos/asf/jakarta/commons/proper/digester/branches/digester2/src/java/org/apache/commons/digester2/Action.java
Note that this is still experimental work, and I haven't received
feedback from the commons community on whether this sort of comment
would be considered adequate to allow an interface change in a minor
release, but IMO without an indication of this sort an API really
shouldn't change (without a major release at least).

Ideally, existing public interfaces should not be changed *at all*, eg
by introducing a new interface rather than changing the existing one. In
cases where an application uses two different libraries that both depend
on a commons lib, the existence of different versions of the commons lib
with the same package names but different APIs can cause major
headaches. 

As Rahul says this situation may well draw -1 votes at release time. We
all want commons projects to have a good reputation for API stability.
There have been mistakes made in the past, causing a lot of negative
user feedback. Yes, it can be a hassle for development. However the
reason that commons is a good place to host libraries is because commons
is trusted, and that's because the software development processes here
are reasonably strict. Writing libraries is hard - and quite different
from writing full applications (eg tomcat, ant) or frameworks.

Regards,

Simon


---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org

Re: [transaction] svn commit: r494203 - in /jakarta/commons/proper/transaction/trunk: RELEASE-NOTES.txt src/java/org/apache/commons/transaction/file/ResourceManager.java

[Oliver Zeigermann <ol...@gmail.com>]

Folks!

Thanks for caring that much and sorry for me being quiet until now as
I am the guilty person.

The design we are talking about actually is quite weird as it is a
stub of a former implementation. There is this interface and there is
*exactly* one implementation for that interface and IMHO there will be
no - reasonable - further implementation at any time. Thus it is
alright to extend the interface.

Even if you do not agree we should at least add the additional methods
to the implementation, leaving the interface untouched, breaking
nothing!

OK?

Cheers and have a nice weekend

Oliver

2007/1/11, Simon Kitching <sk...@apache.org>:
> On Wed, 2007-01-10 at 14:12 -0500, Rahul Akolkar wrote:
> > On 1/10/07, Joerg Heinicke <jo...@gmx.de> wrote:
> > > Rahul Akolkar <rahul.akolkar <at> gmail.com> writes:
> > >
> > > > > "Generally speaking, an interface-compatible change will at most change the
> > > > > private interface of a component, or simply add classes, methods and
> > > > > attributes whose use is optional to both internal and external interface
> > > > > clients."
> > > >
> > > > And this is not.
> > >
> > > In which way is it different from "simply add [..] methods [..] whose use is
> > > optional to both internal and external interface clients." ??
> > >
> > > Even simply replacing the former jar with the next version should work as the
> > > client does not know about the new methods. Only recompilation of
> > > implementations need adaptions before but that's not what I consider a "use" or
> > > a "client".
> > >
> > <snip/>
> >
> > I suspect that bit is talking about Java classes (rather than
> > interfaces), though I haven't tried to hunt it down in the guide. I
> > flagged what I thought would lead to a versioning discussion at 1.2
> > voting time.
>
> There is a section in the java specification that defines precisely what
> "binary compatibility" involves, and adding a method to an interface
> definitely breaks it.
>
> This is an *object oriented* library we are talking about here, so "use"
> includes implementing any public interfaces, subclassing any non-final
> classes and overriding any public or protected methods. Unless
> explicitly documented, we cannot assume that "users" of an open-source
> library restrict themselves to just calling the existing classes.
>
> If the interfaces had been explicitly documented as being "not intended
> for user implementation" then this might be ok. Or if they had been
> placed in a special package, as Eclipse does, to explicitly separate
> internal from external apis. However if neither of these have been done,
> then I would personally expect these APIs to be binary-compatible, *at
> least* without a major version number update.
>
> In the branch for digester 2.x, I explicitly indicated the binary
> stability expectations for the Action interface:
> http://svn.apache.org/repos/asf/jakarta/commons/proper/digester/branches/digester2/src/java/org/apache/commons/digester2/Action.java
> Note that this is still experimental work, and I haven't received
> feedback from the commons community on whether this sort of comment
> would be considered adequate to allow an interface change in a minor
> release, but IMO without an indication of this sort an API really
> shouldn't change (without a major release at least).
>
> Ideally, existing public interfaces should not be changed *at all*, eg
> by introducing a new interface rather than changing the existing one. In
> cases where an application uses two different libraries that both depend
> on a commons lib, the existence of different versions of the commons lib
> with the same package names but different APIs can cause major
> headaches.
>
> As Rahul says this situation may well draw -1 votes at release time. We
> all want commons projects to have a good reputation for API stability.
> There have been mistakes made in the past, causing a lot of negative
> user feedback. Yes, it can be a hassle for development. However the
> reason that commons is a good place to host libraries is because commons
> is trusted, and that's because the software development processes here
> are reasonably strict. Writing libraries is hard - and quite different
> from writing full applications (eg tomcat, ant) or frameworks.
>
> Regards,
>
> Simon
>
>
> ---------------------------------------------------------------------
> 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