RE: goals proposal: minimize public APIs and freeze API only after m2"1.0 release"

[Vincent Massol <vm...@pivolis.com>]

Actually I would go one step further and propose to clearly delimitate
user public API/SPI from non-user public API/SPI. This is what I've
started doing in Cactus land and I'm very happy with it:

http://jakarta.apache.org/cactus/participating/apis.html

We've also listed the public API/SPI in the javadoc using groups:

http://jakarta.apache.org/cactus/api/framework-13/

What do you think about using some "internal" and "spi" packages to
delimitate non-public API/SPI?

Thanks
-Vincent

> -----Original Message-----
> From: Jerome Lacoste [mailto:jerome@coffeebreaks.org]
> Sent: 08 June 2004 03:34
> To: Maven 2 Developers List
> Subject: goals proposal: minimize public APIs and freeze API only
after
> m2"1.0 release"
> 
> Hi,
> 
> One of small patch on m1 was rejected because of touching a public
API.
> 
> The method wasn't used in the code, perhaps for a while. In one way
> that's strange before a 1.0 release.
> 
> I propose as design goals for m2 to
> - minimize the use of public methods and classes, and to make use of
> package private wherever possible.
> - allow for API freeze only after release of version 1.0.
> 
> This should be an early goal and early statement from the project,
> allowing for more flexibility in the future.
> 
> Jerome

RE: goals proposal: minimize public APIs and freeze API only afterm2"1.0 release"

[Jerome Lacoste <je...@coffeebreaks.org>]

On Wed, 2004-06-09 at 04:05, Vincent Massol wrote:
> Hi Jerome,
> 
> I have thought about the javadoc custom tag but in my opinion it doesn't
> work well. We've even tried it on Cactus. It's a good idea in theory but
> in practice the problem is that it's too fine-grained and thus too
> difficult to maintain.
> 
> -Vincent

I had that feeling. I reread your proposal, and I like it.

There are 2 types of reuse:
- the reuse to interact with the application
- the reuse to reuse some functionality

we can then perhaps combine your proposal with something saying if you want to interact, use the API/SPI components (most usualy interfaces).
If you want to interact with functionality, only reuse things that are in the util package, but do it at your own risk as ascendant compatibility is not 100% guaranteed.
These util classes and methods will go through a deprecated policy anyway before they change.

Jerome

RE: goals proposal: minimize public APIs and freeze API only afterm2"1.0 release"

[Vincent Massol <vm...@pivolis.com>]

Hi Jerome,

I have thought about the javadoc custom tag but in my opinion it doesn't
work well. We've even tried it on Cactus. It's a good idea in theory but
in practice the problem is that it's too fine-grained and thus too
difficult to maintain.

-Vincent

> -----Original Message-----
> From: Jerome Lacoste [mailto:jerome@coffeebreaks.org]
> Sent: 08 June 2004 18:13
> To: Maven 2 Developers List
> Subject: RE: goals proposal: minimize public APIs and freeze API only
> afterm2"1.0 release"
> 
> On Tue, 2004-06-08 at 04:58, Vincent Massol wrote:
> > Actually I would go one step further and propose to clearly
delimitate
> > user public API/SPI from non-user public API/SPI. This is what I've
> > started doing in Cactus land and I'm very happy with it:
> >
> > http://jakarta.apache.org/cactus/participating/apis.html
> >
> > We've also listed the public API/SPI in the javadoc using groups:
> >
> > http://jakarta.apache.org/cactus/api/framework-13/
> >
> > What do you think about using some "internal" and "spi" packages to
> > delimitate non-public API/SPI?
> 
> I had a similar idea, but in a different way. I didn't propose it
> because I've never seen it employed in the field.
> 
> The problem as I perceive it is that modifiers have 2 use/meanings:
they
> define the public API (and thus automatically define reuse from other
> clients) and provide encapsulation means.
> 
> But we might want a method/class/... to be public for internal code
> management, but not allow someone from the outside to reuse it,
because
> we know it won't be stable.
> 
> What would be nice is to be able to split that in a finer grained way.
> So perhaps if we were to add a javadoc keyword limiting the meaning of
> the public keyword for classes/methods/... E.g. @internal.
> Classes/methods/... tagged that way would mean that they are public
for
> internal use within the program, but their potential use outside the
> program is risky, as the interface might change.
> 
> I haven't seen used before, but I wouldn't mind maven2 to innovate :)
> 
> Vincent, as you have introduced your internal/spi notations in Cactus,
> do you see cases in which my proposal would solve some problems that
> your solution was not able to handle?
> 
> Maybe it's too complex. Comments?
> 
> Jerome

RE: goals proposal: minimize public APIs and freeze API only after m2"1.0 release"

[Jerome Lacoste <je...@coffeebreaks.org>]

On Tue, 2004-06-08 at 04:58, Vincent Massol wrote:
> Actually I would go one step further and propose to clearly delimitate
> user public API/SPI from non-user public API/SPI. This is what I've
> started doing in Cactus land and I'm very happy with it:
> 
> http://jakarta.apache.org/cactus/participating/apis.html
> 
> We've also listed the public API/SPI in the javadoc using groups:
> 
> http://jakarta.apache.org/cactus/api/framework-13/
> 
> What do you think about using some "internal" and "spi" packages to
> delimitate non-public API/SPI?

I had a similar idea, but in a different way. I didn't propose it
because I've never seen it employed in the field.

The problem as I perceive it is that modifiers have 2 use/meanings: they
define the public API (and thus automatically define reuse from other
clients) and provide encapsulation means.

But we might want a method/class/... to be public for internal code
management, but not allow someone from the outside to reuse it, because
we know it won't be stable.

What would be nice is to be able to split that in a finer grained way.
So perhaps if we were to add a javadoc keyword limiting the meaning of
the public keyword for classes/methods/... E.g. @internal.
Classes/methods/... tagged that way would mean that they are public for
internal use within the program, but their potential use outside the
program is risky, as the interface might change. 

I haven't seen used before, but I wouldn't mind maven2 to innovate :)

Vincent, as you have introduced your internal/spi notations in Cactus,
do you see cases in which my proposal would solve some problems that
your solution was not able to handle?

Maybe it's too complex. Comments?

Jerome