Re: 2.0 API freeze (or lack thereof)

Geoffrey Young wrote:
> was Re: [patch] 
> s/APR::URI::default_port_for_scheme/APR::URI::port_of_scheme/
>
>
> > OK, then we have a little problem with people who have started using 
> > the old API which should be phases out. We have two choices to take:
> >
> > 1) simply change the API, removing the old one and let users adjust 
> > their code
> >
> > 2) having a phase-out process where we add Apache/deprecated.pm with 
> > all the right aliases and the first time the function is used we log 
> > to error_log the function's TTL (time-to-live), for example suggesting 
> > that all deprecated functions are to be removed by the golden release.
> >
> > Of course it's much easier to go with (1) ;)
> >
> > There were quite a few changes in the APR's API that need to be 
> > propogated to the mod_perl API. (e.g. lots of socket API changes and 
> > more).
>
>
> well, I think that this goes to the heart of of the 2.0 project - what's 
> the official line on API freeze?

First of all you have to differ between Apache API and APR API, these are two 
different beasts. Apache is not responsible for APR API per se. APR's API is 
planned to be frozen by 1.0 release (which should be one of the next releases).

I think that Apache API itself is pretty stable at this moment. All the new 
developments go into the Apache 2.1 tree.

> personally, I think it should all up for grabs until we the official 
> "2.0" release to CPAN, that it should be understood the API can change 
> without notice or back compat.

But people have already started using the existing API, so we can at least try 
to make their upgrades less painful.

> as I play around with 2.0, there still seem to be lots of unfinished 
> (filters) 

Which ones are you talking about? Other than the TIE interface the filters API 
is pretty complete IMHO.

> and missing (finfo) parts,

That one will probably won't exist at all in mp2.

> so even more changes are 
> forthcoming, and I don't think that issues that arise while working 
> through these API changes should be hindered by back compat while we're 
> still essentially in beta (or less in some areas :)
>
> and, quoting stas from test-dev:
>
>  > In any case Apache::Test wasn't released yet, so any API
>  > changes are OK, IMHO.

The difference is that Apache::Test was never released to public in any form. 
It was coming with mp2 to run mp2's tests.

> and Apache::Test is probably more used at this point than 2.0 :)
>
> so, I guess I'm thinking that we should make the API right, especially 
> in cases where mod_perl is serving as true glue between Perl and another 
> API (like APR) and not worry too much about the consequences (for the 
> moment). however, if this is our stance, then it really needs to be 
> public, like in the INSTALL and website.

Well, I suggest that we at least maintain a file that documents the API 
changes between release versions.

__________________________________________________________________
Stas Bekman            JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/     mod_perl Guide ---> http://perl.apache.org
mailto:stas@xxxxxxxxxx http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org   http://ticketmaster.com