[Bioperl-l] API Changes

[Nathan S. Haigh]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Chris Fields wrote:
> 
> 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.

Hmm, still not 100% clear - it is Friday!

So, someone running a script that was designed when 1.4 was released
should still be able to run their script for all future releases. So all
changes need to be backward compatible?

So you have several situations regarding method names:
1) Adding new methods should e fine since past scripts don't know about
them and won't have used them
2) Removing methods would break past scripts that used them
3) Renamed methods would break past scripts that used the old name

A stable API to me, means the same method calls should still be able to
accept the same arguments (inc the constructor) and return the same
object/data etc.

What if a module is pretty outdated and would benefit from a rewrite -
should all the old method names be included, what if this makes coding
difficult?

> 
> 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!
> 

You mean the use of case to signify objects vs data being returned are
to be deprecated or encouraged? What was the outcome of the each_* vs
next_*?

Nath



-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFGjmGvczuW2jkwy2gRAkGeAKDBXVSBvN0b39xbK1+2RLed35knSQCgz3pk
kAWH1zVa1ycopijl761cvkQ=
=fppH
-----END PGP SIGNATURE-----