[KinoSearch] Stable releases under new namespaces

[webmasters at ctosonline.org]

On Mar 12, 2010, at 10:16 AM, Marvin Humphrey wrote:
> I'd been thinking that "KinoSearch" would have a perpetually  
> unstable API, and
> that we'd abandon all pretense that it would ever be stable.   
> However, we
> could do as you say here and break API compatibility only at major  
> release
> points -- however, to avoid abandoning the earlier user base  
> completely, we'd
> spin off a renamed stable branch at each back-compat break.
>
> If we did that, CPAN would look like this right away:
>
>   KinoSearch1 1.00    <-- branches/ks1
>   KinoSearch  1.00    <-- identical to branches/ks1 except for  
> namespace
>   KinoSearch  3.00_01 <-- trunk
>
> We would then work to get trunk ready for a real version 3 release.   
> Once it
> was published, CPAN would look like this:
>
>   KinoSearch1 1.00    <-- branches/ks1
>   KinoSearch  3.00    <-- branches/maint-3.x
>   KinoSearch  4.00_01 <-- trunk
>
> Then, in a year or so[2] when we release KinoSearch 4, CPAN would  
> look like
> this:
>
>   KinoSearch1 1.00    <-- branches/ks1
>   KinoSearch3 3.00    <-- branches/ks3
>   KinoSearch  4.00    <-- branches/maint-4.x
>   KinoSearch  5.00_01 <-- trunk

One of the problems with this approach is that, if I want to use  
KinoSearch 4.00 stable, I would have to start with ‘KinoSearch’ and  
later migrate my code to ‘KinoSearch4’.

Another problem with the all the multiple namespace suggestions so far  
is that it makes it hard for KSx:: authors. How would I write a KSx::  
module that works with multiple KinoSearch versions? Would I have to  
keep releasing a new KS3x:: or KS4x:: whenever there is a new  
KinoSearch release?

I have a suggestion, which I think would make it much easier for  
script authors, and a little easier for module authors:

Perhaps the ‘KinoSearch’ namespace could be a front end that delegates  
to a separate namespace. So ‘use KinoSearch 3;’ or ‘use KinoSearch api  
=> 3’ would alias all the KinoSearch namespaces to KinoSearch3:: or  
KinoSearch::3:: for that process (or thread). Then a KSx module can  
call KinoSearch->api or api_version (perhaps this method could be on  
every object under KinoSearch::) to find out which version is being  
used. If a process needs to access multiple KinoSearch versions, it  
can use KinoSearch3 directly.

Using KinoSearch without specifying a version will default to the  
latest, with a warning. ‘api => "*"’, ‘api => 0’ or ‘api => "latest"’  
could be used to suppress the warning.

Now, for this to work seamlessly, all KinoSearch versions would have  
to be bundled along with the latest, which is a bit much. I think  
clear documentation that explains that KinoSearch2/3 needs to be  
installed separately (if it is an old version) is a sufficient  
compromise, as the ‘Can’t locate KinoSearch2.pm in @INC’ message  
explains exactly what’s wrong.


Right now I’m having a maintenance nightmare, as two separate websites  
are using different versions of KinoSearch that are no longer on CPAN.  
And I haven’t had time to update the code for either of them.... And I  
need to update my KSx modules, too. I’m just looking for a way to make  
this all much easier.

Father Chrysostomos