[Bf-committers] Can we please stop breaking APIs?

Sun Jul 17 13:31:25 CEST 2011

I think this terms are becoming a bit unfair. Sure it might seem like
little insignificant fixes here and there but let it accumulate for
months and it becomes an important step up in usability. Of course we
would like the API to never break but that just can't be done,
specially by a single man. Back when we did the big gamelogic
refactor, deprecated warnings worked wonders. I'd say that's the way
to go here too. Don't let it accumulate into a second total re-write.

Daniel Salazar
3Developer.com

On Sun, Jul 17, 2011 at 5:22 AM, Jim Williams <sphere1952 at gmail.com> wrote:
> I have to agree with this completely.  If the API contract is not
> maintained then
> the API is not worth learning.  Having the API change without necessary
> reason after I've relied upon it to make something and sent it out the door
> makes the product unusable.  It is better not to try and to make things only
> for a specific release -- in this case that would be 2.49.
>
> Sounds like you made a mistake in bothering to learn the 2.5 API at all.
>
>
> On Sun, Jul 17, 2011 at 7:04 AM, Matt Ebb <matt at mke3.net> wrote:
>> I have a few things to say on this topic...
>>
>>
>> On Sat, Jul 16, 2011 at 8:37 AM, Campbell Barton <ideasman42 at gmail.com>wrote:
>>
>>> On Fri, Jul 15, 2011 at 10:35 PM, Diego B <bdiego at gmail.com> wrote:
>>> >> Nope, the api is not stable and probably wont be until blender
>>> >> development ceases.
>>> >
>>> > so.. that mean that the api never will be stable ? because blender is
>>> > always in development, like
>>> > any other software.
>>>
>>> In practice we end up stabilizing most areas and don't just break
>>> stuff indefinitely - But bigger changes mean api breakage is
>>> unavoidable in most cases - BMesh, Particle Rewrite, Curves/Nurbs
>>> branch... etc.
>>>
>>
>> I don't think it follows that because blender is always in development (like
>> any other software) that anything is up for grabs and users can never expect
>> to be able to rely on a stable API. I think most people can understand that
>> if a major part of the software changes internally, then the API may have to
>> change as well, and with a managed path of warning and deprecation, the pain
>> of transitioning can be managed.
>>
>> But this is not the sort of problem that is in question here - some of these
>> changes, which I thought would stop after the 'stable' 2.5 release, are
>> smaller, syntactic changes. They're not due to any major internal
>> reorganisations, they're not part of fixing design problems, they're little
>> things that really aren't that *necessary*.
>>
>> Like the previous change that affected me (which I only found out about when
>> things stopped working), it was moving ExportHelper from io_utils to
>> bpy_extras.io_utils. That was something that has nothing to do with
>> reflecting changes internally in blender, it was a somewhat arbitrary
>> decision to make things 'nicer' or more organised.
>>
>> >From the point of view of a developer who's involved in blender, who reads
>> every commit log, who hangs out in IRC, who knows exactly what's happening
>> in the API, this may not seem like a big deal, but for other developers
>> outside that circle, or users who just want to their tools to work when they
>> download a new blender, it's a huge difference - it's the difference between
>> something working or not working at all - there are no varying degrees of
>> difficulty here.
>>
>> Trying to make the api syntactically nice is not a bad goal on its own, but
>> it *is* a problem when it conflicts with the API's usability. And that
>> usability is not just about how much you have to type, or if the names are
>> good syntactically, it's about how much trouble it is to actually develop
>> tools with it and get work done. Having an unstable API that can change for
>> seemingly small and arbitrary reasons really damages the API's usability
>> much more than less-than-beautiful syntax or organisation does.
>>
>> So the legitimate need for having things well organised and with nice syntax
>> and naming has to be balanced with having a usable, stable API. In some
>> cases (like the one I brought up, IMO) the solution should be to just sigh,
>> and live with something that's not 100% perfect, because fixing it causes a
>> greater problem than it solves. In other cases, this can be handled with
>> deprecation, warnings, grace periods to allow people to transition.
>>
>> Agree we should deprecate in some cases - at the moment its arbitrary
>>> when to do so. Currently I just check if any addons/scripts use it and
>>> if its documented.
>>> If not, this is a reasonable indication its not widely used. (nobody
>>> complained when convert_to_pyobject() was renamed for eg.)
>>>
>>
>> This is absolutely not a reasonably indication. The fact is you really don't
>> know at all who is using this stuff out there. I've done a reasonable amount
>> with the 2.5 API now - not extensive by any means, but none of my stuff is
>> included in addons.
>>
>> The benefit of having a python API is that you don't need to spend time
>> being involved in IRC, mailing lists, etc in order to get work done
>> developing tools. Scripters and TDs can just write stuff in python and never
>> show a single other soul, or keep it for their studio to use internally, or
>> distribute it themselves on the net, or give it to a client who has hired
>> said coder to make a python tool. The API is not just to enable blender
>> developers to make included blender tools or addons in python, there's a
>> much, much wider world outside that sphere. So anything that can improve
>> interaction and communication that doesn't involve being deeply involved in
>> blender dev (eg. prior warnings in documentation, deprecation messages,
>> grace periods, etc) is very much appreciated.
>>
>> Anyway, I really appreciate the work that's being done in the API, and it is
>> miles ahead of what we had before. I just don't want to see baby thrown out
>> with the bathwater, having a API that can be considered nice at a given
>> moment in time, but is a total pain to use for real work because it's
>> constantly breaking.
>>
>> cheers
>>
>> Matt
>> _______________________________________________
>> Bf-committers mailing list
>> Bf-committers at blender.org
>> http://lists.blender.org/mailman/listinfo/bf-committers
>>
>
>
>
> --
> No essence.  No permanence.  No perfection.  Only action.
> _______________________________________________
> Bf-committers mailing list
> Bf-committers at blender.org
> http://lists.blender.org/mailman/listinfo/bf-committers
>