[Zope-dev] Re: Future of ZClasses

[Jean-Marc Orliaguet]

Patrick Gerken wrote:
> On 10/2/06, Olavo Santos <lists at varkala.net> wrote:
>>     Just a quick side note.
>>
>>     Many "deprecation sign for any user" are clearly signs that Zope
>> developers are unable to maintain certain Zope features. This is bad,
>> specially for guys that have to manage large, complex and long time 
>> running
>> zope installations ( think years ). And a "no sir, next app!" for 
>> guys like
>> us who have to choose opensource development platforms for the long 
>> run (
>> again: think years ).
>
> Well, though nothing is perfect in Zope world, I think we are quite
> good in having a policy about deprecation which already gives a
> guaranteed timelime for deprecation.
> I wanted to find a deprecation policy for eclipse and JBoss to
> compare. For JBoss i did not find such a thing, for eclipse I did not
> find a eclipse framework one, but one for some sub projects:
> http://www.eclipse.org/webtools/adopters/#non-api-code-deprecation-policy
>
> and somehow this popped up in the eclipse search result:
> http://maven.apache.org/development/deprecation.html
>
> Notice especially how they mention that a deprecation phase can be days.
> So for me it looks we are actually a bit ahead of the competition, but
> maybe somebody can correct me.
>
> Accidently I lately tripped over an article from Martin Fowler about 
> this topic:
> http://www.martinfowler.com/ieeeSoftware/published.pdf
>
> I think we use Interfaces in Z3 to "publish" Methods. So "maybe" it
> makes sense to have a smaller core API with longer deprecation
> periods, so that standard projects can try to rely on core API with
> long deprecation phase and extender would use the one year deprecation
> phase. But as I said earlier, I think we are quite ahead already.
>
> I guess the motivation of this API stability discussion is also
> motivated by JMOs comment about how much more stable is the Java API,
> in Point 2 and 3 of this entry:
> http://www.z3lab.org/sections/blogs/jean-marc-orliaguet/2006_09_23_times-they-changin 
>
>
> But it is not fair to compare the stability of a programming language
> standard modules API with a application framework api. But maybe I am
> not good in searching and somebody points me to the well thought out
> JBoss or Websphere deprecation policy
>
> best regards,
>
>           Patrick

Everyone deprecates stuff, this is not the question. But what is marked 
as 'stable', 'official' or 'standard' may not be deprecated in the same 
way as something that is still under development or private. It is more 
a question of defining and maintaining a contract with API users than a 
question of technicalities (how often to deprecate, what version numbers 
to use, how to inform...)

This is all about defining and maintaining a social contract with the 
user. No one prevents you from deprecating parts of an API that is 
marked as being "under development" or "private" -- as long as you say 
it from the start.

Check out for instance: 
http://openide.netbeans.org/tutorial/api-design.html especially the 
chapter "Life-cycle of an API"

What is unclear in zope is what is "official", what is "stable", what is 
still "under development", etc. It seems that all the different packages 
have the same status, or rather that they have no status. Apart from the 
packages that were added recently (zc. ...) there is no information in 
the repository about the quality of the different APIs. There are no 
version numbers on the packages either so I don't know what is alpha, 
beta, or final. It gives the impression that the framework is stable, 
but not mature.

I'd expect that the API defined in the 'interfaces.py' files for 
instance are 'official' in the sense that there is a commitment that the 
API is ready and that it won't change until the next major version, but 
I doubt that this is understood by everyone putting stuff into these files.

in Java, you can mark a class as 'final', meaning that no one will be 
able to subclass it, or methods can be marked as 'private'. Abstract 
classes can specify the methods that must be implemented. Also if a 
class says that it implements an interface it has to implement it 
otherwise the code won't compile.

Again this is all about defining contracts.

Considering the standard JBoss modules, there is no way to compare with 
zope really since they strive to implement the specifications thoroughly 
(EJB3, JSR-168, ...) and the APIs are final already, so they don't change.

For other modules (e.g. Seam) users are fully aware that parts of the 
specs may change. For more mature modules such as Hibernate, I am not 
aware that the API changes between minor versions.

best regards

/JM