[Bioperl-l] API Changes

[Chris Fields]

On Jul 6, 2007, at 2:09 AM, Nathan S. Haigh wrote:

> David Messina wrote:
>>> [Chris]
>>> The 1.5 releases I believe break some aspects of 1.4 API
>>>
>>
>> Yes, this is true.
>>
>> I question, though, whether it's relevant given that virtually no one
>> uses 1.4 anymore. In any case, I would venture that the number of
>> people who would be bitten by the 1.4->1.5 API change is much smaller
>> than the number of people who download 1.4 and then ask us why it
>> doesn't work.
>>
>
> I'm not really up-to-speed with how the API should remain stable  
> etc. Is
> the idea that the API should be stable from 1.4 though the 1.5 dev and
> then the next stale release can change that API? So any stable to  
> stable
> upgrade could involve an API change while a stable to dev upgrade  
> should
> have the same API? Does a stable API mean that the same method  
> calls are
> available in a newer release....what about adding new methods to a  
> newer
> release?
>
> How are these API changes currently tracked? It seems to me that
> Test::More might be able to help in testing the API:
>
> can_ok($module, @methods);
>
>
> Nath	

It's basically a 'contract' of sorts between the devs (us) and users  
(us/them) that the API won't change for the extent of that release  
series, thus ensuring any scripts out there generating tons of data  
won't break down if they attempt to call a renamed method.  We try to  
maintain the API state anyway for those reasons, but in a dev release  
series we might decide to change some method names for consistency  
and deprecate older ambiguously-named methods (see below).  For a  
stable release it's critical the API remain intact.

There are a few methods which are considered deprecated or will be  
deprecated.  For instance, we recently talked about changes to method  
names which use case to specify whether you're receiving an object  
(get_Foo) vs. data (get_foo), a list (get_Foos), a flattened vs.  
nested list, or whether to use each_* vs next_* for iterators.   
Consistency is nice!

chris