[Bf-committers] BGE API Proposal

[José Ignacio Romero]

El jue, 19-02-2009 a las 02:37 -0800, Roger Wickes escribió:
> I think the issue is whether or not to preserve old API calls. We
> could either append a version suffix to the call, or accept a version
> parameter, as a means of ensuring scripts don't break with every new
> release. For example, it is possible to append a suffix to an API
> call, such as 
> 
> myob=camera.New_248(type='persp', name='CamData')
> 
> and then that way, if the API for camera.New changes to like, using an
> ordinal instead of a literal, it becomes camera.New_250(type=PERSP,
> name='CamData') where PERSP is a constant. I personally don't like
> that approach, but have seen it done.
> 
> What I do like is passing the API version as a parameter, and let the
> API then check and invoke the appropriate code, such as:
> 
> APIVER=248
> 
> and then
> 
> myob=camera.New(type='persp', name='CamData', apiver=APIVER)
> 
> assuming the apiver is an integer and variable parameter. I like
> integer as it allows easy code checking within the API itself. As a
> script is certified and upgraded to work with a new API, a simple line
> change invokes the new api calls. There is only one line to change (up
> front), instead of many. As older api calls get logically depricated
> or impossible to preserve, the code can simply if apiver<248 return
> ('api %s no longer supported for version %i') to the console and
> stop. 
> 
> For scripts that use multiple API versions, something like
> 
> APIVER=250
> APIOLD=248 'for new api calls I haven't gotten around to figuring out
> 
> and then
> 
> camera.New(type='persp', name='CamData', apiver=APIVER)
> myob=camera.Get(name=None, apiver=APIOLD)
> 
> where, for example, the new API for Get looks like the old interface,
> but returns, say, a linked list or something different that the
> programmer either can't figure out yet, or doesn't need/want. 
> 
> In summary, the frustration is that an API change breaks working code,
> and so scripters have to fix code that breaks with every release, a
> maintenance nightmare. If the API maintainer does not want or cannot
> maintain backward compatibility, the api just tightens up the version
> check and disallows anything less than the current release number.
> 
> Just a suggestion. I am not an API maintainer, but I am a pig.
> 

-1 (for keeping the clutter in 2.50)
> 
> ______________________________________________________________________
- The current BGE api has survived way too much time being as shitty as
it is, I'd like to hear of a BGE project that would take more than a
couple of hours to upgrade (and with a good reason to do so, i mean, why
not stay with 2.48/9 if the game is complete/near to be?)

- The reason we want a 2.49 release is to give the users an opportunity
to upgrade painlessly (all api deprecations are marked and suggestions
given to change) pretty much like python 2.6 is to python .

- Breaking compatibility once doesn't mean we will do in each release,
dont carry it to an extreme. Also, most BGE users (at least what i got
from BA) are encouraged to stay with a certain version of blender
through the development of the whole game, unless they want to be
constantly fixing stuff that breaks. I've been developing a game with
the BGE since 2.45, upgrading with each release, and i had to start
again 3 times, because some stuff broke/much better stuff came out.
actually the only thing that didn't break too much was the Python API.

- I understand the books issue, but again the gamekit was written for
2.48(a) why wouldn't the user stay with the version that came with the
book? i mean, 2.50 already makes many changes, it makes several books
obsolete. Same thing with 2.46 and its new method of working with UVs (i
tried to give a teammate an UV tutorial and it took me some time to find
an updated one, most were for blender<=2.45)